Tab 标签页 - Vant 4

Tab 标签页 📑

介绍

🎯 Tab 标签页 是一个超级实用的选项卡组件！它就像书本的目录一样，让你可以在不同的内容区域之间轻松切换。无论是展示商品分类、新闻类别，还是设置页面的不同选项，Tab 组件都能让你的界面变得井井有条，用户体验倍儿棒！

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { Tab, Tabs } from 'vant';

const app = createApp();
app.use(Tab);
app.use(Tabs);

代码演示

基础用法 🚀

最简单的使用方式！通过 v-model:active 绑定当前激活标签对应的索引值，默认情况下会启用第一个标签。就像翻书一样，从第一页开始阅读！

import { ref } from'vue'; exportdefault { setup() { const active = ref(0); return { active }; }, };

通过名称匹配 🏷️

想要更精确地控制标签？给每个标签指定一个独特的 name 属性吧！这样 v-model:active 的值就是当前标签的 name，就像给每个房间都贴上门牌号一样清晰明了！

<van-tabs v-model:active="activeName">
  <van-tab title="标签 1" name="a">内容 1</van-tab>
  <van-tab title="标签 2" name="b">内容 2</van-tab>
  <van-tab title="标签 3" name="c">内容 3</van-tab>
</van-tabs>

import { ref } from 'vue';

export default {
  setup() {
    const activeName = ref('b');
    return { activeName };
  },
};

标签栏滚动 📱

当标签太多装不下时怎么办？别担心！当标签数量超过 5 个时，标签栏会自动开启水平滚动模式，就像手机上的应用图标一样可以左右滑动。更贴心的是，切换时会自动将当前标签居中显示！

<van-tabs v-model:active="active">
  <van-tab v-for="index in 8" :title="`标签 ${index}`">
    内容 {{ index }}
  </van-tab>
</van-tabs>

禁用标签 🚫

有些标签暂时不想让用户点击？设置 disabled 属性就能轻松禁用标签，就像给门上了锁一样！

<van-tabs v-model:active="active">
  <van-tab title="标签 1">内容 1</van-tab>
  <van-tab title="标签 2" disabled>内容 2</van-tab>
  <van-tab title="标签 3">内容 3</van-tab>
</van-tabs>

样式风格 🎨

Tab 组件就像变色龙一样灵活！支持两种超棒的样式风格：经典的 line 线条风格和时尚的 card 卡片风格。默认是 line 样式，通过 type 属性就能轻松切换，让你的界面瞬间换个风格！

<van-tabs v-model:active="active" type="card">
  <van-tab title="标签 1">内容 1</van-tab>
  <van-tab title="标签 2">内容 2</van-tab>
  <van-tab title="标签 3">内容 3</van-tab>
</van-tabs>

点击事件 👆

想知道用户点击了哪个标签？click-tab 事件来帮忙！每次点击标签页时都会触发这个事件，让你能够及时响应用户的操作。

import { ref } from'vue'; import { showToast } from'vant'; exportdefault { setup() { const active = ref(0); constonClickTab = ({ title }) => showToast(title); return { active, onClickTab, }; }, };

粘性布局 📌

想让标签栏始终保持在用户视野中？开启 sticky 粘性布局吧！就像便利贴一样，当页面向下滚动时，标签栏会自动"粘"在顶部，让用户随时都能切换标签，超级方便！

<van-tabs v-model:active="active" sticky>
  <van-tab title="标签 1">内容 1</van-tab>
  <van-tab title="标签 2">内容 2</van-tab>
  <van-tab title="标签 3">内容 3</van-tab>
</van-tabs>

💡 小贴士: 如果页面顶部有其他内容（比如导航栏），可以通过 offset-top 属性设置吸顶时与顶部的距离，避免重叠哦！

收缩布局 📏

不想让标签占满整个宽度？通过 shrink 属性开启收缩布局，所有标签会乖乖地向左侧收缩对齐，就像排队一样整整齐齐！

<van-tabs v-model:active="active" shrink>
  <van-tab title="标签 1">内容 1</van-tab>
  <van-tab title="标签 2">内容 2</van-tab>
  <van-tab title="标签 3">内容 3</van-tab>
</van-tabs>

自定义标签 🎭

想让标签更有个性？通过 title 插槽可以完全自定义标签内容！添加图标、徽章、甚至小动画都没问题，让你的标签与众不同！

<van-tabs v-model:active="active">
  <van-tab>
    <template #title>
      <van-icon name="more-o" />
      自定义
    </template>
    内容 1
  </van-tab>
  <van-tab title="标签 2">内容 2</van-tab>
</van-tabs>

切换动画 ✨

想让标签切换更加丝滑？开启 animated 属性，切换标签内容时会有优雅的转场动画，就像翻页一样流畅自然！

<van-tabs v-model:active="active" animated>
  <van-tab title="标签 1">内容 1</van-tab>
  <van-tab title="标签 2">内容 2</van-tab>
  <van-tab title="标签 3">内容 3</van-tab>
</van-tabs>

滑动切换 👈👉

想要更自然的交互体验？开启 swipeable 属性，用户就可以通过手势左右滑动来切换标签页，就像翻阅相册一样直观！

<van-tabs v-model:active="active" swipeable>
  <van-tab title="标签 1">内容 1</van-tab>
  <van-tab title="标签 2">内容 2</van-tab>
  <van-tab title="标签 3">内容 3</van-tab>
</van-tabs>

滚动导航 📜

需要展示长内容？开启 scrollspy 滚动导航模式，内容会平铺展示，标签会根据滚动位置自动高亮对应的区域，就像文档目录一样智能！

<van-tabs v-model:active="active" scrollspy sticky>
  <van-tab title="标签 1">内容 1</van-tab>
  <van-tab title="标签 2">内容 2</van-tab>
  <van-tab title="标签 3">内容 3</van-tab>
</van-tabs>

异步切换 ⏳

需要在切换前做一些检查或异步操作？before-change 属性来帮忙！可以在切换标签前执行特定的逻辑，比如权限验证、数据保存等。

import { ref } from'vue'; exportdefault { setup() { const active = ref(0); constbeforeChange = (index) => { // 返回 false 表示阻止此次切换if (index === 1) { returnfalse; } // 返回 Promise 来执行异步逻辑returnnewPromise((resolve) => { // 在 resolve 函数中返回 true 或 falsesetTimeout(() =>resolve(index !== 3), 1000); }); }; return { beforeChange, }; }, };

Tips: 通过手势滑动不会触发 before-change 属性。

隐藏标题栏

通过将 showHeader 属性设置为 false，可以不渲染 Tabs 的标题栏。在这种情况下，你可以通过一些自定义组件来控制 Tabs 的 active 属性。

API

Tabs Props

参数	说明	类型	默认值
v-model:active	🎯 绑定当前选中标签的标识符	number | string	0
type	🎨 样式风格类型，可选值为 card	string	line
color	🌈 标签主题色	string	#1989fa
background	🎭 标签栏背景色	string	white
duration	⏱️ 动画时间，单位秒，设置为 0 可以禁用动画	number | string	0.3
line-width	📏 底部条宽度，默认单位 px	number | string	40px
line-height	📐 底部条高度，默认单位 px	number | string	3px
animated	✨ 是否开启切换标签内容时的转场动画（开启该属性后，内容区如果有粘性布局将会不达预期）	boolean	false
border	🖼️ 是否显示标签栏外边框，仅在 type="line" 时有效	boolean	false
ellipsis	✂️ 是否省略过长的标题文字（仅在 shrink 为 false 且 tab 数量小于等于 swipe-threshold 时生效）	boolean	true
sticky	📌 是否使用粘性布局	boolean	false
shrink	📏 是否开启左侧收缩布局	boolean	false
swipeable	👈👉 是否开启手势左右滑动切换（开启该属性后，内容区如果有粘性布局将会不达预期）	boolean	false
lazy-render	🚀 是否开启延迟渲染（首次切换到标签时才触发内容渲染）	boolean	true
scrollspy	📜 是否开启滚动导航	boolean	false
show-header v4.7.3	👁️ 是否显示标题栏	boolean	true
offset-top	📍 粘性布局下吸顶时与顶部的距离，支持 px``vw``vh``rem 单位，默认 px	number | string	0
swipe-threshold	🎚️ 滚动阈值，标签数量超过阈值且总宽度超过标签栏宽度时开始横向滚动（仅在 shrink 为 false 且 ellipsis 为 true 时生效）	number | string	5
title-active-color	🎨 标题选中态颜色	string	-
title-inactive-color	🎨 标题默认态颜色	string	-
before-change	⏳ 切换标签前的回调函数，返回 false 可阻止切换，支持返回 Promise	(name: number | string) => boolean | Promise<boolean>	-

Tab Props

参数	说明	类型	默认值
title	📝 标题	string	-
disabled	🚫 是否禁用标签	boolean	false
dot	🔴 是否在标题右上角显示小红点	boolean	false
badge	🏷️ 图标右上角徽标的内容（dot 为 false 时生效）	number | string	-
name	🏷️ 标签名称，作为匹配的标识符	number | string	标签的索引值
url	🔗 点击后跳转的链接地址	string	-
to	🧭 点击后跳转的目标路由对象，等同于 Vue Router 的 to 属性	string | object	-
replace	🔄 是否在跳转时替换当前页面历史	boolean	false
title-style	🎨 自定义标题样式	string | Array | object	-
title-class	🎭 自定义标题类名	string | Array | object	-
show-zero-badge	0️⃣ 当 badge 为数字 0 时，是否展示徽标	boolean	true

Tabs Events

事件名	说明	回调参数
click-tab	👆 点击标签时触发	{ name: string | number, title: string, event: MouseEvent, disabled: boolean }
change	🔄 当前激活的标签改变时触发	name: string | number, title: string
rendered	🎨 标签内容首次渲染时触发（仅在开启延迟渲染后触发）	name: string | number, title: string
scroll	📜 滚动时触发，仅在 sticky 模式下生效	{ scrollTop: number, isFixed: boolean }

提示：click 和 disabled 事件已废弃，请使用 click-tab 事件代替。

Tabs 方法

通过 ref 可以获取到 Tabs 实例并调用实例方法，详见组件实例方法。

方法名	说明	参数	返回值
resize	外层元素大小或组件显示状态变化时，可以调用此方法来触发重绘	-	-
scrollTo	滚动到指定的标签页，在滚动导航模式下可用	*name: string	number*

类型定义

组件导出以下类型定义：

importtype { TabProps, TabsType, TabsProps, TabsInstance } from'vant';

TabsInstance 是组件实例的类型，用法如下：

import { ref } from'vue'; importtype { TabsInstance } from'vant'; const tabsRef = ref<TabsInstance>(); tabsRef.value?.scrollTo(0);

Tabs Slots

名称	说明
nav-left	标签栏左侧内容
nav-right	标签栏右侧内容
nav-bottom	标签栏下方内容

Tab Slots

名称	说明
default	标签页内容
title	自定义标题

主题定制 🎨

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-tab-text-color	var(--van-gray-7)	📝 标签文字颜色
--van-tab-active-text-color	var(--van-text-color)	✨ 激活标签文字颜色
--van-tab-disabled-text-color	var(--van-text-color-3)	🚫 禁用标签文字颜色
--van-tab-font-size	var(--van-font-size-md)	📏 标签文字大小
--van-tab-line-height	var(--van-line-height-md)	📐 标签文字行高
--van-tabs-default-color	var(--van-primary-color)	🎨 标签栏默认颜色
--van-tabs-line-height	44px	📏 标签栏高度
--van-tabs-card-height	30px	🃏 卡片样式标签高度
--van-tabs-nav-background	var(--van-background-2)	🎭 标签栏背景色
--van-tabs-bottom-bar-width	40px	📏 底部指示条宽度
--van-tabs-bottom-bar-height	3px	📐 底部指示条高度
--van-tabs-bottom-bar-color	var(--van-primary-color)	🌈 底部指示条颜色

常见问题

组件从隐藏状态切换到显示状态时，底部条位置错误？

Tabs 组件在挂载时，会获取自身的宽度，并计算出底部条的位置。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法展示底部条位置。

解决方法

方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：

方法二，调用组件的 resize 方法来主动触发重绘：

this.$refs.tabs.resize();

Tabs 开启 swipeable 或 animated 属性后，内容区元素的 sticky 功能将不达预期

Tabs 开启 swipeable 或 animated 属性后，内容区将被带有 transform 属性的元素包裹，此时如果内容区的元素开启了 sticky 功能，那么该功能生效了，但显示位置将不达预期。

比如下面的代码：

这是因为 transform 元素内部的 fixed 定位会相对于该元素进行计算，而不是相对于整个文档，从而导致布局异常。

如何判断当前组件是否处于激活的 Tab 内？

可以在子组件中通过调用 useTabStatus 或 useAllTabStatus 来判断当前组件是否处于激活的 Tab 内部。

• useTabStatus：返回当前组件所在的 Tab 是否为激活状态，若组件不在 Tab 内部则返回 null。
• useAllTabStatus：在存在嵌套 Tab 的场景下，返回是否所有上层 Tab 为激活状态，若组件不在 Tab 内部则返回 null。

const isActive = useTabStatus(); 
// 嵌套 Tab 场景
const isAllActive = useAllTabStatus();

相关文档 📚

导航组件 🧭

• NavBar 导航栏 - 页面顶部导航，与 Tab 搭配使用
• Tabbar 标签栏 - 底部标签栏，用于页面级切换
• Sidebar 侧边导航 - 侧边栏导航，适合多层级内容
• IndexBar 索引栏 - 字母索引导航

展示组件 📱

• NoticeBar 通知栏 - 消息通知展示
• Progress 进度条 - 进度展示
• Badge 徽标 - 数字或状态标记
• Tag 标签 - 内容标记和分类

反馈组件 💬

• Toast 轻提示 - 操作反馈提示
• Dialog 弹出框 - 重要信息确认
• Loading 加载 - 加载状态展示

工具组件 🔧

• ConfigProvider 全局配置 - 主题定制配置