reka-ui SplitterPanel 完全指南:属性、事件、插槽与方法实战解析

原创2026-09-17 10:25:061,362 阅读
文章标签:UI组件前端设计系统

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 最复杂的行为,涉及三处协同:

  1. 拖拽越过 minSize 自动折叠:resizePanel 中,当尺寸低于 minSize 且面板可折叠时,会以“折叠尺寸与 minSize 的中点”((collapsedSize + minSize) / 2)作为吸附阈值——拖拽低于中点则吸附到 collapsedSize,否则吸附回 minSize(见 resizePanel.ts)。这与 VS Code 等编辑器的面板行为一致。
  2. 状态判定:isPanelCollapsed 使用模糊比较 panelSize <= collapsedSize(见 SplitterGroup.vue),因为 px 单位换算与布局归一化会产生浮点误差(如 collapsedSize 与 panelSize 相差 1e-10 级别)。相关回归测试见 Splitter.test.ts。
  3. 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 等)与 DOM data-state 属性三种途径感知面板状态;
  • 工程落地:配合 SplitterGroup 的 autoSaveId 持久化、SSR 手动 id、条件渲染的 order,可构建生产级的分栏界面。

更完整的组件族 API 与键盘交互(Enter 折叠/恢复、方向键移动、Home/End 跳转最小/最大尺寸)可继续阅读 Splitter 文档 及 SplitterGroup.vue、SplitterResizeHandle.vue 源码。

登录后查看全文
radix-vue