选择

一个围绕原生 select 元素的轻量级包装器，它处理繁琐的辅助功能问题，并为悬停和焦点等状态提供更具意见性的状态。

要开始使用，请通过 npm 安装无头 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 元素一样。

无头 UI 会跟踪每个组件的很多状态，例如选择是否被聚焦，弹出窗口是否打开或关闭，或者菜单中哪个项目当前通过键盘被聚焦。

但是由于这些组件是无头的，并且开箱即用完全没有样式，所以您无法在 UI 中看到此信息，直到您自己提供每个状态所需的样式。

使用每个组件公开的 data-* 属性来设置无头 UI 组件的不同状态的样式是最简单的方法。

例如，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 以获取所有可用数据属性的列表。

每个组件还通过 渲染道具 公开有关其当前状态的信息，您可以使用这些信息来有条件地应用不同的样式或渲染不同的内容。

例如，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 以获取所有可用渲染道具的列表。

使用 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>
  )
}

您也可以通过将 disabled 属性直接添加到 Select 本身来在 Field 之外禁用选择。

围绕原生 select 元素的薄包装器。

属性默认值描述
asselect
字符串 | 组件

元素或组件select应渲染为。

invalidfalse
布尔值

是否select无效。

disabledfalse
布尔值

是否select被禁用.

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
布尔值

当为真时，单击标签不会聚焦关联的表单控件。

数据属性渲染道具描述
data-disableddisabled

布尔值

父 Field 是否被禁用。

Description 组件描述表单控件。

属性默认值描述
asp
字符串 | 组件

元素或组件description应渲染为。

数据属性渲染道具描述
data-disableddisabled

布尔值

父 Field 是否被禁用。

如果您有兴趣查看预先设计的 Tailwind CSS 选择菜单示例，请查看 Tailwind UI - 由我们构建的精美设计和专业制作的组件集合。

这是支持我们在这个开源项目上的工作的好方法，使我们能够改进它们并保持良好的维护。

探索 示例 →

Various components from Tailwind UI