BrutxUI

简体中文

English

简体中文

English

外观

Tabs 标签页 ​

基于 reka-ui 的 Tabs 原语构建的新粗野主义风格标签页导航组件。支持水平/垂直布局、受控模式和多种激活状态颜色变体。

预览 ​

Preview

水平布局（默认）

在此修改您的账户信息。完成后请点击保存。

垂直布局

通用设置选项，包括语言、主题等基础配置。

数据驱动模式（tabs prop）

概览

安装 ​

pnpm dlx brutx-vue@latest add tabs

用法 ​

vue
<script setup>
import { Tabs, TabsList, TabsTrigger, TabsContent } from 'brutx-ui-vue/tabs'
</script>

<template>
    <Tabs default-value="account">
        <TabsList>
            <TabsTrigger value="account">Account</TabsTrigger>
            <TabsTrigger value="password">Password</TabsTrigger>
        </TabsList>
        <TabsContent value="account">
            <p class="text-sm">Manage your account settings.</p>
        </TabsContent>
        <TabsContent value="password">
            <p class="text-sm">Change your password here.</p>
        </TabsContent>
    </Tabs>
</template>

垂直布局 ​

通过 Tabs 的 orientation 属性设置垂直布局（vertical）。垂直布局下，TabsList 会自动切换为纵向排列（flex-col），适用于侧边栏导航等场景。

orientation 属性会通过依赖注入传递给子组件，因此 TabsList 无需单独设置即可自动适配方向。如需在单个 TabsList 上覆盖方向，可直接设置其 orientation 属性。

vue
<script setup>
import { Tabs, TabsList, TabsTrigger, TabsContent } from 'brutx-ui-vue/tabs'
</script>

<template>
    <Tabs default-value="general" orientation="vertical" class="flex gap-4">
        <TabsList>
            <TabsTrigger value="general">通用</TabsTrigger>
            <TabsTrigger value="security">安全</TabsTrigger>
            <TabsTrigger value="notifications">通知</TabsTrigger>
        </TabsList>
        <TabsContent value="general">
            <p class="text-sm">通用设置选项。</p>
        </TabsContent>
        <TabsContent value="security">
            <p class="text-sm">安全设置选项。</p>
        </TabsContent>
        <TabsContent value="notifications">
            <p class="text-sm">通知设置选项。</p>
        </TabsContent>
    </Tabs>
</template>

受控模式 ​

使用 v-model 实现受控标签页切换：

vue
<script setup>
import { ref } from 'vue'
import { Tabs, TabsList, TabsTrigger, TabsContent } from 'brutx-ui-vue/tabs'

const currentTab = ref('account')
</script>

<template>
    <Tabs v-model="currentTab">
        <TabsList>
            <TabsTrigger value="account">Account</TabsTrigger>
            <TabsTrigger value="password">Password</TabsTrigger>
        </TabsList>
        <TabsContent value="account">
            <p class="text-sm">Manage your account settings.</p>
        </TabsContent>
        <TabsContent value="password">
            <p class="text-sm">Change your password here.</p>
        </TabsContent>
    </Tabs>
</template>

数据驱动模式（tabs prop） ​

传入 tabs 数组即可让 Tabs 自动渲染 TabsList/TabsTrigger/TabsContent，适用于简单的标签导航场景。未传 tabs 时通过默认插槽组合完整结构。

vue
<script setup lang="ts">
import { Tabs } from 'brutx-ui-vue/tabs'
import type { TabItem } from 'brutx-ui-vue/tabs'

const tabs: TabItem[] = [
    { label: '概览', value: 'overview' },
    { label: '分析', value: 'analytics' },
    { label: '设置', value: 'settings' },
]
</script>

<template>
    <Tabs :tabs="tabs" default-value="overview" />
</template>

自定义内容面板 ​

通过 #default 插槽可替换默认的 Card 展示。插槽会替代默认内容区域，但 TabsList 仍由 tabs 自动渲染：

vue
<script setup lang="ts">
import { Tabs, TabsContent } from 'brutx-ui-vue/tabs'
import type { TabItem } from 'brutx-ui-vue/tabs'

const tabs: TabItem[] = [
    { label: 'Tab A', value: 'a' },
    { label: 'Tab B', value: 'b' },
]
</script>

<template>
    <Tabs :tabs="tabs">
        <template #default>
            <TabsContent value="a">
                <p class="text-sm">自定义 A 内容</p>
            </TabsContent>
            <TabsContent value="b">
                <p class="text-sm">自定义 B 内容</p>
            </TabsContent>
        </template>
    </Tabs>
</template>

tabs 模式下额外提供 header 与 footer 两个命名插槽，用于在标签区块上下方插入辅助内容。tabs 为空数组时会显示 Result fallback，并仍渲染 header/footer 插槽。

受控与自主状态管理 ​

tabs 模式内置双模式状态管理：

  • 传入 modelValue（或使用 v-model）时为受控模式，由父组件主导激活值
  • 未传 modelValue 时为非受控模式，组件内部维护激活值
  • 初始选择依次使用 defaultValue 和首项的 value；选中项被移除后，同样按此顺序回退

变体 ​

TabsTrigger 支持以下激活状态颜色变体：

变体说明
default默认激活状态样式
primaryPrimary（珊瑚色）背景
secondarySecondary 背景
successSuccess（绿色）背景
vue
<template>
    <TabsTrigger value="tab" variant="primary">Primary 变体</TabsTrigger>
</template>

尺寸 ​

TabsList 支持以下容器尺寸：

尺寸说明
sm小尺寸
default默认尺寸
lg大尺寸

子组件 ​

组件说明
Tabs根组件（包装 reka-ui 的 TabsRoot）
TabsList标签触发器容器
TabsTrigger可点击的标签按钮
TabsContent每个标签的内容面板

导出类型 ​

从 brutx-ui-vue/tabs 子路径导入：

ts
import {
    Tabs,
    TabsList,
    TabsTrigger,
    TabsContent,
    tabsListVariants,
    tabsTriggerVariants,
    tabsContentVariants,
} from 'brutx-ui-vue/tabs'
import type { TabItem } from 'brutx-ui-vue/tabs'
import { TabsRoot } from 'reka-ui'

TabItem ​

tabs prop 的数据项类型：

ts
interface TabItem {
    label: string
    value: string
    disabled?: boolean
}
属性类型说明
labelstring标签显示文本
valuestring标签唯一标识
disabledboolean是否禁用此标签（可选）

组合式函数 ​

组件导出了以下变体工具函数，可用于自定义样式扩展：

ts
import {
    tabsListVariants,
    tabsTriggerVariants,
    tabsContentVariants,
} from 'brutx-ui-vue/tabs'
函数变体参数说明
tabsListVariantssize: 'sm' | 'default' | 'lg'，orientation: 'horizontal' | 'vertical'容器样式变体
tabsTriggerVariantsvariant: 'default' | 'primary' | 'secondary' | 'success'触发器样式变体
tabsContentVariants—内容面板基础样式

API 参考 ​

Tabs

Tabs — 属性
名称类型默认值说明
modelValue
string | undefined
undefined
受控模式下当前激活的标签页值，支持 v-model；为 undefined 时由组件维护选择状态。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/Tabs.vue

解析值
undefined

来源

Tabs.vue:16

packages/ui/src/components/tabs/Tabs.vue

defaultValue
string | undefined
undefined

运行时回退:未提供时，数据驱动模式使用 tabs 首项的 value；组合模式交由底层 TabsRoot 处理初始状态。

非受控模式的初始标签页值，也用于数据列表中当前选择失效后的回退。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/Tabs.vue

解析值
undefined
运行时回退
未提供时，数据驱动模式使用 tabs 首项的 value；组合模式交由底层 TabsRoot 处理初始状态。

组件在说明的运行条件下采用此回退值。

来源

Tabs.vue:17

packages/ui/src/components/tabs/Tabs.vue

tabs
TabItem[] | undefined
undefined
标签页数据列表。非空时自动渲染触发器与默认内容面板；空数组显示本地化空状态；未提供时通过默认插槽自行组合。
详情

声明类型

TabItem[] | undefined

关联类型

TabItem
类型定义 — TabItem
export interface TabItem {
    label: string
    value: string
    disabled?: boolean
}

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/Tabs.vue

解析值
undefined

来源

Tabs.vue:18

packages/ui/src/components/tabs/Tabs.vue

orientation
"vertical" | "horizontal" | undefined
"horizontal"
标签页根状态的排列方向和键盘导航方向，也为 TabsList 提供默认方向。
详情

声明类型

"vertical" | "horizontal" | undefined

字面量

  • "horizontal"
  • "vertical"

默认值详情

声明
'horizontal'

来源: packages/ui/src/components/tabs/Tabs.vue

解析值
"horizontal"

来源

Tabs.vue:19

packages/ui/src/components/tabs/Tabs.vue

class
string | undefined
undefined
自定义 CSS 类；提供 tabs 时作用于外层容器，组合模式下作用于 TabsRoot。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/Tabs.vue

解析值
undefined

来源

Tabs.vue:20

packages/ui/src/components/tabs/Tabs.vue

Tabs — 事件
名称签名或类型说明
@update:modelValue
[value: string]
激活标签页改变时发出新的字符串值；非受控模式同时更新内部选择。
详情

声明类型

[value: string]

来源

Tabs.vue

packages/ui/src/components/tabs/Tabs.vue

Tabs — 插槽
名称签名或类型说明
#header
{}
数据驱动模式下位于标签页区域上方的内容；tabs 为空数组时仍显示。
详情

声明类型

{}

来源

Tabs.vue

packages/ui/src/components/tabs/Tabs.vue

#default
{}
组合模式下放置完整标签页结构；数据驱动模式下替换自动生成的内容面板，需自行放置 TabsContent。tabs 为空数组时不渲染此插槽。
详情

声明类型

{}

来源

Tabs.vue

packages/ui/src/components/tabs/Tabs.vue

TabsContent

TabsContent — 属性
名称类型默认值说明
value
必填
string
—
此内容面板对应的标签页值，应与 TabsTrigger 的 value 一致。
详情

声明类型

string

默认值详情

未声明默认值
—

来源

TabsContent.vue:8

packages/ui/src/components/tabs/TabsContent.vue

surface
TabsContentSurface | undefined
"plain"
外壳渲染模式：plain 为零边距贴合（适合内嵌 Card），panel 为带实体边框与阴影的独立卡片面板。
详情

声明类型

TabsContentSurface | undefined

字面量

  • "panel"
  • "plain"

关联类型

TabsContentSurface
类型定义 — TabsContentSurface
export type TabsContentSurface = NonNullable<TabsContentVariantProps['surface']>

默认值详情

声明
'plain'

来源: packages/ui/src/components/tabs/TabsContent.vue

解析值
"plain"

来源

TabsContent.vue:9

packages/ui/src/components/tabs/TabsContent.vue

forceMount
boolean | undefined
undefined
保持内容面板挂载，以便控制外部动画或保留面板实例。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/TabsContent.vue

解析值
undefined

来源

TabsContent.vue:10

packages/ui/src/components/tabs/TabsContent.vue

class
string | undefined
undefined
合并到标签页内容面板的自定义 CSS 类。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/TabsContent.vue

解析值
undefined

来源

TabsContent.vue:11

packages/ui/src/components/tabs/TabsContent.vue

TabsContent — 插槽
名称签名或类型说明
#default
{}
此标签页对应的内容。
详情

声明类型

{}

来源

TabsContent.vue

packages/ui/src/components/tabs/TabsContent.vue

TabsList

TabsList — 属性
名称类型默认值说明
size
"default" | "lg" | "sm" | undefined
"default"
标签列表容器的尺寸变体。
详情

声明类型

NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined

字面量

  • "default"
  • "lg"
  • "sm"

默认值详情

声明
'default'

来源: packages/ui/src/components/tabs/TabsList.vue

解析值
"default"

来源

TabsList.vue:12

packages/ui/src/components/tabs/TabsList.vue

orientation
"horizontal" | "vertical" | undefined
undefined

运行时回退:依次使用此属性、父 Tabs 注入的方向、horizontal。

覆盖标签列表自身的布局样式与 data-orientation，不改变根 Tabs 的键盘方向设置。
详情

声明类型

NonNullable<"vertical" | "horizontal" | null | undefined> | undefined

字面量

  • "horizontal"
  • "vertical"

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/TabsList.vue

解析值
undefined
运行时回退
依次使用此属性、父 Tabs 注入的方向、horizontal。

组件在说明的运行条件下采用此回退值。

来源

TabsList.vue:13

packages/ui/src/components/tabs/TabsList.vue

class
string | undefined
undefined
合并到标签列表容器的自定义 CSS 类。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/TabsList.vue

解析值
undefined

来源

TabsList.vue:14

packages/ui/src/components/tabs/TabsList.vue

TabsList — 插槽
名称签名或类型说明
#default
{}
标签触发器列表，通常放置 TabsTrigger。
详情

声明类型

{}

来源

TabsList.vue

packages/ui/src/components/tabs/TabsList.vue

TabsTrigger

TabsTrigger — 属性
名称类型默认值说明
value
必填
string
—
标签页的唯一字符串标识，用于关联对应的 TabsContent。
详情

声明类型

string

默认值详情

未声明默认值
—

来源

TabsTrigger.vue:11

packages/ui/src/components/tabs/TabsTrigger.vue

disabled
boolean | undefined
false
禁用此标签页触发器，阻止用户激活。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
false

来源: packages/ui/src/components/tabs/TabsTrigger.vue

解析值
false

来源

TabsTrigger.vue:12

packages/ui/src/components/tabs/TabsTrigger.vue

variant
"accent" | "default" | "primary" | "secondary" | "slots" | "success" | undefined
"default"
触发器的视觉变体，控制激活状态的配色及装饰。
详情

声明类型

NonNullable<"default" | "primary" | "secondary" | "success" | "accent" | "slots" | null | undefined> | undefined

字面量

  • "accent"
  • "default"
  • "primary"
  • "secondary"
  • "slots"
  • "success"

默认值详情

声明
'default'

来源: packages/ui/src/components/tabs/TabsTrigger.vue

解析值
"default"

来源

TabsTrigger.vue:13

packages/ui/src/components/tabs/TabsTrigger.vue

class
string | undefined
undefined
合并到标签页触发器的自定义 CSS 类。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tabs/TabsTrigger.vue

解析值
undefined

来源

TabsTrigger.vue:14

packages/ui/src/components/tabs/TabsTrigger.vue

TabsTrigger — 插槽
名称签名或类型说明
#default
{}
标签页触发器的文字、图标或其他标签内容。
详情

声明类型

{}

来源

TabsTrigger.vue

packages/ui/src/components/tabs/TabsTrigger.vue

可访问性 ​

  • 键盘操作：方向键在标签触发器之间导航
  • ARIA 属性：标签内容通过 ARIA 属性与其触发器关联，激活标签具有 aria-selected="true"

蛮力铸就。

© 2026 BrutxUI · MIT License