跳转至

StackView 控件 (SStackView)

StackView 是一个堆栈布局容器控件，可以将子控件按照堆栈的方式进行排列和管理。它支持水平和垂直方向的堆栈布局，可以自动调整子控件的大小和位置。

基本信息

  • 类名：SStackView
  • 控件标签：stackview
  • 基类：SPanel
  • 功能：提供堆栈布局容器功能

属性说明

SStackView（标签 stackview）是栈式布局容器，同一时刻只显示其中一个页面（<stackPage>，标签 stackPage）。页面切换可带动画。

自身属性

属性名 类型 默认值 说明
curSel int - 当前显示的页面索引
aniType enum none 切换动画：none / fade（淡入淡出）/ move（平移）/ push（推入推出）
vertical bool false 动画是否为垂直方向
samePageSize bool false 所有页面是否使用相同尺寸
animator:xxx - - 以 animator: 前缀设置切换动画器（SViewSwitchAnimator）属性

text、字体、颜色、可用、可见等通用属性见通用属性。

使用示例

垂直堆栈示例

<stackview pos="10,10,200,300" 
           name="stackVertical"
           orientation="vertical" 
           spacing="5"
           gravity="left">
    <button text="按钮1" height="30"/>
    <button text="按钮2" height="30"/>
    <button text="按钮3" height="30"/>
</stackview>

水平堆栈示例

<stackview pos="10,10,300,50" 
           name="stackHorizontal"
           orientation="horizontal" 
           spacing="10"
           gravity="center">
    <button text="按钮1" width="80"/>
    <button text="按钮2" width="80"/>
    <button text="按钮3" width="80"/>
</stackview>

居中对齐的堆栈示例

<stackview pos="10,70,300,200" 
           name="stackCenter"
           orientation="vertical" 
           spacing="10"
           gravity="center">
    <button text="居中按钮1" width="120" height="30"/>
    <button text="居中按钮2" width="120" height="30"/>
    <button text="居中按钮3" width="120" height="30"/>
</stackview>

右对齐的堆栈示例

<stackview pos="10,210,300,350" 
           name="stackRight"
           orientation="vertical" 
           spacing="5"
           gravity="right">
    <button text="右对齐按钮1" width="150" height="30"/>
    <button text="右对齐按钮2" width="150" height="30"/>
    <button text="右对齐按钮3" width="150" height="30"/>
</stackview>

事件处理

StackView 控件支持以下事件：

事件名 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"stackVertical", EventMouse::EventID, OnStackMouseEvent)
EVENT_MAP_END()

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

代码操作

// 查找堆栈视图控件
SStackView *pStackView = FindChildByName2<SStackView>(L"stackVertical");

// 设置堆栈方向
pStackView->SetAttribute(L"orientation", L"horizontal");

// 设置间距
pStackView->SetAttribute(L"spacing", L"10");

// 设置对齐方式
pStackView->SetAttribute(L"gravity", L"center");

// 获取子控件数量
int nChildCount = pStackView->GetChildrenCount();

事件处理

StackView 控件本身不产生特定事件，但其子控件的事件可以正常处理：

EVENT_MAP_BEGIN()
    EVENT_NAME_COMMAND(L"button1", OnButton1Click)
    EVENT_NAME_COMMAND(L"button2", OnButton2Click)
EVENT_MAP_END()

void CMainDlg::OnButton1Click() {
    // 处理按钮1点击事件
}

void CMainDlg::OnButton2Click() {
    // 处理按钮2点击事件
}

最佳实践

  1. 方向选择：根据界面布局需求选择合适的 orientation 值
  2. 间距控制：通过 spacing 属性控制子控件间距，保持界面美观
  3. 对齐方式：使用 gravity 属性实现子控件的对齐效果
  4. 尺寸管理：合理设置子控件的尺寸，确保堆栈布局效果

使用场景

  1. 工具栏布局
  2. 水平堆栈排列工具按钮

  3. 自动处理按钮间距和对齐

  4. 表单布局

  5. 垂直堆栈排列表单元素

  6. 简化表单布局代码

  7. 设置面板

  8. 堆栈排列设置项

  9. 动态添加或移除设置项

  10. 导航菜单

  11. 垂直或水平排列菜单项
  12. 支持动态菜单管理

常见问题

Q: 子控件排列不正确怎么办？

A: 检查 orientation 属性是否设置正确，确认水平或垂直排列符合预期。

Q: 子控件间距过大或过小怎么办？

A: 调整 spacing 属性值，设置合适的间距。

Q: 子控件对齐效果不明显怎么办？

A: 确保子控件尺寸不占满整个堆栈视图，并检查 gravity 属性设置。

相关控件