文字區域

原生文字區域元素的一個簡易封裝器，處理繁瑣的可存取性事項，並提供更自訂的狀態選項（如：滑鼠移入和焦點）。

開始使用之前，請透過 npm 安裝 headless UI

npm install @headlessui/react

文字區域使用 Textarea 元件建構

import { Textarea } from '@headlessui/react'

function Example() {
  return <Textarea name="description"></Textarea>
}

你可以將通常 傳遞給原生的 textarea 元素的任何屬性傳遞給 Textarea

Headless UI 會記錄每個元件的許多狀態，例如文字區域是否取得焦點，快顯視窗是開啟還是關閉，或目前使用鍵盤選取了選單中的哪個項目。

但是因為元件是 headless 且開箱即用時完全沒有樣式，所以你無法在 UI 中看到此資訊，直到你自己提供你希望每個狀態套用樣式為止。

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

例如，Textarea 元件公開一個 data-focus 屬性，它會告訴你文字區域目前是否透過滑鼠或鍵盤取得焦點，以及一個 data-hover 屬性，它會告訴你文字區域目前是否由滑鼠游標暫停。

<!-- Rendered `Textarea` -->
<textarea name="description" data-focus data-hover></textarea>

使用 CSS 屬性選擇器 有條件套用基於這些資料屬性存在的樣式。如果您使用 Tailwind CSS，資料屬性修改 會讓這變得很簡單

import { Textarea } from '@headlessui/react'

function Example() {

  return <Textarea name="description" className="border data-[hover]:shadow data-[focus]:bg-blue-100"></Textarea>
}

請參閱 元件 API，以取得一份全部可用資料屬性的清單。

每個元件也會透過 渲染屬性 公開其目前狀態的資訊，你可以使用它們有條件套用不同的樣式或渲染不同的內容。

例如，Textarea 元件公開一個 focus 屬性，它會告訴你文字區域目前是否透過滑鼠或鍵盤取得焦點，以及一個 hover 屬性，它會告訴你文字區域目前是否由滑鼠游標暫停。

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

function Example() {
  return (
    <Textarea name="description" as={Fragment}>

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

請參閱 元件 API，以取得一份全部可用渲染屬性的清單。

以欄位元件包裝 標籤 及 文字輸入區域，以利用產生的 ID 自動關聯它們

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

function Example() {
  return (

    <Field>
      <Label>Description</Label>
      <Textarea name="description"></Textarea>

    </Field>
  )
}

在 欄位 中使用 描述 元件，以利用 aria-describedby 屬性自動將其與 文字輸入區域 關聯起來

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

function Example() {
  return (

    <Field>
      <Label>Description</Label>

      <Description>Add any extra information about your event here.</Description>
      <Textarea name="description"></Textarea>

    </Field>
  )
}

將 disabled 屬性加入 欄位 元件以停用 文字輸入區域 及其相關聯的 標籤 及 描述

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

function Example() {
  return (

    <Field disabled>
      <Label className="data-[disabled]:opacity-50">Name</Label>
      <Description className="data-[disabled]:opacity-50">Add any extra information about your event here.</Description>
      <Textarea name="description" className="data-[disabled]:bg-gray-100"></Textarea>
    </Field>
  )
}

您也可以在 欄位 外停用文字輸入區域，方法是直接將 disabled 屬性加入 文字輸入區域 本身。

包覆原生 textarea 元素的一層薄包裝器。

屬性預設說明
astextarea
字串 | 元件

元素或元件，textarea會做為呈現。

invalidfalse
布林

無論textarea是否無效。

disabledfalse
布林

無論textareais disabled.

autoFocusfalse
布林

無論textarea會在初次呈現時接受焦點。

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

布林

無論textarea是否無效。

data-disableddisabled

布林

無論textarea已停用。

data-focusfocus

布林

無論textarea已聚焦。

data-hoverhover

布林

無論textarea已游標懸停。

data-autofocusautofocus

布林

autoFocus 屬性是否設定為 true。

將 標籤、描述 和表單控制項分組在一起。

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

元素或元件，field會做為呈現。

disabledfalse
布林

欄位是否已停用。

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

布林

欄位是否已停用。

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

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

元素或元件，label會做為呈現。

passivefalse
布林

若為 true，則點選標籤時不會讓相關聯的表單控制項取得焦點。

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

布林

母項 欄位 是否已停用。

描述 元件描述表單控制項。

屬性預設說明
asp
字串 | 元件

元素或元件，description會做為呈現。

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

布林

母項 欄位 是否已停用。

如果您有興趣使用預先設計的 Tailwind CSS 範例文字區塊，請參閱 Tailwind UI — 我們所建構的一系列設計精美且由專業人員精心打造的元件。

這是支持我們從事諸如此類的開源專案的好方法，讓我們得以對其進行改良，並保持良好的維護狀態。

探索 範例 →

Various components from Tailwind UI