Layout API 参考

本文示例使用以下公共入口：

import {  RenderBorder,  RenderOverlayHost,  RenderText,  type BoxAlignment,  type EdgeInsetsInput,} from 'ds-ui'

本页汇总 ds-ui 包入口公开的布局 API。布局设计原则和选择方法见布局系统总览。

通用盒模型

RenderBox

所有可布局组件的基类。每个 RenderBox 都公开以下统一属性：

属性	类型
`width` / `height`	`number
`minWidth` / `maxWidth`	`number
`minHeight` / `maxHeight`	`number
`margin`	`EdgeInsetsInput`
`horizontalAlignment` / `verticalAlignment`	`BoxAlignment
`size`	`Size`，组件绘制尺寸
`outerSize`	`Size`，包含 margin 的布局尺寸

RenderPanel

布局面板的基类，继承 RenderBox 并增加 padding。RenderPanelOptions 等于 RenderBoxOptions + { padding? }。

应用代码通常实例化具体面板，不直接实例化抽象的 RenderPanel。

行为型单子节点组件

API	参数	说明
`RenderVisibility`	`{ mode?, child? }`	visible、hidden、collapsed 状态。
`RenderClip`	`child` 或 `{ child?, cornerRadius? }`	裁剪绘制和命中范围。
`RenderAppContextScope`	`RenderAppContextScopeOptions`	向子树提供局部 app context。
`RenderCommandScope`	`RenderCommandScopeOptions`	向子树提供局部命令作用域。

这些组件保留是因为它们提供独立运行时行为。尺寸、margin 和 alignment 仍使用统一 RenderBox 属性。

RenderStackPanel

new RenderStackPanel({
  orientation?,
  spacing?,
  mainAxisAlignment?,
  crossAxisAlignment?,
  padding?,
})

addChild(child, flex = 0)
clearChildren()
RenderSpacer({ width?, height? })

StackPanelChildData 仅包含 flex。相关类型：Orientation、MainAxisAlignment、CrossAxisAlignment。

RenderDockPanel

addChild(child, { dock })
setFill(child?)
clearChildren()

DockSide = 'left' | 'top' | 'right' | 'bottom' | 'fill'。DockChildData 只包含 dock；停靠区域的宽高使用子组件自身 width / height。

RenderGridPanel

new RenderGridPanel({
  columns?,
  rows?,
  columnGap?,
  rowGap?,
  padding?,
})

轨道 helper：

gridPx(value)
gridFr(value = 1, { min?, max? })
gridStar(value = 1, options?)
gridAuto({ min?, max? })

GridPanelChildData 只包含 row、column、rowSpan、columnSpan。单元格内对齐使用子组件自身 alignment。

其他面板

API	关键参数或 attached data
`RenderUniformGrid`	`rows?`、`columns?`、`columnGap?`、`rowGap?`、`padding?`
`RenderWrapPanel`	`spacing?`、`runSpacing?`、`alignment?`、`runAlignment?`、`crossAxisAlignment?`、`padding?`
`RenderAdaptiveGridPanel`	`minColumnWidth`、`minColumns?`、`maxColumns?`、`columnGap?`、`rowGap?`、`padding?`；子项只有 `columnSpan?`
`RenderMasonryPanel`	`columnCount?`、`columnGap?`、`rowGap?`、`itemHorizontalAlignment?`、`padding?`
`RenderAnchor` / `RenderCanvas`	padding；子项使用 `top/right/bottom/left/centerX/centerY`

所有面板都继承 RenderPanelOptions。

RenderOverlayHost

RenderOverlayHost 在 base 上叠加 scrim 和一个 overlay child：

const base = new RenderText('Base content')const panel = new RenderBorder({ child: content })panel.minWidth = 320panel.maxWidth = 520panel.horizontalAlignment = 'center' const host = new RenderOverlayHost({  base,  overlayInset: 24,  overlay: {    child: panel,    closeOnScrimPointerDown: true,    onRequestClose: close,  },})

overlay 的尺寸和对齐来自 child 的通用属性；overlayInset 是宿主为浮层保留的安全边距。

设计约束

不提供只为 width/height、margin、alignment 服务的单子节点包装组件。
padding 由容器拥有，margin 由子组件拥有。
attached data 只保存父子关系信息，不能重复保存通用组件属性。
RenderSpacer 表达真实空白项；RenderClip 和 RenderVisibility 表达真实行为。
alignment 未设置时由直接父布局选择默认策略；各面板的有效默认值见布局系统总览。