Splitter
将工作区拆分为可调整面板。中文惯用名：分栏。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.splitter |
| 名称 | Splitter |
| 二级分类 | 布局（layout） |
| 用途 | 将工作区拆分为可调整面板 |
| 描述 | 中文惯用名：分栏。 |
预览
静态结构：Splitter 的 DSL 类型名为 Resizable（同一适配器，Splitter 是「工作区分栏」用法口径）——panels 逐项渲染为 react-resizable-panels 的 Panel（data-slot="resizable-panel"），相邻面板之间插入带手柄的 ResizableHandle（data-slot="resizable-handle"，内置 GripVertical 抓握图标，纵向时手柄旋转 90°）；外层 PanelGroup 为 data-slot="resizable-panel-group"（flex h-full w-full，vertical 时 flex-col）；面板内的 children 经 renderChildren 渲染 DSL 子树；defaultSize 统一按百分比解释（本预览左右 40% / 剩余）。
DSL 结构
{
"type": "Resizable",
"props": {
"panels": [
{
"defaultSize": 40,
"children": [
{
"type": "Text",
"props": {
"text": "左侧面板",
"style": {
"display": "block",
"padding": 8
}
}
}
]
},
{
"children": [
{
"type": "Text",
"props": {
"text": "右侧面板（拖动手柄调整）",
"style": {
"display": "block",
"padding": 8
}
}
}
]
}
]
}
}何时用
何时使用
- 把工作区拆分为多个面板（固定分割条的分栏）：编辑器 + 预览、列表 + 详情、目录 + 正文——分割条常驻在版面骨架中，两侧面板各自独立滚动。
- 分栏需要初始比例预设（defaultSize 百分比），并允许用户按当前任务微调宽窄。
- 面板数量多于两个、或需要上下分区的工作区（direction: vertical）。
何时不用
- 内容之间的静态分隔线（非版面分栏）：使用 Separator。
- 调整的是单个区域 / 对象的自身尺寸（需要最小 / 最大像素约束）：使用 Resizable。
- 等宽栅格分列：使用 Grid；一维排列：使用 Flex。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 左右两栏 | 水平分栏 + 竖向拖拽手柄 | 列表 + 详情、编辑器 + 预览 |
| 上下面板 | direction="vertical" 横向手柄 | 代码 + 终端、表单 + 结果 |
| 多面板 | 3 个及以上面板，多个手柄 | 三栏工作台（导航 / 内容 / 检查器） |
| 带尺寸约束 | minSizePx / maxSizePx 限制可拖范围 | 侧栏不允许被拖到不可用宽度 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
panels | ResizablePanelData[] | [] | 面板列表：{ children?, defaultSize?（百分比）, defaultSizePx?, minSizePx?, maxSizePx? }（像素优先级高于百分比） |
direction | `'horizontal' | 'vertical'` | 'horizontal' |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 面板容器必须有确定高度（父级给高或 h-full），否则分栏高度塌陷。
- 只给第一个面板设 defaultSize 即可，其余按剩余空间自动分配，避免比例之和不为 100 引发跳变。
- 关键操作区（保存、提交）不放在可被拖窄的面板边缘，防止被拖拽挤没。
- 每个面板内容自身负责滚动（内部用 ScrollArea），不要让整个分栏区出现双层滚动条。
- 需要像素级约束（最小可用宽度）时给面板加 minSizePx，而不是靠拖拽经验规避。
正例
- ✓ 工单详情：左侧列表（defaultSize 40）+ 右侧详情，中间手柄可拖。
- ✓ 编辑器：上代码（defaultSize 60）+ 下控制台，direction="vertical"。
反例
- ✕ 用 Splitter 表达固定分割条（应使用 Separator）。
- ✕ 面板内再嵌一个同向 Splitter 造成手柄密集成排、拖拽目标难以命中。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。