工具栏
概述
用于将相关操作、链接和切换控件组织到同一个支持 roving focus 的紧凑工具栏中。SToolbar 组合 Aria 工具栏基础组件（ToolbarRoot/ToolbarButton/ToolbarLink/ToolbarSeparator/ToolbarToggleGroup/ToolbarToggleItem）与 toolbarVariants 样式配方（7 个槽、6 种尺寸 × 2 个方向）。
工具栏适合密集、可键盘导航的一行操作。单个操作按钮请用 button；成组按钮请用 toggle-group。
用法
特性
- 🧩 Aria/样式分离 —
ToolbarRoot提供工具栏上下文；每个部分（button/link/separator/toggle-group）都是薄样式化基础组件 - ⌨️ Roving focus — 方向键在工具栏项间导航，Home/End，可选
loop；分隔线与禁用项被跳过 - ↔️ 方向 —
horizontal（默认）或vertical；分隔线自动翻转方向 - 🔘 切换组 —
SToolbarToggleGroup/SToolbarToggleItem用v-model实现单选/多选切换 - 🔗 链接支持 —
SToolbarLink渲染带前导图标（showIcon）的锚点 - 📐 6 种尺寸 — xs–2xl
size；逐槽ui覆盖 - ♿ 无障碍 —
role="toolbar"、aria-orientation、切换项aria-pressed、axe-core零违规
组件家族
SToolbar（样式层）— 根包装组件；toolbarVariants配方（size+ 方向）配合provideToolbarUiSToolbarButton（样式层）— 工具栏按钮（Button基座）SToolbarLink（样式层）— 工具栏链接（Link基座，可选showIcon）SToolbarSeparator（样式层）— 方向感知分隔线（SeparatorRoot基座）SToolbarToggleGroup/SToolbarToggleItem（样式层）— 切换组控件（ToggleGroupRoot/ToggleGroupItem基座）ToolbarRoot/ToolbarButton/ToolbarLink/ToolbarSeparator/ToolbarToggleGroup/ToolbarToggleItem（Aria）— 底层基础组件
演示
API
Aria 层
7Toolbar
8 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 应用于根元素的额外类名。 |
size | ThemeSize | — | 组件的视觉尺寸。 |
ui | Partial<ToolbarUi> | — | 该组件的按槽类重写。 |
orientation | DataOrientation | — | 工具栏的排列方向。 |
dir | Direction | — | 工具栏的阅读方向。 |
loop | boolean | — | 键盘焦点是否会循环移动。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
ToolbarButton
4 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
click | PointerEvent | 在发生点击时触发。 |
ToolbarLink
21 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
showIcon | boolean | — | 当提供 `href` 属性时，是否显示图标。 |
to | string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric | — | Route Location：点击该链接后应跳转到的位置。 |
replace | boolean | — | 调用 `router.replace` 而不是 `router.push`。 |
href | string | — | 点击链接时应跳转到的 URL。 |
disabled | boolean | — | 当值为 `true` 时，该链接将被禁用。 |
activeClass | string | — | 当链接处于活动状态时应用的类 |
exactActiveClass | string | — | 当链接完全有效时应用的类 |
inactiveClass | string | — | 链接处于非活动状态时应应用的类。 |
prefetchedClass | string | — | 一个用于标记已预取链接的类。 |
external | boolean | — | 强制将链接视为外部链接（true）或内部链接（false）。这有助于处理边界情况 |
ariaCurrentValue | 'true' | 'false' | 'page' | 'date' | 'time' | 'step' | 'location' | `'page'` | 当链接处于活动状态时，传递给 `aria-current` 属性的值。 |
viewTransition | boolean | — | 如果支持，请将 `router.push()` 返回的 Promise 传递给 `document.startViewTransition()`。 |
target | (string & {}) | '_blank' | '_parent' | '_self' | '_top' | null | — | 将链接的 URL 作为浏览上下文的名称显示在何处。 |
rel | (string & {}) | 'noopener' | 'noreferrer' | 'nofollow' | 'sponsored' | 'ugc' | null | 'noopener noreferrer' | 应用于链接的 rel 属性值。对于外部链接，默认值为“noopener noreferrer”。 |
noRel | boolean | — | 如果设置为 true，则不会在链接中添加 rel 属性 |
prefetch | boolean | — | 启用后，将预取视口内链接的中间件、布局和有效载荷。 |
prefetchOn | 'visibility' | 'interaction' | Partial<{ visibility: boolean; interaction: boolean; }> | — | 允许控制何时预取链接。默认情况下，仅在可见性发生变化时才会触发预取。 |
noPrefetch | boolean | — | 用于禁用 `prefetch` 属性的逃逸机制。 |
trailingSlash | 'append' | 'remove' | — | 一个用于在此特定链接的 `href` 中添加或移除尾部斜杠的选项。
如果提供了此选项，将覆盖全局 `trailingSlash` 选项。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
ToolbarRoot
5 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
orientation | DataOrientation | — | 工具栏的排列方向。 |
dir | Direction | — | 工具栏的阅读方向。 |
loop | boolean | — | 键盘焦点是否会循环移动。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
ToolbarSeparator
1 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
decorative | boolean | — | 该组件是否纯属装饰性。<br>当值为 `true` 时，将更新与无障碍相关的属性，
从而将渲染后的元素从无障碍树中移除。 |
ToolbarToggleGroup<M, T>
14 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
rovingFocus | boolean | — | 当值为 `false` 时，将禁用使用方向键浏览项目的功能。 |
disabled | boolean | — | 当值为 `true` 时，将阻止与该组中所有项的交互。 |
orientation | DataOrientation | — | 组件的取向。 |
dir | Direction | — | 如适用，请标注该组的阅读方向。 |
loop | boolean | — | 当值为 `true` 时，键盘导航将从最后一个项目循环至第一个项目，反之亦然。 |
modelValue | (M extends true ? T[] : T) | — | 所选项的受控值。
当需要控制项的状态时使用此属性。可通过 `v-model` 进行绑定。 |
defaultValue | (M extends true ? T[] : T) | — | 所选项的默认值。
当需要设置项的初始状态时，请使用此选项。 |
multiple | M | — | 用于确定一次可选择“单个”还是“多个”项目。
此属性将覆盖根据 `modelValue` 和 `defaultValue` 推断出的类型。 |
clearable | boolean | — | 当 `multiple` 为 false 时，是否可以清除所选项目。 |
selectionBehavior | SelectionBehavior | 'toggle' | 集合中多选功能应如何工作。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | M extends true ? T[] : T | — |
ToolbarToggleItem<T>
5 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
value | T | — | 用于标识组内项的唯一值。 |
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
注意事项
架构与对标差异
工具栏家族是多槽组合：ToolbarRoot 提供 roving focus + 方向上下文，每个部分（按钮/链接/分隔线/切换组）复用 button、link、separator、toggle-group 基础组件，UI 包装组件按槽注入 toolbarVariants 类。这与 radix-ui/shadcn-ui 的 headless toolbar/toggle-group 分离一致。Ant Design、Element Plus、Mantine、Naive UI 提供按钮/分段控件而非带方向感知分隔线的专用 roving-focus 工具栏容器；VeanUI 提供带 loop/RTL 支持与 size 尺寸体系的完整工具栏。
| 能力 | VeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
|---|---|---|---|---|---|---|
| Aria/样式分离 | ✅ | ✅ | — | — | — | — |
| Roving focus + loop | ✅ | ✅ | — | — | ✅ | — |
| 方向感知 | ✅ | ✅ | — | — | — | — |
| 切换组 | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| 链接支持 | ✅ | ✅ | — | — | — | — |
| 尺寸（6） | ✅ | — | — | — | — | — |
— = 不支持或采用不同交互模型。
运行时注意
SToolbar渲染role="toolbar"与aria-orientation（默认horizontal/vertical）；分隔线自动翻转以匹配。- Roving focus 使用方向键 + Home/End；
loop循环导航。禁用项与分隔线被跳过。 SToolbarToggleGroup支持单选（model-value字符串）与多选（model-value数组），用v-model绑定。dir/RTL 从ConfigProviderlocale（如ar）推导，或在根组件显式设置。SToolbarLink渲染锚点；showIcon在链接文本旁添加前导图标。
Roadmap
不适用——toolbar 对当前对标集已功能完备。
FAQ
如何构建工具栏？
组合按钮、链接、分隔线与切换组：
<SToolbar>
<SToolbarButton>剪切</SToolbarButton>
<SToolbarButton>复制</SToolbarButton>
<SToolbarSeparator />
<SToolbarToggleGroup v-model="align">
<SToolbarToggleItem value="left">左</SToolbarToggleItem>
<SToolbarToggleItem value="center">中</SToolbarToggleItem>
</SToolbarToggleGroup>
</SToolbar>如何设为垂直？
设置 orientation="vertical"：
<SToolbar orientation="vertical">
<SToolbarButton>上</SToolbarButton>
<SToolbarButton>下</SToolbarButton>
</SToolbar>如何让导航循环？
设置 loop：
<SToolbar loop>
<SToolbarButton>A</SToolbarButton>
<SToolbarButton>B</SToolbarButton>
</SToolbar>如何添加链接？
使用带 href 与 show-icon 的 SToolbarLink：
<SToolbar>
<SToolbarLink href="https://example.com" show-icon>网站</SToolbarLink>
</SToolbar>