Select

一個簡單的原生 select 元素包裝器，可以處理繁瑣的可訪問性問題，並提供更多元化的狀態，例如滑鼠移入和焦點。

為開始使用，透過 npm 安裝 Headless UI

npm install @headlessui/react

選取控制元件使用 Select 元件所組建

import { Select } from '@headlessui/react'

function Example() {
  return (
    <Select name="status" aria-label="Project status">
      <option value="active">Active</option>
      <option value="paused">Paused</option>
      <option value="delayed">Delayed</option>
      <option value="canceled">Canceled</option>
    </Select>
  )
}

您可以傳遞任何道具給 Select，您通常會傳遞給原生 select 元素

Headless UI 追蹤每個元件的許多狀態，例如選取是否取得焦點、快顯視窗是否開啟或關閉，或選單中哪個項目目前由鍵盤取得焦點。

但由於這些元件是 headless 且完全無預設樣式，您無法在 UI 中看到這些資訊，直到您自行提供您要套用的各個狀態樣式。

設定 Headless UI 元件不同狀態樣式的最簡單方法是使用每個元件揭露的 data-* 屬性。

例如，Select 元件會揭露一個 `data-focus` 屬性，它會告訴您選取目前是否由鍵盤取得焦點，以及一個 data-hover 屬性，它會告訴您選取目前是否由滑鼠游標懸停。

<!-- Rendered `Select` -->
<select name="status" data-focus data-hover>
  <option value="active">Active</option>
  <option value="paused">Paused</option>
  <option value="delayed">Delayed</option>
  <option value="canceled">Canceled</option>
</select>

使用 CSS 屬性選取器，以有條件地根據這些資料屬性的存在套用樣式。如果您正在使用 Tailwind CSS，資料屬性修改器 會讓這變得很容易

import { Select } from '@headlessui/react'

function Example() {
  return (

    <Select name="status" className="border data-[hover]:shadow data-[focus]:bg-blue-100" aria-label="Project status">
      <option value="active">Active</option>
      <option value="paused">Paused</option>
      <option value="delayed">Delayed</option>
      <option value="canceled">Canceled</option>
    </Select>
  )
}

請參閱 元件 API 以取得所有可用資料屬性清單。

每個元件會透過 render props 揭露其目前狀態的資訊，您可以依此有條件套用不同樣式或呈現不同內容。

例如，Select 元件會揭露一個 focus 狀態，它會告訴您選取目前是否由鍵盤取得焦點，以及一個 hover 狀態，它會告訴您選取目前是否由滑鼠游標懸停。

import { Select } from '@headlessui/react'
import clsx from 'clsx'
import { Fragment } from 'react'

function Example() {
  return (
    <Select name="status" as={Fragment}>

      {({ focus, hover }) => (
        <select className={clsx('border', focus && 'bg-blue-100', hover && 'shadow')} aria-label="Project status">
          <option value="active">Active</option>
          <option value="paused">Paused</option>
          <option value="delayed">Delayed</option>
          <option value="canceled">Canceled</option>
        </select>

      )}
    </Select>
  )
}

請參閱 元件 API 以取得所有可用 render prop 清單。

使用 Field 元件包裹 Label 和 Select 自動使用產生的 ID 將兩者關聯

import { Field, Label, Select } from '@headlessui/react'

function Example() {
  return (

    <Field>
      <Label>Project status</Label>
      <Select name="status">
        <option value="active">Active</option>
        <option value="paused">Paused</option>
        <option value="delayed">Delayed</option>
        <option value="canceled">Canceled</option>
      </Select>

    </Field>
  )
}

在 Field 內使用 Description 元件，使用 aria-describedby 屬性將其自動與 Select 關聯

import { Description, Field, Label, Select } from '@headlessui/react'

function Example() {
  return (

    <Field>
      <Label>Project status</Label>

      <Description>This will be visible to clients on the project.</Description>
      <Select name="status">
        <option value="active">Active</option>
        <option value="paused">Paused</option>
        <option value="delayed">Delayed</option>
        <option value="canceled">Canceled</option>
      </Select>

    </Field>
  )
}

將 disabled 屬性新增到 Field 元件即可禁用 Select 其相關聯的 Label 和 Description

import { Description, Field, Label, Select } from '@headlessui/react'

function Example() {
  return (

    <Field disabled>
      <Label className="data-[disabled]:opacity-50">Project status</Label>
      <Description className="data-[disabled]:opacity-50">This will be visible to clients on the project.</Description>
      <Select name="status" className="data-[disabled]:bg-gray-100">
        <option value="active">Active</option>
        <option value="paused">Paused</option>
        <option value="delayed">Delayed</option>
        <option value="canceled">Canceled</option>
      </Select>
    </Field>
  )
}

你也可以在 Field 外部禁用選取，直接將禁用屬性新增到 Select 本身。

原生 select 元素的少量包裝。

屬性預設值說明
asselect
字串 | 元件

元素或元件select應該呈現為。

invalidfalse
布林值

是否select無效。

disabledfalse
布林值

是否selectis disabled.

autoFocusfalse
布林值

是否select首次呈現時應該接收焦點。

資料屬性呈現屬性說明
data-invalidinvalid

布林值

是否select無效。

data-disableddisabled

布林值

是否select無效。

data-focusfocus

布林值

是否select有焦點。

data-hoverhover

布林值

是否select滑鼠暫停。

data-activeactive

布林值

是否select處於活動或被按下的狀態。

data-autofocusautofocus

布林值

autoFocus 屬性是否已設定為 true。

將 Label、Description 和表單控制項分組在一起。

屬性預設值說明
asdiv
字串 | 元件

元素或元件field應該呈現為。

disabledfalse
布林值

欄位是否已禁用。

資料屬性呈現屬性說明
data-disableddisabled

布林值

欄位是否已禁用。

Label 元件標記一個表單控制項。

屬性預設值說明
aslabel
字串 | 元件

元素或元件label應該呈現為。

passivefalse
布林值

當為 true 時，按一下標籤不會將焦點設定在相關聯的表單控制項上。

資料屬性呈現屬性說明
data-disableddisabled

布林值

父 Field 是否已禁用。

Description 元件用來描述表單控制項。

屬性預設值說明
as段落
字串 | 元件

元素或元件說明應該呈現為。

資料屬性呈現屬性說明
data-disableddisabled

布林值

父 Field 是否已禁用。

如果您有興趣取得預先設計的 Tailwind CSS 選單範例，請查看 Tailwind UI — 是我們建置的一系列美麗設計及專家製作的元件。

這是支持我們開發這類開源專案的好方法，它讓我們可以改善它們並持續維護。

探索更多 的範例→

Various components from Tailwind UI