TechUI Docs

简中

EN

简中

EN

主题

滚动标签导航 ​

⭐明星组件
👑首创

RollingNavTabs 是一个用于处理变长标签列表的滚动导航组件。 它底层同样基于 TuiRolling 引擎构建，继承了流畅的惯性滚动和动态模糊特性。

与图标导航不同，RollingNavTabs 专为标签页 (Tabs) 场景设计，支持在滚动的头部和尾部插入固定操作区（如“添加按钮”、“菜单按钮”），非常适合用于多文档编辑器、后台管理系统的页签导航等场景。

核心特性 ​

  • Powered by TuiRolling: 拥有极致的滚动性能，支持海量标签的无缝滚动。
  • 首尾插槽系统: 提供 prefix 和 suffix 插槽，允许在滚动区域的“车头”和“车尾”驻留固定元素（如设置图标、折叠菜单）。
  • 灵活的控制栏: 翻页控制器可以配置在头部 (prefix) 或尾部 (suffix)，并支持与插槽内容的顺序反转。
  • 双向布局: 支持 水平 (Horizontal) 和 垂直 (Vertical) 模式。
  • 交互丰富: 支持标签的关闭、锁定、禁用状态，以及拖拽滚动。

基础用法 ​

水平模式 (Horizontal) ​

最常见的页签导航形态。 使用 TuiRollingNavTabs 包裹 TuiRollingNavTab 子组件。

html
<script setup>
import { ref } from 'vue';

const activeTab = ref('tab1');
const tabs = [
  { label: 'Dashboard', value: 'tab1', icon: 'ti-home', locked: true }, // 锁定不可关闭
  { label: 'Settings', value: 'tab2', icon: 'ti-settings' },
  { label: 'Profile', value: 'tab3' },
];

const handleRemove = (index) => {
  tabs.splice(index, 1);
};
</script>

<template>
  <TuiRollingNavTabs 
    v-model="activeTab" 
    direction="h"
    closeable
  >
    <TuiRollingNavTab 
      v-for="(item, index) in tabs" 
      :key="item.value"
      :index="index"
      :value="item.value" 
      :label="item.label" 
      :icon="item.icon"
      :locked="item.locked"
      @remove="handleRemove(index)"
    />
  </TuiRollingNavTabs>
</template>

垂直模式 (Vertical) ​

设置 direction="v" 即可变为侧边栏标签模式。 常用于侧边工具栏或垂直菜单。

html
<template>
  <div style="height: 400px; width: 160px">
    <TuiRollingNavTabs 
      v-model="activeTab" 
      direction="v"
      :itemApproxHeight="40"
    >
      <TuiRollingNavTab 
        v-for="(item, index) in tabs" 
        :key="item.value"
        v-bind="item" 
        :index="index"
      />
    </TuiRollingNavTabs>
  </div>
</template>

布局与插槽 ​

RollingNavTabs 的强大之处在于其灵活的区域划分：

  • 前缀插槽
  • 控制器
  • 滚动视口
  • 控制器
  • 后缀插槽

注入固定内容 ​

通过 #prefix 和 #suffix 插槽，可以在滚动区域的两端添加固定操作按钮。

html
<TuiRollingNavTabs>
  <TuiRollingNavTab ... />

  <template #prefix>
    <i class="tui-icon ti-settings"></i>
  </template>

  <template #suffix>
    <i class="tui-icon ti-plus"></i>
  </template>
</TuiRollingNavTabs>

控制栏位置与反转 ​

  • controlPosition: 决定翻页控制器（< > 箭头）显示在头部 (prefix) 还是尾部 (suffix)。
  • prefixReverse / suffixReverse: 决定控制器与插槽内容的排列顺序。
    • 默认：[插槽内容] [控制器] ...
    • 反转：[控制器] [插槽内容] ...
html
<template>
  <TuiRollingNavTabs 
    controlPosition="prefix" 
    prefixReverse
  >
    <template #prefix><span>Logo</span></template>
    </TuiRollingNavTabs>
</template>

API 参考 ​

TuiRollingNavTabs Props ​

属性名类型默认值说明
modelValueString/Number-当前激活的 Tab 值。
directionString'h'滚动方向。可选：'h', 'v'。
itemApproxWidthNumber140(水平模式) Item 的近似宽度，用于虚拟滚动计算。
itemApproxHeightNumber40(垂直模式) Item 的近似高度。
controlPositionString-控制栏位置。可选：'prefix' (头部), 'suffix' (尾部)。
prefixReverseBooleanfalse是否反转前缀区（插槽与控制器）的顺序。
suffixReverseBooleanfalse是否反转后缀区（插槽与控制器）的顺序。
closeableBooleanfalse是否显示关闭按钮。
motionBlurBooleantrue是否开启滚动动态模糊。
resizeObserverString'global'尺寸监听策略：self, global, none。
durationNumber-滚动动画时长。

TuiRollingNavTab Props ​

属性名类型默认值说明
valueString/Number-Tab 的唯一标识值。
labelString-显示文本。
iconString-图标类名。
indexNumber-必填。索引值，用于计算滚动位置。
disabledBooleanfalse是否禁用。
lockedBooleanfalse是否锁定（锁定后即便开启 closeable 也无法关闭）。

Emits ​

事件名说明回调参数
update:modelValue选中值改变时触发。(value)
change选中项改变时触发。(value, index)
start开始滚动时触发。-
rolling滚动过程中持续触发。(offset)

Slots ​

插槽名说明
default放置 TuiRollingNavTab 列表。
prefix头部固定内容插槽。
suffix尾部固定内容插槽。