分隔器

一个将布局划分为可调整大小部分的组件。

查看代码

面板 A

面板 B

面板 C

特性

支持键盘交互。
支持水平/垂直布局。
支持嵌套布局。
支持从右到左方向。
可跨另一个面板调整大小。
可条件性地挂载。

安装

从命令行安装此组件。

$ npm add reka-ui

组成部分

导入所有部分并将其组合。

vue

<script setup>
import { SplitterGroup, SplitterPanel, SplitterResizeHandle } from 'reka-ui'
</script>

<template>
  <SplitterGroup>
    <SplitterPanel />
    <SplitterResizeHandle />
  </SplitterGroup>
</template>

API 参考

组

包含分隔器的所有部分。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`autoSaveId`	`null`	`string \| null` 用于通过 `localStorage` 自动保存组排列的唯一 ID。
`direction*`		`'vertical' \| 'horizontal'` 分隔器的组方向。
`id`		`string \| null` 组 ID；如果未提供，则回退到 `useId`。
`keyboardResizeBy`	`10`	`number \| null` 按下方向键时的步长。
`storage`	`defaultStorage`	`PanelGroupStorage` 自定义存储 API；默认为 localStorage

事件触发	载荷
`layout`	`[val: number[]]` 组布局改变时调用的事件处理程序

插槽（默认）	载荷
`layout`	`number[]` 当前布局大小

数据属性	值
`[data-orientation]`	`"垂直" \| "水平"`
`[data-state]`	`"折叠" \| "展开" \| "可折叠时存在"`

面板

一个可折叠的区域。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`collapsedSize`		`数字` 面板折叠时的大小。
`collapsible`		`布尔值` 当面板调整大小超出其 `minSize` 时是否应折叠。当为 `true` 时，它将折叠到 `collapsedSize`。
`defaultSize`		`数字` 面板的初始大小（1-100 之间的数值）
`id`		`string` 面板 ID（在组内唯一）；如果未提供，则回退到 `useId`
`maxSize`		`数字` 面板的最大允许大小（1-100 之间的数值）；默认为 `100`
`minSize`		`数字` 面板的最小允许大小（1-100 之间的数值）；默认为 `10`
`order`		`数字` 面板在组内的顺序；对于有条件渲染面板的组是必需的

事件触发	载荷
`collapse`	`[]` 面板折叠时调用的事件处理程序。
`expand`	`[]` 面板展开时调用的事件处理程序。
`resize`	`[size: number, prevSize: number]` 面板调整大小时调用的事件处理程序；size 参数是一个 1-100 之间的数值。

插槽（默认）	载荷
`isCollapsed`	`布尔值` 面板是否已折叠
`isExpanded`	`布尔值` 面板是否已展开
`collapse`	`(): void` 如果面板是 `collapsible`，则完全折叠它。
`expand`	`(): void` 如果面板当前已折叠，则将其展开到其最近的大小。
`resize`	`(size: number): void` 将面板调整到指定的百分比（1 - 100）。

方法	类型
`collapse`	`() => void` 如果面板是 `collapsible`，则完全折叠它。
`expand`	`() => void` 如果面板当前已折叠，则将其展开到其最近的大小。
`getSize`	`() => number` 获取面板当前大小的百分比（1 - 100）。
`resize`	`(size: number) => void` 将面板调整到指定的百分比（1 - 100）。

调整大小手柄

用于调整大小的手柄。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`disabled`		`布尔值` 禁用拖动手柄
`hitAreaMargins`		`PointerHitAreaMargins` 在确定可调整大小手柄的点击检测时允许的边距量
`id`		`string` 调整大小手柄 ID（在组内唯一）；如果未提供，则回退到 `useId`
`tabindex`	`0`	`数字` 手柄的 Tabindex

事件触发	载荷
`dragging`	`[isDragging: boolean]` 拖动处理程序时调用的事件处理程序。

数据属性	值
`[data-state]`	`"拖动" \| "悬停" \| "非活动"`
`[data-disabled]`	禁用时存在
`[data-orientation]`	`"垂直" \| "水平"`

示例

可折叠

使用 collapsible 属性，当达到 minSize 时，允许面板折叠到 collapsedSize。

（collapsedSize 和 minSize 属性是必需的。）

vue

<template>
  <SplitterGroup>
    <SplitterPanel
      collapsible
      :collapsed-size="10"
      :min-size="35"
    >
      Panel A
    </SplitterPanel>
    <SplitterResizeHandle />
    <SplitterPanel>
      Panel B
    </SplitterPanel>
  </SplitterGroup>
</template>

持久化到 localStorage

使用 autoSaveId 属性将布局数据保存到 localStorage。

vue

<template>
  <SplitterGroup auto-save-id="any-id">
    …
  </SplitterGroup>
</template>

通过 SSR 持久化布局

默认情况下，分隔器使用 localStorage 来持久化布局。在使用服务器渲染时，当默认布局（在服务器上渲染）被持久化布局（在 localStorage 中）替换时，这可能会导致闪烁。避免这种闪烁的方法是也通过 cookie 来持久化布局，如下所示

vue

<!-- with Nuxt -->
<script setup lang="ts">
const layout = useCookie<number[]>('splitter:layout')
</script>

<template>
  <SplitterGroup
    direction="horizontal"
    @layout="layout = $event"
  >
    <SplitterPanel :default-size="layout[0]">
      …
    </SplitterPanel>
    <SplitterResizeHandle />
    <SplitterPanel :default-size="layout[1]">
      …
    </SplitterPanel>
  </SplitterGroup>
</template>

程序化折叠/展开

有时面板需要根据用户操作进行调整大小或折叠/展开。SplitterPanel 暴露了 collapse 和 expand 方法来实现这一点。

vue

<script setup lang="ts">
const panelRef = ref<InstanceType<typeof SplitterPanel>>()
</script>

<template>
  <button
    @click="panelRef?.isCollapsed ? panelRef?.expand() : panelRef?.collapse() "
  >
    {{ panelRef?.isCollapsed ? 'Expand' : 'Collapse' }}
  </button>

  <SplitterGroup>
    <SplitterPanel
      ref="panelRef"
      collapsible
      :collapsed-size="10"
      :min-size="35"
    >
      …
    </SplitterPanel>
    <SplitterResizeHandle />
    <SplitterPanel>
      …
    </SplitterPanel>
  </SplitterGroup>
</template>

自定义手柄

通过将任何元素作为插槽传递来定制手柄。

vue

<template>
  <SplitterGroup>
    <SplitterPanel>
      …
    </SplitterPanel>
    <SplitterResizeHandle>
      <Icon icon="radix-icons-drag-handle-dots-2" />
    </SplitterResizeHandle>
    <SplitterPanel>
      …
    </SplitterPanel>
  </SplitterGroup>
</template>

SSR

分隔器组件严重依赖唯一的 id，但对于 Vue<3.4，我们没有可靠的方法来生成 SSR 友好的 id。

因此，如果您正在使用 Nuxt 或其他 SSR 框架，您需要为所有分隔器组件手动添加 id。或者，您可以使用 <ClientOnly> 包装组件。

vue

<template>
  <SplitterGroup id="group-1">
    <SplitterPanel id="group-1-panel-1">
      …
    </SplitterPanel>
    <SplitterResizeHandle id="group-1-resize-1">
      <Icon icon="radix-icons-drag-handle-dots-2" />
    </SplitterResizeHandle>
    <SplitterPanel id="group-1-panel-2">
      …
    </SplitterPanel>
  </SplitterGroup>
</template>

可访问性

遵循窗口分隔器 WAI-ARIA 设计模式。

键盘交互

键	描述
`回车键`	如果主窗格未折叠，则折叠该窗格。如果窗格已折叠，则将分隔器恢复到其先前的位置。
`向下箭头键`	将水平分隔器向下移动。
`向上箭头键`	将水平分隔器向上移动。
`向右箭头`	将垂直分隔器向右移动。
`向左箭头`	将垂直分隔器向左移动。
`Home`	将分隔器移动到使主窗格具有其允许的最小大小的位置。
`End`	将分隔器移动到使主窗格具有其允许的最大大小的位置。

分隔器 ​

特性 ​

安装 ​

组成部分 ​

API 参考 ​

组 ​

面板 ​

调整大小手柄 ​

示例 ​

可折叠 ​

持久化到 localStorage ​

通过 SSR 持久化布局 ​

程序化折叠/展开 ​

自定义手柄 ​

SSR ​

可访问性 ​

键盘交互 ​

分隔器

特性

安装