介紹

選項卡組件，用于在不同的內容區(qū)域之間進行切換。

引入

通過以下方式來全局注冊組件，更多注冊方式請參考組件注冊。

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

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

代碼演示

基礎用法

通過 ?v-model:active? 綁定當前激活標簽對應的索引值，默認情況下啟用第一個標簽。

<van-tabs v-model:active="active">
  <van-tab title="標簽 1">內容 1</van-tab>
  <van-tab title="標簽 2">內容 2</van-tab>
  <van-tab title="標簽 3">內容 3</van-tab>
  <van-tab title="標簽 4">內容 4</van-tab>
</van-tabs>

import { ref } from 'vue';

export default {
  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('a');
    return { activeName };
  },
};

標簽欄滾動

標簽數(shù)量超過 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>

點擊事件

點擊標簽頁時，會觸發(fā) ?click-tab? 事件。

<van-tabs v-model:active="active" @click-tab="onClickTab">
  <van-tab title="標簽 1">內容 1</van-tab>
  <van-tab title="標簽 2">內容 2</van-tab>
</van-tabs>

import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const active = ref(0);
    const onClickTab = ({ title }) => showToast(title);
    return {
      active,
      onClickTab,
    };
  },
};

粘性布局

通過 ?sticky? 屬性可以開啟粘性布局，粘性布局下，標簽頁滾動到頂部時會自動吸頂。

<van-tabs v-model:active="active" sticky>
  <van-tab v-for="index in 4" :title="'選項 ' + index">
    內容 {{ index }}
  </van-tab>
</van-tabs>

Tips: 如果頁面頂部有其他內容，可以通過 offset-top 屬性設置吸頂時與頂部的距離。

收縮布局

通過 ?shrink? 屬性可以開啟收縮布局，開啟后，所有的標簽會向左側收縮對齊。

<van-tabs v-model:active="active" shrink>
  <van-tab v-for="index in 4" :title="'選項 ' + index">
    內容 {{ index }}
  </van-tab>
</van-tabs>

自定義標簽

通過 ?title? 插槽可以自定義標簽內容。

<van-tabs v-model:active="active">
  <van-tab v-for="index in 2">
    <template #title> <van-icon name="more-o" />選項 </template>
    內容 {{ index }}
  </van-tab>
</van-tabs>

切換動畫

通過 ?animated? 屬性可以開啟切換標簽內容時的轉場動畫。

<van-tabs v-model:active="active" animated>
  <van-tab v-for="index in 4" :title="'選項 ' + index">
    內容 {{ index }}
  </van-tab>
</van-tabs>

滑動切換

通過 ?swipeable? 屬性可以開啟滑動切換標簽頁。

<van-tabs v-model:active="active" swipeable>
  <van-tab v-for="index in 4" :title="'選項 ' + index">
    內容 {{ index }}
  </van-tab>
</van-tabs>

滾動導航

通過 ?scrollspy? 屬性可以開啟滾動導航模式，該模式下，內容將會平鋪展示。

<van-tabs v-model:active="active" scrollspy sticky>
  <van-tab v-for="index in 8" :title="'選項 ' + index">
    內容 {{ index }}
  </van-tab>
</van-tabs>

異步切換

通過 ?before-change? 屬性可以在切換標簽前執(zhí)行特定的邏輯。

<van-tabs v-model:active="active" :before-change="beforeChange">
  <van-tab v-for="index in 4" :title="'選項 ' + index">
    內容 {{ index }}
  </van-tab>
</van-tabs>

import { ref } from 'vue';

export default {
  setup() {
    const active = ref(0);
    const beforeChange = (index) => {
      // 返回 false 表示阻止此次切換
      if (index === 1) {
        return false;
      }

      // 返回 Promise 來執(zhí)行異步邏輯
      return new Promise((resolve) => {
        // 在 resolve 函數(shù)中返回 true 或 false
        resolve(index !== 3);
      });
    };

    return {
      beforeChange,
    };
  },
};

Tips: 通過手勢滑動不會觸發(fā) before-change 屬性。

API

Tabs Props

Tab Props

Tabs Events

提示：click 和 disabled 事件已廢棄，請使用 click-tab 事件代替。

Tabs 方法

通過 ref 可以獲取到 Tabs 實例并調用實例方法，詳見組件實例方法。

類型定義

組件導出以下類型定義：

import type { TabProps, TabsType, TabsProps, TabsInstance } from 'vant';

?TabsInstance? 是組件實例的類型，用法如下：

import { ref } from 'vue';
import type { TabsInstance } from 'vant';

const tabsRef = ref<TabsInstance>();

tabsRef.value?.scrollTo(0);

Tabs Slots

Tab Slots

主題定制

樣式變量

組件提供了下列 CSS 變量，可用于自定義樣式，使用方法請參考 ConfigProvider 組件。

常見問題

組件從隱藏狀態(tài)切換到顯示狀態(tài)時，底部條位置錯誤？

Tabs 組件在掛載時，會獲取自身的寬度，并計算出底部條的位置。如果組件一開始處于隱藏狀態(tài)，則獲取到的寬度永遠為 0，因此無法展示底部條位置。

解決方法

方法一，如果是使用 ?v-show? 來控制組件展示的，則替換為 ?v-if? 即可解決此問題：

<!-- Before -->
<van-tabs v-show="show" />
<!-- After -->
<van-tabs v-if="show" />

方法二，調用組件的 resize 方法來主動觸發(fā)重繪：

<van-tabs v-show="show" ref="tabs" />

this.$refs.tabs.resize();