Field

Một field của form: một label, một control, description tùy chọn và một lỗi. Field giữ các id, nên label đặt tên cho control và control được mô tả bởi description cùng lỗi, và Field truyền required, disabled và invalid cho cả hai cùng lúc.

npm: 3 trực tiếp, 5 tổng
registry: 3 trực tiếp, 4 tổng

Xem trước

import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

<Field className="w-full max-w-sm">
  <FieldLabel>Email</FieldLabel>
  <FieldControl>
    <Input type="email" placeholder="you@example.com" />
  </FieldControl>
  <FieldDescription>Chúng tôi gửi biên lai đến địa chỉ này.</FieldDescription>
</Field>

Cách dùng

Khi nào dùng

Mọi control của form có label, kèm description hoặc thông báo lỗi đi cùng.
Đặt required, disabled hoặc invalid một lần, cho label và control cùng nhau.

Khi nào không dùng

Hai control trở lên dưới một tên, chẳng hạn một ngày tách thành ngày, tháng và năm. Cho mỗi cái một Field riêng.
Control không có label nhìn thấy, chẳng hạn ô tìm trong thanh công cụ. Đặt tên bằng aria-label.

Biến thể

orientation

vertical: label ở trên control, cho hầu hết form. horizontal: label cạnh control, ở một phần ba đầu, cho trang cài đặt có giá trị ngắn.

Email
Chúng tôi gửi biên lai đến địa chỉ này.
verticalmặc định
Email
Chúng tôi gửi biên lai đến địa chỉ này.
horizontal

import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

<Field className="w-full max-w-sm">
  <FieldLabel>Email</FieldLabel>
  <FieldControl>
    <Input type="email" placeholder="you@example.com" />
  </FieldControl>
  <FieldDescription>Chúng tôi gửi biên lai đến địa chỉ này.</FieldDescription>
</Field>
<Field orientation="horizontal" className="w-full max-w-sm">
  <FieldLabel>Email</FieldLabel>
  <FieldControl>
    <Input type="email" placeholder="you@example.com" />
  </FieldControl>
  <FieldDescription>Chúng tôi gửi biên lai đến địa chỉ này.</FieldDescription>
</Field>

Ví dụ

Mặc định

Chúng tôi gửi biên lai đến địa chỉ này.

import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

<Field className="w-full max-w-sm">
  <FieldLabel>Email</FieldLabel>
  <FieldControl>
    <Input type="email" placeholder="you@example.com" />
  </FieldControl>
  <FieldDescription>Chúng tôi gửi biên lai đến địa chỉ này.</FieldDescription>
</Field>

Bắt buộc

Tên không gian làm việc

import { Field, FieldControl, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

<Field className="w-full max-w-sm" required>
  <FieldLabel requiredText="Bắt buộc">Tên không gian làm việc</FieldLabel>
  <FieldControl>
    <Input />
  </FieldControl>
</Field>

Có lỗi

Chữ lỗi đánh dấu input là invalid và được đọc sau tên của nó.

Nhập email như you@example.com.

import { Field, FieldControl, FieldError, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

<Field className="w-full max-w-sm">
  <FieldLabel>Email</FieldLabel>
  <FieldControl>
    <Input type="email" defaultValue="not-an-email" />
  </FieldControl>
  <FieldError>Nhập email như you@example.com.</FieldError>
</Field>

Với Select

FieldControl bọc trigger, nên label mở danh sách. name và required đặt trên Select.

Vai trò

Quản trị viên có thể mời người và thay đổi thanh toán.

import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"

<Field className="w-full max-w-sm">
  <FieldLabel>Vai trò</FieldLabel>
  <Select>
    <FieldControl>
      <SelectTrigger>
        <SelectValue placeholder="Chọn vai trò" />
      </SelectTrigger>
    </FieldControl>
    <SelectContent>
      <SelectItem value="viewer">Người xem</SelectItem>
      <SelectItem value="editor">Biên tập</SelectItem>
      <SelectItem value="admin">Quản trị</SelectItem>
    </SelectContent>
  </Select>
  <FieldDescription>Quản trị viên có thể mời người và thay đổi thanh toán.</FieldDescription>
</Field>

Vô hiệu

Khu vực

Được đặt khi không gian làm việc được tạo.

import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"

<Field className="w-full max-w-sm" disabled>
  <FieldLabel>Khu vực</FieldLabel>
  <FieldControl>
    <Input defaultValue="Châu Âu" />
  </FieldControl>
  <FieldDescription>Được đặt khi không gian làm việc được tạo.</FieldDescription>
</Field>

Nên và không nên

Nên

Dùng Field cho mọi control của form có label, để các id luôn được nối.
Viết lỗi thành việc cần làm: Nhập một email như you@example.com.
Xếp các field thành một cột với gap-lg giữa chúng.
Đặt required, disabled và invalid trên Field, không đặt trên label và control từng cái một.

Không nên

Đừng đặt nhiều hơn một control trong một Field; cho mỗi control một Field riêng.
Đừng đặt id trên control bên trong FieldControl; đặt nó trên Field, nếu không label ngừng trỏ tới control.
Đừng hiện lỗi trước khi người dùng rời field hoặc gửi form.
Đừng dùng description cho một lỗi; dùng FieldError.

Props

Tên	Kiểu	Giá trị	Mặc định	Mô tả
orientation	enum	vertical \| horizontal	vertical	vertical: label ở trên control, cho hầu hết form. horizontal: label cạnh control, ở một phần ba đầu, cho trang cài đặt có giá trị ngắn.
id	string	-	-	Id của control, cho một label hoặc link ở chỗ khác trên trang. Được tạo khi bỏ trống.
name	string	-	-	Tên trong form, truyền vào control. Với Select, đặt name trên Select.
required	boolean	-	false	Đặt ghi chú Required lên label và đặt required trên control.
disabled	boolean	-	false	Làm mờ label và vô hiệu control.
invalid	boolean	-	false	Đặt aria-invalid trên control. FieldError có chữ thì tự làm việc đó; chỉ đặt invalid khi lỗi hiện ở nơi khác.

Slot

Tên	Bắt buộc	Mô tả
label	có	FieldLabel với tên của field.
control	có	FieldControl bọc một control: Input, hoặc SelectTrigger của một Select.
description	không	FieldDescription tùy chọn: cần nhập gì, hoặc vì sao cần nó. Một câu ngắn.
error	không	FieldError tùy chọn: chỗ nào sai và cách sửa. Chỉ render khi value đang invalid.

Cấu tạo

Phần	Mô tả
root	Field: một cột với label ở trên control, hoặc một lưới với label ở một phần ba đầu, cạnh control.
label	FieldLabel: một Label trỏ tới control và theo required cùng disabled của field.
control	FieldControl: bọc đúng một control (Input, SelectTrigger) và đưa cho nó id, name, trạng thái và các mô tả. Không thêm phần tử.
description	FieldDescription: chữ phụ 14px dưới control. Chỉ render khi có chữ.
error	FieldError: chữ danger 14px dưới control. Chỉ render khi có chữ, và khi đó đánh dấu control là invalid.

Role: generic

FieldLabel trỏ tới control (htmlFor), nên nhấn vào label thì focus vào control và trình đọc màn hình đọc label như tên của nó.
FieldControl đưa cho control id của field, và aria-describedby với description và lỗi, nên trình đọc màn hình đọc chúng sau tên.
FieldError có chữ thì đặt aria-invalid trên control. Lỗi là chữ, nên không chỉ dựa vào viền đỏ.
FieldError không phải live region. Sau khi gửi, chuyển focus tới field invalid đầu tiên; lỗi của nó được đọc cùng field.
required đặt ghi chú Required lên label và required lên control, và đó là thứ trình đọc màn hình thông báo.

Cài đặt

npx werewolf-ui add field

Chạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.