StackPanel 线性布局
LIVE CANVAS可运行组件示例
ON-DEMAND RUNTIME交互式示例将在进入视区时启动避免文档首屏同时初始化多个 Canvas Runtime
RenderStackPanel 按单一方向排列子节点，是页面、表单、工具条和侧边栏最常用的基础布局。
API 总览
公开 API：
RenderStackPanelRenderSpacerMainAxisAlignmentCrossAxisAlignmentStackPanelChildData
import { RenderSpacer, RenderStackPanel, type CrossAxisAlignment, type MainAxisAlignment, type StackPanelChildData,} from 'ds-ui'构造参数
RenderStackPanel 的 options 继承 RenderPanelOptions，因此除了下表参数，还可直接传入 padding、宽高、最小/最大尺寸、margin 和 alignment。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
orientation |
'horizontal' | 'vertical' |
'vertical' |
主轴方向。 |
spacing |
number |
主题默认间距 | 相邻子节点间距。 |
mainAxisAlignment |
MainAxisAlignment |
'start' |
主轴剩余空间分布。 |
crossAxisAlignment |
CrossAxisAlignment |
'start' |
默认交叉轴对齐。 |
padding |
EdgeInsetsInput |
0 |
面板内部留白。 |
基本用法
const panel = new RenderStackPanel({ orientation: 'vertical', spacing: 8, padding: 16, crossAxisAlignment: 'stretch',}) const action = new RenderButton({ label: '查询', variant: 'primary' })action.horizontalAlignment = 'end'action.margin = { top: 8 } panel.addChild(new RenderText('查询条件'))panel.addChild(new RenderTextBox({ placeholder: '输入关键词' }))panel.addChild(action)子组件自身的 horizontalAlignment / verticalAlignment 会覆盖面板的交叉轴默认值。子组件的 margin 计入排列尺寸，但不进入组件绘制区域。
mainAxisAlignment 控制整组子项在主轴剩余空间中的分布，不是单个子项的 alignment。它只有在面板最终主轴尺寸大于全部子项自然尺寸与间距之和时才会产生可见效果。面板处于 loose 约束并按内容收缩时，通常没有剩余空间可供分布。
LIVE CANVAS可运行组件示例
ON-DEMAND RUNTIME交互式示例将在进入视区时启动避免文档首屏同时初始化多个 Canvas Runtime
弹性子节点
addChild(child, flex) 的第二个参数属于父布局关系：
flex = 0：在主轴使用自然尺寸；嵌套 GridPanel 或 DockPanel 也不会提前吃满父级主轴。flex > 0：父主轴有限时参与剩余空间分配。- 多个 flex 子节点按权重分配。
- 父主轴无界时退化为自然尺寸。
const page = new RenderStackPanel({ orientation: 'vertical', spacing: 8, crossAxisAlignment: 'stretch',}) page.addChild(new RenderPageHeader({ title: '订单列表' }))page.addChild(new RenderTextBox({ placeholder: '搜索订单' }))page.addChild(new RenderDataGrid({ columns: [], rows: [] }), 1)需要空白项时使用 RenderSpacer({ width, height })；不要为了 flex 再包一层子组件。
使用建议
- 页面根布局通常使用 vertical + stretch。
- 工具条通常使用 horizontal + 固定 spacing。
- 常规兄弟间距用
spacing，单项例外用该子项的margin。 - 需要严格行列对齐时使用
RenderGridPanel。 - 需要四边停靠和中间填充时使用
RenderDockPanel。 - 需要把一个有宽度边界的表单放在完整页面中央时，优先使用外层单格
RenderGridPanel；StackPanel 只有在自身已经获得完整页面主轴尺寸时才能通过mainAxisAlignment: 'center'实现全页居中。