跳转至

面板控件 (SPanel)

基本信息

  • 类名：SPanel
  • 控件标签：panel
  • 基类：SWindow
  • 功能：提供基础容器功能

属性说明

基本属性

属性名 类型 默认值 说明
colorBkgnd color - 背景颜色
colorBorder color - 边框颜色，需要和margin一起使用

外观属性

属性名 类型 默认值 说明
skin string - 背景皮肤

布局属性

属性名 类型 默认值 说明
margin string - 边框大小，和colorBorder或者ncSkin配合使用，格式为左,上,右,下
padding string - 内边距，和inset属性相同，格式为左,上,右,下
layout string - layout，可选值：锚点布局:soui,Grid布局:gridLayout,线性水平:hbox,线性垂直:vbox
gravity string - 子控件的对齐方式，可选值：左:left,上:top,中:center,右:right,下:bottom
layout_gravity string - 相对于父控件的对齐方式，可选值：左:left,上:top,中:center,右:right,下:bottom

使用示例

基础面板

<!-- 简单面板 -->
<panel name="panel_basic" 
       pos="10,10,210,110" 
       colorBkgnd="#F0F0F0">
    <text pos="10,10" text="面板内容"/>
    <button pos="10,40,100,70" text="按钮"/>
</panel>

带皮肤的面板

<!-- 使用皮肤的面板 -->
<panel name="panel_skin" 
       pos="10,120,210,220" 
       skin="panel_background">
    <text pos="10,10" text="带皮肤的面板"/>
</panel>

布局面板

<!-- 水平布局面板 -->
<panel name="panel_layout" 
       pos="220,120,410,220" 
       layout="hbox"
       gravity="center"
       padding="10,10,10,10">
    <button text="按钮1" size="80,30"/>
    <window weight="1"/> <!-- 占位窗口 -->
    <button text="按钮2" size="80,30"/>
</panel>

## 布局系统

### 1. 布局方式

SPanel 支持多种布局方式：

#### hbox（水平布局）
```xml
<panel layout="hbox" gravity="center">
    <button size="80,30" text="按钮1"/>
    <button size="0,30" flex="1" text="弹性按钮"/>
    <button size="80,30" text="按钮2"/>
</panel>

vbox（垂直布局）

<panel layout="vbox" gravity="center">
    <button size="0,30" flex="1" text="弹性按钮"/>
    <button size="80,30" text="按钮1"/>
    <button size="80,30" text="按钮2"/>
</panel>

2. 对齐方式

gravity 属性支持以下值的组合： - left: 左对齐 - right: 右对齐 - top: 顶部对齐 - bottom: 底部对齐 - center: 居中对齐

<panel layout="hbox" gravity="center">
    <button size="80,30" text="居中按钮"/>
</panel>

3. 尺寸控制

固定尺寸

<panel size="200,100">
    <!-- 固定200x100像素 -->
</panel>

弹性尺寸

<panel layout="hbox">
    <button size="80,30" text="固定"/>
    <button size="0,30" flex="1" text="弹性"/>
</panel>

代码操作

1. 查找和操作面板

// 查找面板控件
SPanel* pPanel = FindChildByName2<SPanel>(L"panel_basic");
if(pPanel) {
    // 设置背景颜色
    pPanel->SetAttribute(L"colorBkgnd", L"#FF0000");

    // 设置皮肤
    pPanel->SetAttribute(L"skin", L"panel_skin");

    // 添加子控件
    SButton* pBtn = new SButton();
    pBtn->SetAttribute(L"text", L"动态按钮");
    pBtn->SetAttribute(L"pos", L"10,10,100,40");
    pPanel->InsertChild(pBtn);
}

2. 动态创建面板

// 创建面板
SPanel* CreatePanel()
{
    SPanel* pPanel = new SPanel();
    pPanel->SetAttribute(L"pos", L"10,10,210,110");
    pPanel->SetAttribute(L"colorBkgnd", L"#F0F0F0");

    // 添加子控件
    SStatic* pText = new SStatic();
    pText->SetAttribute(L"pos", L"10,10");
    pText->SetAttribute(L"text", L"动态创建的面板");
    pPanel->InsertChild(pText);

    return pPanel;
}

代码操作

// 查找面板控件
SPanel *pPanel = FindChildByName2<SPanel>(L"panel_basic");

// 设置背景颜色
pPanel->SetAttribute(L"colorBkgnd", L"#FFFF00");

// 设置皮肤
pPanel->SetAttribute(L"skin", L"skin_panel");

// 设置布局方式
pPanel->SetAttribute(L"layout", L"vbox");

// 设置内边距
pPanel->SetAttribute(L"padding", L"5,5,5,5");

事件处理

面板控件支持以下事件：

事件名 EventID 说明
EVT_MOUSE_HOVER EventMouse::EventID 鼠标悬停事件
EVT_MOUSE_LEAVE EventMouse::EventID 鼠标离开事件
EVT_SETFOCUS EventSetFocus::EventID 获得焦点事件
EVT_KILLFOCUS EventKillFocus::EventID 失去焦点事件 
// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_HANDLER(L"panel_basic", EventMouse::EventID, OnPanelMouseEvent)
EVENT_MAP_END()

void OnPanelMouseEvent(IEvtArgs *pEvt)
{
    // 处理鼠标事件
}

最佳实践

  1. 布局管理：使用 layout 属性实现灵活的子控件布局
  2. 样式定制：通过 skin 和 colorBkgnd 属性定制面板外观
  3. 间距控制：合理使用 padding 和 margin 控制控件间距
  4. 对齐方式：通过 gravity 和 layout_gravity 控制子控件对齐

常见问题

Q: 面板背景颜色不显示怎么办？

A: 确保没有设置 skin 属性，或检查皮肤资源是否正确。

Q: 子控件布局不正确怎么办？

A: 检查 layout 属性是否设置正确，以及子控件的尺寸和位置属性。

Q: 面板边框显示异常怎么办？

A: 确保同时设置了 colorBorder 和 margin 属性。

相关控件

应用场景

  1. 界面分区
  2. 将界面划分为不同功能区域

  3. 组织相关控件形成逻辑单元

  4. 布局管理

  5. 实现复杂的界面布局

  6. 响应式设计支持

  7. 样式容器

  8. 为子控件提供统一的背景和样式

  9. 实现视觉分组效果

  10. 动态内容

  11. 动态添加和移除子控件
  12. 实现可变界面结构