v1.7
GitHub 儲存庫

標籤

輕鬆建立可存取的、 полностью可自訂的標籤介面，具備功能強大的焦點管理和鍵盤導覽支援。

請透過 npm 安裝無頭 UI 以開始進行操作

npm install @headlessui/vue

標籤使用 標籤群組、標籤清單、標籤、標籤面板 和 標籤面板 元件來建立。預設情況下，選取第一個標籤，按一下任何標籤或使用鍵盤選取它將啟動對應的面板。

<template>
  <TabGroup>
    <TabList>
      <Tab>Tab 1</Tab>
      <Tab>Tab 2</Tab>
      <Tab>Tab 3</Tab>
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <TabPanel>Content 2</TabPanel>
      <TabPanel>Content 3</TabPanel>
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'
</script>

無頭 UI 會追蹤許多關於每個元件的狀態，例如目前勾選的是哪個標籤選項、彈出視窗是開啟還是關閉，或目前使用鍵盤在功能表中選取哪個項目。

但是因為元件是無頭的，而且預設裝置完全沒有樣式，所以在你為每個狀態提供你想要的樣式之前，你無法在 UI 中看見此資訊。

每個元件透過 插槽 props 顯示其目前狀態的資訊，你可以使用這些資訊有條件套用不同的樣式或呈現不同的內容。

例如，標籤 元件會顯示一個 selected 狀態，告知你目前是否選取標籤。

<template>
  <TabGroup>
    <TabList>
      <!-- Use the `selected` state to conditionally style the selected tab. -->

      <Tab as="template" v-slot="{ selected }">
        <button

          :class="{ 'bg-blue-500 text-white': selected, 'bg-white text-black': !selected }"
        >
          Tab 1
        </button>
      </Tab>
      <!-- ... -->
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <!-- ... -->
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'
</script>

每個元件的完整插槽 props API，請參閱 元件 API 文件。

各元件也會透過 `data-headlessui-state` 屬性公開其當前狀態的資訊，您可以使用它有條件地套用不同的樣式。

當在 插槽屬性 API 中的任何狀態為 `true` 時，它們會在此屬性中以空白分隔的字串列出，因此您可以使用表單中的 CSS 屬性選取器 `[attr~=value]` 來針對它們。

例如，以下是當第二個標籤 `selected` 時，具有子 `Tab` 元件的 `TabGroup` 元件所呈現的內容

<!-- Rendered `TabGroup` -->
<div>
  <button data-headlessui-state="">Tab 1</button>
  <button data-headlessui-state="selected">Tab 2</button>
  <button data-headlessui-state="">Tab 3</button>
</div>
<div>
  <div data-headlessui-state="">Content 1</div>
  <div data-headlessui-state="selected">Content 2</div>
  <div data-headlessui-state="">Content 3</div>
</div>

如果您正在使用 Tailwind CSS，您可以使用 @headlessui/tailwindcss 外掛程式，搭配像 `ui-open:*` 這類修改器來針對此屬性。

<template>
  <TabGroup>
    <TabList>
      <Tab

        class="ui-selected:bg-blue-500 ui-selected:text-white ui-not-selected:bg-white ui-not-selected:text-black"
      >
        Tab 1
      </Tab>
      <!-- ... -->
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <!-- ... -->
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'
</script>

若要停用標籤，請對 `Tab` 元件使用 `disabled` 屬性。已停用的標籤無法使用滑鼠選取，且在使用鍵盤瀏覽標籤清單時也會被略過。

<template>
  <TabGroup>
    <TabList>
      <Tab>Tab 1</Tab>

      <Tab disabled>Tab 2</Tab>
      <Tab>Tab 3</Tab>
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <TabPanel>Content 2</TabPanel>
      <TabPanel>Content 3</TabPanel>
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'
</script>

預設情況下，標籤會在使用者使用箭頭鍵瀏覽時自動選取。

如果您不想在使用者按下 `Enter` 或 `Space` 之前變更目前標籤，請使用 `TabGroup` 元件上的 `manual` 屬性。如果選取標籤會執行昂貴的作業，而且您不想不必要地執行它，這會很有用。

<template>

  <TabGroup manual>
    <TabList>
      <Tab>Tab 1</Tab>
      <Tab>Tab 2</Tab>
      <Tab>Tab 3</Tab>
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <TabPanel>Content 2</TabPanel>
      <TabPanel>Content 3</TabPanel>
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'
</script>

`manual` 屬性對滑鼠互動沒有影響，標籤仍會在按一下它們時立即被選取。

如果您已設定 `TabList` 垂直顯示，請使用 `vertical` 屬性，以啟用使用向上和向下箭頭鍵瀏覽，而不是向左和向右，並針對輔助技術更新 `aria-orientation` 屬性。

<template>

  <TabGroup vertical>
    <TabList>
      <Tab>Tab 1</Tab>
      <Tab>Tab 2</Tab>
      <Tab>Tab 3</Tab>
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <TabPanel>Content 2</TabPanel>
      <TabPanel>Content 3</TabPanel>
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'
</script>

若要變更預設選取的標籤，請在 `TabGroup` 元件上使用 `:defaultIndex="number"` 屬性。

<template>

  <TabGroup :defaultIndex="1">
    <TabList>
      <Tab>Tab 1</Tab>


      <!-- Selects this tab by default -->
      <Tab>Tab 2</Tab>

      <Tab>Tab 3</Tab>
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>


      <!-- Displays this tab by default -->
      <TabPanel>Content 2</TabPanel>

      <TabPanel>Content 3</TabPanel>
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'
</script>

如果您提供的索引超出範圍，則在初始呈現時會選取最後一個未停用的標籤。(例如，上方範例中的 `<TabGroup :defaultIndex="5"` 會呈現選取第三個面板。)

使用 `TabGroup` 元件中的 `@change` 事件，當選取的標籤切換時，執行函式。

<template>

  <TabGroup @change="changeTab">
    <TabList>
      <Tab>Tab 1</Tab>
      <Tab>Tab 2</Tab>
      <Tab>Tab 3</Tab>
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <TabPanel>Content 2</TabPanel>
      <TabPanel>Content 3</TabPanel>
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'


  function changeTab(index) {
    console.log('Changed active tab to:', index)
  }
</script>

此標籤元件也可以當成受控的元件。要執行這個動作，提供 `selectedIndex` 並自己管理狀態。

<template>

  <TabGroup :selectedIndex="selectedTab" @change="changeTab">
    <TabList>
      <Tab>Tab 1</Tab>
      <Tab>Tab 2</Tab>
      <Tab>Tab 3</Tab>
    </TabList>
    <TabPanels>
      <TabPanel>Content 1</TabPanel>
      <TabPanel>Content 2</TabPanel>
      <TabPanel>Content 3</TabPanel>
    </TabPanels>
  </TabGroup>
</template>

<script setup>
  import { ref } from 'vue'
  import { TabGroup, TabList, Tab, TabPanels, TabPanel } from '@headlessui/vue'


  const selectedTab = ref(0)


  function changeTab(index) {
    selectedTab.value = index
  }
</script>

按一下 `Tab` 將會選取該標籤，並顯示相對應的 `TabPanel`。

在將焦點放在 `Tab` 元件時，會套用所有互動。

指令說明

ArrowLeft與ArrowRight

選取上一個/下一個未停用的標籤。

ArrowUp與ArrowDown在設定 `vertical` 時

選取上一個/下一個未停用的標籤。

Home或PageUp

選取第一個未停用的標籤。

End或PageDown

選取最後一個未停用的標籤。

Enter或Space在設定為manual時

啟動已選取的標籤。

所有相關的 ARIA 屬性均自動管理。

關於所有已實現的輔助功能的完整參考，請造訪ARIA spec on Tabs。

主要的標籤群組組件。

Prop預設值說明
作為範本
字串 | 組件

標籤群組應該呈現為的元素或組件。

defaultIndex0
數字

預設的已選取索引

selectedIndex—
數字

如果您想將標籤組件用作受控組件，則為已選取的索引。

verticalfalse
布林值

為 true 時，標籤清單的方向將為垂直，否則將為水平。

manualfalse
布林值

為 true 時，使用者只能透過鍵盤先使用箭頭鍵導航到面板才能顯示該面板，然後按 Enter 或 Space。預設值下，當透過箭頭鍵導航到面板時，面板會自動顯示。請注意，此 prop 不會影響滑鼠行為。

插槽 Prop說明
selectedIndex

數字

目前選取的索引。

事件說明
變更

每次變更目前的標籤時呼叫的功能。

Prop預設值說明
作為div
字串 | 組件

標籤清單應該呈現為的元素或組件。

插槽 Prop說明
selectedIndex

數字

目前選取的索引。

Prop預設值說明
作為按鈕
字串 | 組件

標籤應該呈現為的元素或組件。

disabledfalse
布林值

標籤目前是否已停用。

插槽 Prop說明
selected

布林值

標籤目前是否已選取。

Prop預設值說明
作為div
字串 | 組件

標籤面板應該呈現為的元素或組件。

插槽 Prop說明
selectedIndex

數字

目前選取的索引。

Prop預設值說明
作為div
字串 | 組件

TabPanel 應該作為元素或作為元件呈現。

staticfalse
布林值

元素是否應略選選取的索引。

_註： static 及 unmount 無法同時使用。

unmounttrue
布林值

元素根據所選索引是取消掛載或隱藏。

_註： static 及 unmount 無法同時使用。

插槽 Prop說明
selected

布林值

TabPanel 目前是否已選取。

如果你對使用 Headless UI 和 Tailwind CSS 的預設元件範例有興趣，歡迎看看 Tailwind UI — 我們打造的一系列設計精美、製作精良的元件。

這是支持我們進行像這樣的開放原始碼專案的好方法，讓我們得以改進並維持它們的良好狀態。

探索更多預設範例→