标签页

TuiTabs 是一个极其灵活的选项卡切换组件。 它打破了传统 Tabs 只能水平展示的限制，支持上下左右四个方向的布局，并提供多种外观风格。它既可以作为内容切换器，也可以作为页面内导航条使用。

核心特性

• 全向布局: 支持 faceTo 属性控制标签朝向（上/下/左/右），轻松实现侧边导航或底部菜单。
• 三种外观: 提供 simple (简约), card (卡片), button (按钮/分段控制器) 三种风格。
• 双模式渲染: 支持通过 options 数组纯数据驱动，也支持使用 <TuiTab> 组件进行插槽式开发。
• 智能滚动: 当标签数量超出容器时，支持开启 scrollable 模式进行滚动浏览。
• 徽标集成: 内置徽标（Badge）支持，可轻松显示未读数或状态标记。

基础用法

组件插槽模式

使用 <TuiTab> 子组件构建标签。这是最直观的用法，适合需要高度自定义每个标签内容的场景。

<script setup>
import { ref } from 'vue';
const activeName = ref(0);
</script>

<template>
  <TuiTabs v-model="activeName">
    <TuiTab :value="0" label="用户管理" icon="tui-icon ti-user" />
    <TuiTab :value="1" label="系统设置" icon="tui-icon ti-settings" />
    <TuiTab :value="2" label="权限配置" disabled />
  </TuiTabs>
</template>

数据驱动模式

通过 options 属性传入配置数组。代码更简洁，适合动态生成的标签列表。

<script setup>
import { ref } from 'vue';
const activeId = ref('a');

const tabOptions = [
  { label: '首页', value: 'a', icon: 'ti-home' },
  { label: '消息', value: 'b', count: 12, tagType: 'danger' }, // 带徽标
  { label: '设置', value: 'c' }
];
</script>

<template>
  <TuiTabs v-model="activeId" :options="tabOptions" />
</template>

外观风格

通过 appearance 属性切换视觉风格。

• simple (默认): 简约风格，通过下划线（或侧边线）指示选中状态。
• card: 卡片风格，模拟文件夹标签，有边框包裹。
• button: 按钮风格（分段控制器），常用于表单内的模式切换。

<template>
  <TuiTabs appearance="card" v-model="val1" :options="opts" />
  
  <TuiTabs 
    appearance="button" 
    :tagConfig="{ tone: 'strong', round: true }" 
    v-model="val2" 
    :options="opts" 
  />
</template>

朝向与文字排版

TuiTabs 的强大之处在于可以适应各种布局需求。

• faceTo: 控制 Tab 条相对于内容的位置。
  • up (默认): 标准顶部导航。
  • down: 底部导航。
  • left: 左侧垂直导航。
  • right: 右侧垂直导航。
• textDirection: 控制文字排列方向。
  • h (默认): 水平排列。
  • v: 垂直排列（常配合 faceTo="left/right" 使用，实现古风或特殊的侧边栏效果）。

<template>
  <TuiTabs 
    faceTo="left" 
    textDirection="v" 
    style="height: 400px"
    v-model="active" 
    :options="sideOptions" 
  />
</template>

滚动模式

当标签数量过多超出容器宽度（或高度）时，设置 scrollable 为 true 即可开启滚动模式。组件会自动显示左右（或上下）切换箭头。

<template>
  <div style="width: 400px">
    <TuiTabs 
      scrollable 
      :scrollOffset="50"
      v-model="active" 
      :options="longOptions" 
    />
  </div>
</template>

徽标与状态

每个 Tab 项都支持显示徽标（Badge）。

• count: 显示的数值或文本。
• tagType: 徽标的语义颜色 (primary, danger, warning 等)。
• tagConfig: 在 TuiTabs 上配置 tagConfig 可统一控制所有徽标的样式（如 round, tone）。

<template>
  <TuiTabs 
    :tagConfig="{ tone: 'strong', round: true }" 
    :options="[
       { label: '待办', count: 5, tagType: 'danger' },
       { label: '进行中', count: 12, tagType: 'primary' }
    ]" 
  />
</template>

API 参考

TuiTabs Props

属性名	类型	默认值	说明
modelValue	String/Number	-	双向绑定。当前选中的 Tab 值。
options	Array	[]	数据源配置。项对象结构参考下方 TuiTab Props。
appearance	String	'simple'	外观风格。可选：simple, card, button。
faceTo	String	'up'	朝向。可选：up, down, left, right。
textDirection	String	null	文字方向。可选：h (水平), v (垂直)。如果不填则自动适配。
size	String	'default'	尺寸。可选：default, large, small。
align	String	null	对齐方式。可选：start, center, end。
hideBaseLine	Boolean	false	是否隐藏底部的装饰线条（仅 simple/card 模式有效）。
itemMaxWidth	Number/String	-	单个 Tab 项的最大宽度。
scrollable	Boolean	false	是否开启滚动模式。
scrollOffset	Number	0	滚动时的额外偏移量。
tagConfig	Object	-	统一透传给内部 TuiTag 组件的 Props（如 tone, round）。
tipConfig	Object	-	统一透传给 Tooltip 的配置。

TuiTab Props (或 Options 对象字段)

属性名	类型	默认值	说明
value	String/Number	Required	唯一标识值。
label	String	-	标签文本（Slot 模式下为默认插槽内容）。
icon	String	null	图标类名。
count	Number	0	徽标数值。大于 0 时显示。
tagType	String	'default'	徽标颜色类型 (danger, primary 等)。
disabled	Boolean	false	是否禁用该选项。

Events

事件名	说明	回调参数
change	切换选项时触发。	`(value: String
update:modelValue	双向绑定更新。	(value)