面板组 PanelGroup

基本用法

保留原伸缩框“基本用法”的单内容面板：拖拽右侧或底部调整宽高，交汇处可同时调整两个方向。通过横、纵两层面板组组合实现，空白填充面板只用于提供可伸缩空间。

水平布局

PanelGroup 内至少需要一个未设置 size 和 defaultSize 的填充面板，自动占据剩余空间。有尺寸的面板在未放置独立 PanelSeparator 时，会在朝向填充面板的一侧自带边缘伸缩杆。每个方向中，填充面板的每侧最多一个有尺寸面板；更多面板通过嵌套布局实现。

非受控尺寸与交互控制

仅设置 Panel.defaultSize 即可由组件维护尺寸，例如 default-size="50%" 将容器分成两半。需要在业务中读取实时尺寸时使用 v-model:size。PanelGroup.disabled 隐藏组内伸缩杆并禁用指针、键盘和双击调整；禁用或切换方向时会取消当前拖拽并恢复起始尺寸。嵌套组独立控制禁用状态。

orientation 支持运行时切换，面板内容保持挂载。component 可指定面板组的 HTML 根标签。组级拖拽事件只上报本组面板的交互，嵌套交叉拖拽分别通知对应组。

自定义伸缩杆与重排

通过 PanelSeparator 默认插槽自定义伸缩杆。为面板设置稳定的 key 后，切换位置会播放重排动画，伸缩方向随位置更新。双击伸缩杆恢复 defaultSize（未设置时恢复首次传入的 size）。

双侧伸缩

一组中填充面板的两侧各允许一个有尺寸面板，两侧都可以拖拽伸缩。

垂直方向

orientation="vertical" 时面板沿纵向排列，伸缩杆变为水平方向。

折叠动画

面板支持 collapsed 折叠，并通过 fold 配置内容在折叠/展开时应用的样式姿态，折叠与展开是真实的动画（宽度过渡 + 内容姿态过渡）。

固定内容

填充面板设置 pin 后，内容按面板折叠结束时的宽度排版，折叠动画期间不再逐帧重新换行，避免真实内容付出回流代价。

嵌套

PanelGroup 支持嵌套：填充面板内可以再放一个不同方向的 PanelGroup。

多层嵌套与交叉拖拽

三层面板组组合文件列表、编辑器、大纲与终端，各面板可以独立折叠。两根伸缩杆交汇处支持同时调整两个方向的尺寸。

API

PanelGroup 属性

参数名	描述	类型	默认值
orientation	面板排列方向，可动态切换	'horizontal' | 'vertical'	'horizontal'
component	面板组的 HTML 根标签	string	'div'
disabled	禁用组内调整并隐藏伸缩杆	boolean	false
reorder	面板重排时是否播放位移动画	boolean	true
transition	重排动画的过渡配置（毫秒）	PanelTransition	-

Panel 属性

参数名	描述	类型	默认值
size (v-model)	受控面板尺寸，像素或百分比字符串	number | \${number}%``	-
collapsed (v-model)	是否折叠	boolean	false
defaultSize	非受控初始尺寸及双击恢复尺寸	number | \${number}%``	首次传入的 size
fold	折叠/展开时应用到内容层上的样式姿态	{ shown?: PanelPose; hidden?: PanelPose }	-
minSize	最小尺寸	number | \${number}%``	0
maxSize	最大尺寸	number | \${number}%``	-
pin	填充面板是否固定内容宽度（避免折叠动画期间内容回流）	boolean	false
keepMounted	折叠后是否保持内容挂载	boolean	true
transition	面板尺寸/折叠动画的过渡配置（毫秒）	PanelTransition	{ duration: 250 }

size 传入时为受控尺寸，使用 v-model:size 接收实时更新；不传 size 而只传 defaultSize 时为非受控尺寸，组件保留调整结果。两者均不传时为填充面板，挂载后不切换面板类型。修改 defaultSize 只改变后续双击恢复的尺寸，不重置非受控当前尺寸。collapsed 仍是受控状态，使用 v-model:collapsed 接收更新。pin 仅对填充面板生效。class、style 和普通 HTML 属性应用到内容层，避免内边距、边框阻止外层完全折叠。keepMounted=false 时，内容在退出动画完成后卸载，下一次展开重新创建。

PanelTransition

duration 为毫秒；easing 为 cubic-bezier 四元组。设置 type: 'spring' 可启用弹簧尺寸动画，支持 bounce、stiffness、damping 和 mass。设置 duration: 0 可关闭动画。系统启用“减少动态效果”时，尺寸和内容动画会关闭。重排和内容的 opacity / transform 使用 duration、easing；弹簧配置作用于面板尺寸。

Panel 事件

事件名	描述	参数
update:size	拖拽中实时尺寸变化或键盘/双击调整；取消拖拽时回写起始尺寸	size: number | \${number}%``
update:collapsed	折叠状态变化（含拖拽中越过最小尺寸的自动折叠）	collapsed: boolean

拖拽生命周期事件（Panel / PanelGroup）

事件名	描述	参数
move-start	按下伸缩杆、开始调整之前触发	event: PointerEvent（pointerdown）
moving	拖拽移动时触发	event: PointerEvent
move-end	指针释放、最终尺寸更新后触发	event: PointerEvent

在 Panel 上监听单个面板，在 PanelGroup 上监听本组面板。PointerEvent 继承 MouseEvent，同时保留鼠标坐标和触摸/笔指针信息。取消拖拽会恢复起始尺寸，不触发 move-end。

Panel 插槽

插槽名	描述	参数
default	面板内容	collapsed: boolean，dragging: boolean，folding: boolean

PanelSeparator 属性

参数名	描述	类型	默认值
aria-label	伸缩杆的无障碍标签	string	'调整大小'

PanelSeparator 插槽

插槽名	描述	参数
default	自定义伸缩杆内容	-

PanelGroup 插槽

插槽名	描述
default	组合 Panel 与 PanelSeparator

键盘操作

伸缩杆支持 Tab 聚焦、方向键调整 10px、Shift + 方向键或 PageUp / PageDown 调整 50px，Home / End 移到最小/最大尺寸，Enter 请求折叠或展开，Escape 取消当前拖拽。水平布局支持 RTL。伸缩杆的普通属性和监听器会透传到可聚焦元素。

从 ResizeBox 迁移

PanelGroup 组件组替代已移除的 ResizeBox（伸缩框）。迁移对照：

ResizeBox	PanelGroup 组件组
<resize-box :width="w" :directions="['right']">	<panel-group> + <panel v-model:size="w"> + 填充 <panel>
width / height (v-model)	size (v-model)，方向由 orientation 决定
moving-start / moving / moving-end	move-start / moving / move-end；update:size 实时上报尺寸
directions（四边伸缩）	每组每侧最多一个有尺寸面板；更复杂的布局用嵌套 PanelGroup 表达
resize-trigger 插槽	<panel-separator> 的 default 插槽

从 Split 迁移

Split 及其文档、导出和样式已移除，双面板布局使用一个有尺寸面板和一个填充面板组合。

Split	PanelGroup 组件组
direction	PanelGroup.orientation，支持动态切换
component / disabled	PanelGroup.component / PanelGroup.disabled
size (v-model)	Panel.size (v-model)，拖拽中实时上报
default-size	Panel.defaultSize，支持非受控尺寸；两等分传 '50%'
min / max	Panel.minSize / Panel.maxSize
move-start / moving / move-end	在 Panel 或 PanelGroup 上监听同名事件
first / second 插槽	两个 Panel 的默认插槽
resize-trigger / resize-trigger-icon	PanelSeparator 默认插槽自定义内容

尺寸数值表示像素，百分比使用字符串：原 0.5 改为 '50%'，原 '300px' 改为 300。伸缩杆继续使用 PanelSeparator 默认插槽，不增加独立图标插槽。