DirectSurface UIDirectSurface UI
开始使用
文档/布局系统

Splitter 分割面板

LIVE CANVAS可运行组件示例
ON-DEMAND RUNTIME交互式示例将在进入视区时启动避免文档首屏同时初始化多个 Canvas Runtime

RenderSplitter 是可拖拽分割容器，用于把两个子区域按比例分成左右或上下两块。它支持鼠标拖拽、键盘调整、最小/最大比例限制和禁用状态。

Splitter 负责布局和调整比例，不负责保存布局偏好、创建滚动容器或管理业务窗口生命周期。需要 IDE 式多区域停靠和浮动窗口时使用 DockWorkspace。

API 总览

import {  RenderSplitter,  RenderText,  type SplitDirection,} from 'ds-ui'
API 类型 用途
RenderSplitter class 两区域可拖拽分割容器。
SplitDirection type 分割方向：horizontal 为左右，vertical 为上下。

最小装配顺序是：创建两个独立 child，传给 RenderSplitter({ first, second, direction, ratio })。业务可以在 onChange(ratio) 中保存用户偏好。

何时使用

使用 Splitter：

  • 主从视图需要用户调整左右比例。
  • 上下日志/详情区域需要可拖拽高度。
  • 两个区域都是长期存在的页面片段。
  • 只需要一个明确的二分布局。

不要使用：

  • 多文档、停靠、拆分和浮动窗口工作区，使用 DockWorkspace。
  • 只需要静态左右布局，使用 DockPanel 或 GridPanel。
  • 需要三块以上复杂联动布局，组合多个 Splitter 或使用更明确的工作区组件。

最小示例

import { RenderSplitter, RenderText } from 'ds-ui' const splitter = new RenderSplitter({  first: new RenderText('左侧列表'),  second: new RenderText('右侧详情'),  direction: 'horizontal',  ratio: 0.32,  onChange: ratio => {    state.masterRatio = ratio  },})

构造参数

参数 类型 默认值 说明
first RenderObject 必填 第一块内容。左右分割时在左侧，上下分割时在上方。
second RenderObject 必填 第二块内容。
direction SplitDirection 'horizontal' 分割方向。
ratio number 0.5 第一块占可用主轴空间的比例。
disabled boolean false 是否禁用拖拽和键盘调整。
minRatio number 0.1 最小比例。
maxRatio number 0.9 最大比例。
splitterSize number 5 分割条尺寸。
fixedSize number 0 组件主高度覆盖。大于 0 时用于固定高度。
onChange (ratio: number) => void undefined 拖拽或键盘调整比例时触发。

属性和方法

API 类型 / 返回值 说明
first / second RenderObject 两个子区域。构造时会设置 parent。
direction SplitDirection 当前方向。
ratio number 当前比例。赋值会被限制在 minRatio..maxRatio。
disabled boolean 禁用状态。
minRatio / maxRatio number 比例边界。
splitterSize number 分割条尺寸，只读。
fixedSize number 固定高度覆盖。
dispose() void 释放 pointer capture 和回调，并释放子树。

交互行为

操作 行为
拖拽分割条 更新 ratio 并触发 onChange(ratio)。
Home 设置到 minRatio。
End 设置到 maxRatio。
ArrowLeft / ArrowRight 水平方向减少或增加比例，每次 0.02。
ArrowUp / ArrowDown 垂直方向减少或增加比例，每次 0.02。

拖拽时 Splitter 会捕获指针；取消、禁用或 dispose 时会释放捕获状态。

布局规则

  • horizontal：first 在左，second 在右。
  • vertical：first 在上，second 在下。
  • 可用主轴尺寸会先减去 splitterSize，再按 ratio 分给两个 child。
  • 父级未给有限宽度时默认宽度 400；未给有限高度时默认高度 300。
  • ratio 不会越过 minRatio 和 maxRatio。

相关组件