輸入

一個原生的輸入元素的簡單封裝器，處理無聊的可存取性問題，並提供較主觀的狀態，如滑鼠移入和焦點。

入門前，請透過 npm 安裝 Headless UI

npm install @headlessui/react

輸入框會使用 Input 組件建置

import { Input } from '@headlessui/react'

function Example() {
  return <Input name="full_name" type="text" />
}

您可將任何道具傳遞給 Input，就像您平常傳遞給原生 input 元素一樣。

Headless UI會追蹤每個組件的許多狀態資訊，例如輸入框是否獲得焦點、快顯視窗是否開啟或關閉，或是選單中哪個項目當前透過鍵盤獲得焦點。

但由於這些組件預設都是無頭且完全不具備樣式，您無法在使用者介面中看到這些資訊，直到您自行提供您要套用於每個狀態的樣式。

設定 Headless UI 組件不同狀態最簡單的方式，就是使用每個組件公開的 data-* 屬性。

例如，Input 組件公開 data-focus 屬性，用來告訴您輸入框當前是否獲得滑鼠或鍵盤的焦點，以及 data-hover 屬性，用來告訴您輸入框當前是否被滑鼠游標滑過。

<!-- Rendered `Input` -->
<input type="text" name="full_name" data-focus data-hover />

使用 CSS 屬性選擇器，根據這些資料屬性的存在條件性套用樣式。如果您正在使用 Tailwind CSS， 資料屬性修飾詞 可以讓這變得更容易

import { Input } from '@headlessui/react'

function Example() {

  return <Input type="text" name="full_name" className="border data-[hover]:shadow data-[focus]:bg-blue-100" />
}

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

每個組件也會透過渲染道具公開其當前狀態相關資訊，您可以使用此資訊，有條件地套用不同的樣式，或呈現不同的內容。

例如，Input 組件公開 focus 狀態，用來告訴您輸入框當前是否獲得滑鼠或鍵盤的焦點，以及 hover 狀態，用來告訴您輸入框當前是否被滑鼠游標滑過。

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

function Example() {
  return (
    <Input type="text" name="full_name" as={Fragment}>

      {({ focus, hover }) => <input className={clsx('border', focus && 'bg-blue-100', hover && 'shadow')} />}
    </Input>
  )
}

請參閱 組件 API 以取得所有可用渲染屬性的清單。

使用 Field 元件包覆 Label 和 Input，以使用產生的 ID 自動關聯它們

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

function Example() {
  return (

    <Field>
      <Label>Name</Label>
      <Input name="full_name" />

    </Field>
  )
}

在 Field 中使用 Description 元件，以使用 aria-describedby 屬性自動與 Input 關聯起來

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

function Example() {
  return (

    <Field>
      <Label>Name</Label>

      <Description>Use your real name so people will recognize you.</Description>
      <Input name="full_name" />

    </Field>
  )
}

將 disabled 道具新增至 Field 元件，以停用 Input 及其相關的 Label 和 Description

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

function Example() {
  return (

    <Field disabled>
      <Label className="data-[disabled]:opacity-50">Name</Label>
      <Description className="data-[disabled]:opacity-50">Use your real name so people will recognize you.</Description>
      <Input name="full_name" className="data-[disabled]:bg-gray-100" />
    </Field>
  )
}

你也可以將 disabled 道具直接新增至 Input，在 Field 外部停用輸入。

原生 input 元素的一個精簡封裝。

道具預設值說明
asinput
字串 | 元件

元素或元件為input應渲染為。

invalidfalse
布林值

是否input無效。

disabledfalse
布林值

是否input已停用.

autoFocusfalse
布林值

是否input第一次渲染時應獲得焦點。

資料屬性渲染道具說明
data-invalidinvalid

布林值

是否input無效。

data-disableddisabled

布林值

是否input已停用。

data-focusfocus

布林值

是否input已聚焦。

data-hoverhover

布林值

是否input已滑鼠移上。

data-autofocusautofocus

布林值

autoFocus 道具是否已設為 true。

將 標籤、說明和表單控制項進行分組。

道具預設值說明
asdiv
字串 | 元件

元素或元件為field應渲染為。

disabledfalse
布林值

欄位是否已停用。

資料屬性渲染道具說明
data-disableddisabled

布林值

欄位是否已停用。

標籤 元件標記表單控制項。

道具預設值說明
aslabel
字串 | 元件

元素或元件為label應渲染為。

passivefalse
布林值

如果為 true，則按一下標籤不會將焦點放在相關的表單控制項上。

資料屬性渲染道具說明
data-disableddisabled

布林值

父 欄位 是否已停用。

說明 元件說明表單控制項。

道具預設值說明
asp
字串 | 元件

元素或元件為說明應渲染為。

資料屬性渲染道具說明
data-disableddisabled

布林值

父 欄位 是否已停用。

如果您有興趣查看預先設計的 Tailwind CSS 表單輸入群組範例，請查看 Tailwind UI — 由我們建立的美觀設計和精心製作的元件集合。

這是一個很好的方式支持我們在像這樣的開源專案上的工作，並讓我們能夠改進它們並保持良好維護。

探索 範例 →

Various components from Tailwind UI