Splitter

基础布局

基于 Bootstrap 5 的分栏布局组件，用于在两个或多个面板之间创建可拖拽调整的布局，支持水平/垂直方向、像素/百分比/自适应尺寸、最小最大约束、折叠面板、键盘操作、自定义分隔条以及受控/非受控模式

Component Demo

Basic usage and examples of the Splitter component

基础用法

左侧面板

右侧面板

拖拽中间分隔条调整两侧宽度，未指定尺寸的面板默认为 auto 并自动占据剩余空间；分隔条支持键盘操作：方向键调整 10%，Shift+方向键微调 1%，Home/End 直达最小/最大尺寸

垂直布局

上方面板

下方面板

layout 设为 vertical 时面板上下排列；垂直布局需要容器具有确定的高度，百分比尺寸与 min/max 均相对容器高度计算

像素与百分比

固定像素 200px

百分比 30%

auto 自适应剩余空间

尺寸支持像素数字、像素字符串与百分比字符串，未指定或传入 auto 的面板按剩余空间均分；拖拽后 auto 面板会转换为像素尺寸，百分比面板保持百分比单位

最小与最大尺寸

范围 20% ~ 60%

最小 25%

拖拽与键盘调整都会被两侧面板的 min/max 同时约束，越界时会自动钳制

折叠面板

双击分隔条折叠

内容区域

开启 collapsible 后双击分隔条即可折叠/展开左侧面板，再次双击恢复折叠前的尺寸；拖拽或键盘调整也可将折叠面板重新展开

受控折叠

内容区域

受控模式通过 collapsed 与 onCollapse 管理折叠状态，双击分隔条仅触发 onCollapse 回调

受控模式

左侧面板

右侧面板

25% / 75%

提供 sizes 后组件进入受控模式，拖拽、键盘与折叠仅触发 onChange，由外部状态驱动渲染

禁用与不可调整

左侧面板

右侧面板

disabled 禁用整个分割器的拖拽、键盘调整与双击折叠

固定面板（不可调整）

可调整面板

面板设置 resizable="false" 后其相邻分隔条会被禁用

自定义分隔条

左侧面板

右侧面板

renderBar 接收分隔条的无障碍与样式属性，展开到自定义元素上即可；拖拽、键盘与双击折叠交互由组件自动处理，barSize 可调整分隔条厚度

嵌套布局

顶部工具栏

资源管理器

编辑器

面板内容可以继续嵌套任意方向的分割器，组合出 IDE 式多区域可调整布局

API Documentation

Complete API reference for the Splitter component

Props

Splitter

属性名	类型	默认值	描述
`as`	`ElementType`	`'div'`	根容器渲染的元素类型
`barSize`	`number`	`8`	分隔条厚度（像素）
`children`	`ReactNode`	-	面板内容，仅识别 `SplitterPanel`，其余子项会被忽略
`className`	`string`	-	自定义类名，作用于根容器
`defaultSizes`	`SplitterSize[]`	-	非受控模式下的初始尺寸数组，按面板顺序对应，缺失项视为 `auto`；优先级高于面板的 `defaultSize`
`disabled`	`boolean`	`false`	是否禁用所有分隔条的拖拽、键盘调整与双击折叠
`layout`	`SplitterLayout`	`'horizontal'`	布局方向，`horizontal` 左右分栏、`vertical` 上下分栏
`onChange`	`(sizes: SplitterSize[]) => void`	-	尺寸变化时回调，参数为当前各面板尺寸数组（拖拽、键盘调整、折叠均会触发）
`onResizeEnd`	`(sizes: SplitterSize[]) => void`	-	一次拖拽调整结束时回调，参数为调整后的尺寸数组
`onResizeStart`	`(sizes: SplitterSize[]) => void`	-	开始拖拽调整时回调，参数为调整前的尺寸数组
`renderBar`	`(props: SplitterBarRenderProps, index: number) => ReactNode`	-	自定义分隔条渲染函数，参数为分隔条属性集合（无障碍与样式属性，含 `data-splitter-bar` 标识）与分隔条序号（从 0 开始）；拖拽、键盘与折叠交互由组件自动附加到返回的元素上
`sizes`	`SplitterSize[]`	-	受控尺寸数组，提供后组件不再维护内部尺寸，仅在尺寸变化时触发 `onChange`
`...rest`	`HTMLAttributes`	-	根容器的所有原生属性（如 `style`、`id` 等）

SplitterPanel

属性名	类型	默认值	描述
`as`	`ElementType`	`'div'`	面板渲染的元素类型
`children`	`ReactNode`	-	面板内容
`className`	`string`	-	自定义类名，作用于面板
`collapsible`	`boolean`	`false`	是否允许通过双击相邻分隔条折叠该面板
`collapsed`	`boolean`	`false`	受控的折叠状态，提供后双击/拖拽不会自动更新，仅触发 `onCollapse` 回调
`collapsedSize`	`number \| string`	`0`	折叠后的面板尺寸
`defaultCollapsed`	`boolean`	`false`	非受控模式下的初始折叠状态
`defaultSize`	`number \| string`	`'auto'`	非受控模式下的初始尺寸，支持像素数字、`200px` 像素字符串、`40%` 百分比字符串或 `auto`
`max`	`number \| string`	-	面板的最大尺寸（像素或百分比）
`min`	`number \| string`	-	面板的最小尺寸（像素或百分比）
`onCollapse`	`(collapsed: boolean) => void`	-	折叠状态变化时回调，参数为新的折叠状态
`resizable`	`boolean`	`true`	是否允许通过相邻分隔条调整该面板尺寸；相邻两侧均不可调整时分隔条会被禁用
`...rest`	`HTMLAttributes`	-	面板的所有原生属性（如 `style`、`data-*` 等）

Type Definitions

SplitterProps

分栏容器组件属性接口

export interface SplitterProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
  as?: ElementType;
  barSize?: number;
  children?: ReactNode;
  className?: string;
  defaultSizes?: SplitterSize[];
  disabled?: boolean;
  layout?: SplitterLayout;
  onChange?: (sizes: SplitterSize[]) => void;
  onResizeEnd?: (sizes: SplitterSize[]) => void;
  onResizeStart?: (sizes: SplitterSize[]) => void;
  renderBar?: (props: SplitterBarRenderProps, index: number) => ReactNode;
  sizes?: SplitterSize[];
}

SplitterPanelProps

面板组件属性接口

export interface SplitterPanelProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  collapsible?: boolean;
  collapsed?: boolean;
  collapsedSize?: number | string;
  defaultCollapsed?: boolean;
  defaultSize?: number | string;
  index?: number;
  max?: number | string;
  min?: number | string;
  onCollapse?: (collapsed: boolean) => void;
  resizable?: boolean;
}

SplitterContextValue

分栏上下文值，可通过 `useSplitter` 获取（不在 `Splitter` 内返回 `null`）

export interface SplitterContextValue {
  barSize: number;
  collapsed: boolean[];
  disabled: boolean;
  layout: SplitterLayout;
  panelCount: number;
  resizingIndex: null | number;
  sizes: SplitterSize[];
}

SplitterLayout

分栏布局方向类型

export type SplitterLayout = 'horizontal' | 'vertical';

SplitterSize

面板尺寸类型，支持像素数字、像素字符串与百分比字符串

export type SplitterSize = number | string;

SplitterBarRenderProps

自定义分隔条渲染属性，在原生 HTML 属性之上附带 `data-splitter-bar` 分隔条标识

export interface SplitterBarRenderProps extends HTMLAttributes<HTMLElement> {
  'data-splitter-bar': number;
}