reka-ui SplitterPanel 完全指南:属性、事件、插槽与方法实战解析
reka-ui SplitterPanel 完全指南:属性、事件、插槽与方法实战解析
本文围绕 reka-ui(原 Radix Vue)Splitter 布局组件中的核心成员 SplitterPanel 展开,系统讲解其全部 Props、Emits、Slots 与暴露的 Methods,并结合 SplitterPanel.vue 源码与 Splitter 官方文档 中的示例,说明面板折叠、像素尺寸、持久化、编程式控制等实际用法。读完本文,你将能熟练使用 SplitterPanel 构建可拖拽、可折叠、可持久化的分栏布局,并理解其在底层如何与 SplitterGroup 协作。
SplitterPanel 在 Splitter 组件族中的角色
reka-ui 的 Splitter 组件将布局划分为可调整大小的区块,它由三部分组成:
SplitterGroup:容器,负责管理面板注册、布局计算、拖拽状态与持久化;SplitterPanel:可折叠的区块(本节主角);SplitterResizeHandle:用于拖拽调整大小的手柄。
三者通过 Vue 的 provide/inject 上下文协作。在 SplitterPanel.vue 中,面板挂载时调用 injectPanelGroupContext() 获取分组上下文,若不在 SplitterGroup 内会直接抛出错误:
if (panelGroupContext === null) {
throw new Error(
'SplitterPanel components must be rendered within a SplitterGroup container',
)
}
因此 SplitterPanel 必须作为 SplitterGroup 的直接或间接子组件使用。挂载时面板通过 registerPanel(panelData) 注册到分组(SplitterPanel.vue),卸载时调用 unregisterPanel 注销,分组据此维护面板顺序并重算布局。
Props 全解析
SplitterPanel 共暴露 10 个 Props(全部可选):
| 名称 | 说明 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
as |
组件实际渲染成的元素或组件,可被 asChild 覆盖 |
AsTag | Component |
否 | "div" |
asChild |
将默认渲染元素替换为传入的子元素,并合并其 props 与行为(详见仓库内 Composition 指南) | boolean |
否 | - |
collapsedSize |
面板折叠后的大小,按 sizeUnit 解释 |
number |
否 | - |
collapsible |
面板被拖拽到 minSize 以下时是否折叠;为 true 时折叠到 collapsedSize |
boolean |
否 | - |
defaultSize |
面板初始大小,按 sizeUnit 解释(默认百分比) |
number |
否 | - |
id |
面板 id(组内唯一);未提供时回退到 useId 生成 |
string |
否 | - |
maxSize |
面板允许的最大尺寸,按 sizeUnit 解释;默认 100(百分比) |
number |
否 | - |
minSize |
面板允许的最小尺寸,按 sizeUnit 解释;默认 10(百分比) |
number |
否 | - |
order |
面板在组内的排列顺序;条件渲染面板的分组必须提供 | number |
否 | - |
sizeUnit |
尺寸值的单位:%(默认)或 px(固定尺寸) |
"%" | "px" |
否 | - |
这些 Props 与源码中 SplitterPanelProps 接口一一对应(见 SplitterPanel.vue)。面板内部会将它们组装成 PanelConstraints 约束对象,并在变化时触发 reevaluatePanelConstraints 重新校验尺寸(SplitterPanel.vue)。
关于默认值的重要细节
表格中 minSize 的默认值为 10,maxSize 默认为 100,这是文档层面给出的约定;而在底层 resizePanel 计算逻辑中,约束未提供时按 minSize = 0、maxSize = 100 兜底(见 resizePanel.ts)。开发中建议显式声明 min-size、max-size,避免依赖隐含默认值导致布局与预期不符。
单位换算的底层逻辑
当 sizeUnit="px" 时,内部计算统一先转换为百分比。convertPanelConstraintsToPercent 会把 px 约束按 value / groupSizeInPixels * 100 换算(见 units.ts),因此 px 面板依赖容器实际测量尺寸;若容器尚未测量(如嵌套在百分比布局中),会返回 null 等待后续 ResizeObserver 回调。这解释了为什么 px 尺寸的 defaultSize、minSize、maxSize、collapsedSize 全部按同一单位解释。
条件渲染与 order
当分组内面板是条件渲染(v-if)时,注册顺序可能不稳定,此时必须提供 order。分组在 registerPanel 时按 order 升序排序(SplitterGroup.vue),无 order 的面板排在最前。
事件(Emits)
SplitterPanel 触发 3 个事件:
| 名称 | 说明 | 载荷类型 |
|---|---|---|
collapse |
面板折叠时触发 | [] |
expand |
面板展开时触发 | [] |
resize |
面板尺寸变化时触发,size 参数为 1–100 之间的数值 | [size: number, prevSize: number] |
源码中 resize 事件的载荷实际为 <a href="https://link.gitcode.com/i/57185900b7f8e1a61eb0010444495f05" target="_blank">size: number, prevSize: number | undefined](见 [SplitterPanel.vue),首次触发的 prevSize 可能为 undefined。这些回调由分组在每次布局变化后统一派发:callPanelCallbacks 会比较新旧尺寸,仅在面板实际尺寸变化时才触发对应事件,并通过 panelIdToLastNotifiedSizeMapRef 记录上次通知的尺寸,避免重复通知(相关逻辑见 SplitterGroup.vue 及 callPanelCallbacks.ts)。
<SplitterPanel
@resize="(size, prevSize) => onResize(size, prevSize)"
@collapse="onCollapse"
@expand="onExpand"
>
插槽(Slots)
SplitterPanel 通过默认插槽向父级暴露面板状态与操作函数:
| 插槽名 | 说明 | 类型 |
|---|---|---|
isCollapsed |
面板是否处于折叠状态 | boolean |
isExpanded |
面板是否处于展开状态 | boolean |
collapse |
若面板可折叠(collapsible),将其完全折叠 |
(): void |
expand |
若面板当前折叠,将其展开到最近一次的大小 | (): void |
resize |
将面板调整到指定百分比(1–100) | (size: number): void |
模板中插槽绑定方式(见 SplitterPanel.vue):
<SplitterPanel v-slot="{ isCollapsed, isExpanded, expand, collapse, resize }">
<div>
{{ isCollapsed ? '已折叠' : isExpanded ? '已展开' : '' }}
<button @click="collapse">折叠</button>
<button @click="expand">展开</button>
<button @click="resize(50)">调到 50%</button>
</div>
</SplitterPanel>
注意插槽中的 collapse、expand 会以布尔短路的形式检查 collapsible——collapse 仅在面板可折叠时生效,expand 仅在折叠状态下生效;插槽内的 resize 则直接调用分组上下文的 resizePanel。
暴露的方法(Methods)
通过组件 ref 可调用 4 个暴露方法(defineExpose 定义见 SplitterPanel.vue):
| 名称 | 说明 | 类型 |
|---|---|---|
collapse |
若面板可折叠(collapsible),将其完全折叠 |
() => void |
expand |
若面板当前折叠,展开到最近一次的大小 | () => void |
getSize |
获取面板当前尺寸(按面板 sizeUnit:% 返回百分比,px 返回像素) |
() => number |
resize |
将面板调整到指定尺寸(按面板 sizeUnit 解释) |
(size: number) => void |
此外 defineExpose 还额外暴露了只读的 isCollapsed 与 isExpanded 布尔属性(在 MethodsTable 之外的运行时能力)。
编程式折叠/展开示例
官方文档给出的典型用法(见 splitter.md):
<script setup lang="ts">
const panelRef = ref<InstanceType<typeof SplitterPanel>>()
</script>
<template>
<button
@click="panelRef?.isCollapsed ? panelRef?.expand() : panelRef?.collapse()"
>
{{ panelRef?.isCollapsed ? '展开' : '折叠' }}
</button>
<SplitterGroup>
<SplitterPanel
ref="panelRef"
collapsible
:collapsed-size="10"
:min-size="35"
>
…
</SplitterPanel>
<SplitterResizeHandle />
<SplitterPanel>
…
</SplitterPanel>
</SplitterGroup>
</template>
方法背后的折叠语义
调用 collapse() 时,分组会先把当前尺寸记录到 panelSizeBeforeCollapseRef(折叠前的尺寸),再通过 adjustLayoutByDelta 把面板调整到 collapsedSize;调用 expand() 时则优先恢复折叠前的尺寸,若该尺寸低于 minSize 则回退到 minSize(实现见 SplitterGroup.vue)。这一“记忆最近尺寸”的语义保证了折叠→展开后布局行为符合直觉。
resize 与 getSize 的单位一致性
resize(size) 与 getSize() 都按面板自身 sizeUnit 解释数值:% 面板传百分比、px 面板传像素。底层 getPanelSize 会把内部百分比布局按容器像素换算后返回(见 SplitterGroup.vue),确保你在 px 面板上读到的是真实像素值。
折叠行为的底层原理
折叠是 SplitterPanel 最复杂的行为,涉及三处协同:
- 拖拽越过 minSize 自动折叠:
resizePanel中,当尺寸低于minSize且面板可折叠时,会以“折叠尺寸与 minSize 的中点”((collapsedSize + minSize) / 2)作为吸附阈值——拖拽低于中点则吸附到collapsedSize,否则吸附回minSize(见 resizePanel.ts)。这与 VS Code 等编辑器的面板行为一致。 - 状态判定:
isPanelCollapsed使用模糊比较panelSize <= collapsedSize(见 SplitterGroup.vue),因为 px 单位换算与布局归一化会产生浮点误差(如collapsedSize与panelSize相差1e-10级别)。相关回归测试见 Splitter.test.ts。 - DOM 状态标记:模板会输出
data-state="collapsed" | "expanded"(仅当collapsible时)、data-panel-collapsible、data-panel-size(当前 flexGrow,保留一位小数)等属性,便于样式化与自动化测试(见 SplitterPanel.vue)。
实战:一个可折叠、可持久化的分栏布局
基础折叠面板
collapsible 搭配 collapsed-size 与 min-size(官方要求这两个 prop 同时提供,见 splitter.md):
<template>
<SplitterGroup>
<SplitterPanel
collapsible
:collapsed-size="10"
:min-size="35"
>
Panel A
</SplitterPanel>
<SplitterResizeHandle />
<SplitterPanel>
Panel B
</SplitterPanel>
</SplitterGroup>
</template>
collapsedSize 与 minSize 的组合建议:collapsedSize < minSize。开发模式下若 collapsedSize > minSize、minSize > maxSize、defaultSize 越界等配置非法,validatePanelConstraints 会在控制台输出警告(见 validation.ts),可据此排查布局异常。
固定像素侧边栏
用 sizeUnit="px" 实现固定宽度侧边栏,父容器缩放时侧边栏保持像素宽度:
<template>
<SplitterGroup direction="horizontal">
<SplitterPanel
size-unit="px"
:default-size="240"
:min-size="160"
:max-size="320"
>
固定宽度侧边栏
</SplitterPanel>
<SplitterResizeHandle />
<SplitterPanel>
自适应内容
</SplitterPanel>
</SplitterGroup>
</template>
px 面板同样支持 autoSaveId 持久化与折叠/展开 API,恢复时按正确的单位还原(见 splitter.md)。从 units.ts 的 recalculateLayoutForPixelPanels 可以看出,容器尺寸变化时 px 面板按像素换算成新的百分比,其余百分比面板按剩余空间等比缩放,并归一化确保总和为 100%。
localStorage 持久化
在 SplitterGroup 上设置 autoSaveId 即可把布局存入 localStorage(见 splitter.md):
<template>
<SplitterGroup auto-save-id="my-layout-id">
<SplitterPanel :default-size="50">…</SplitterPanel>
<SplitterResizeHandle />
<SplitterPanel :default-size="50">…</SplitterPanel>
</SplitterGroup>
</template>
持久化由分组负责:布局写入会经过 100ms 的防抖(LOCAL_STORAGE_DEBOUNCE_INTERVAL,见 SplitterGroup.vue),且保存前会克隆可变数据避免竞态(SplitterGroup.vue)。恢复时布局同样会经过 validatePanelGroupLayout 校验——即使 localStorage 中的旧布局也能被约束纠正(SplitterGroup.vue)。
SSR 注意事项
Splitter 依赖唯一 id,而 Vue 3.4 之前无法在 SSR 中可靠生成 id。因此在 Nuxt 等 SSR 环境中,必须手动为所有 Splitter 组件提供 id(SplitterPanel 的 id 用于组内唯一标识、DOM 属性与持久化键),或整体用 <ClientOnly> 包裹。手动指定 id 的写法(见 splitter.md):
<template>
<SplitterGroup id="group-1">
<SplitterPanel id="group-1-panel-1">…</SplitterPanel>
<SplitterResizeHandle id="group-1-resize-1">…</SplitterResizeHandle>
<SplitterPanel id="group-1-panel-2">…</SplitterPanel>
</SplitterGroup>
</template>
数据属性一览
SplitterPanel 渲染时会携带以下 data-* 属性,可用于样式选择器与测试定位(见 SplitterPanel.vue):
data-panel="":标记面板元素;data-panel-id:面板 id(手动指定或自动生成);data-panel-group-id:所属分组 id;data-panel-collapsible:当collapsible为真时出现;data-panel-size:当前 flex 尺寸(一位小数);data-state:可折叠面板为collapsed/expanded,不可折叠时不输出。
总结
SplitterPanel 的全部能力浓缩在 10 个 Props、3 个事件、5 个插槽变量与 4 个公开方法中。理解其要点后即可灵活应用:
- 尺寸控制:
defaultSize/minSize/maxSize/collapsedSize全部按sizeUnit解释,%适合弹性布局,px适合固定侧边栏; - 折叠体系:
collapsible开启后,拖拽越过“折叠尺寸与最小尺寸中点”即吸附折叠,collapse/expand方法记忆折叠前尺寸; - 状态同步:通过事件(
resize/collapse/expand)、插槽变量(isCollapsed等)与 DOMdata-state属性三种途径感知面板状态; - 工程落地:配合
SplitterGroup的autoSaveId持久化、SSR 手动id、条件渲染的order,可构建生产级的分栏界面。
更完整的组件族 API 与键盘交互(Enter 折叠/恢复、方向键移动、Home/End 跳转最小/最大尺寸)可继续阅读 Splitter 文档 及 SplitterGroup.vue、SplitterResizeHandle.vue 源码。