字段

为表单控件提供标签关联和校验能力的组件。

安装


pnpm dlx shadcn@latest add @lumi-ui/field

组件结构

<Field>
  <FieldLabel />
  <FieldControl />
  <FieldDescription />
  <FieldItem />
  <FieldError />
  <FieldValidity />
</Field>

警告

表单控件必须有可访问的名称，才能被辅助技术正确识别。<FieldLabel> 和 <FieldDescription> 会自动为其关联的控件分配可访问名称和描述。

状态与校验

必填

错误状态

校验状态

{
  "state": {
    "badInput": false,
    "customError": false,
    "patternMismatch": false,
    "rangeOverflow": false,
    "rangeUnderflow": false,
    "stepMismatch": false,
    "tooLong": false,
    "tooShort": false,
    "typeMismatch": false,
    "valid": null,
    "valueMissing": false
  },
  "error": "",
  "errors": [],
  "value": null,
  "initialValue": null,
  "validity": {
    "badInput": false,
    "customError": false,
    "patternMismatch": false,
    "rangeOverflow": false,
    "rangeUnderflow": false,
    "stepMismatch": false,
    "tooLong": false,
    "tooShort": false,
    "typeMismatch": false,
    "valid": null,
    "valueMissing": false
  }
}

与其他表单控件配合

Select

Autocomplete

Combobox

提示

你可以将 <Checkbox>、<Radio> 和 <Switch> 包裹在 <FieldLabel> 内，实现隐式标签关联。具体示例见下方。

Checkbox

Fieldset

Radio Group

表单集成

更多信息请参阅表单集成。

API 参考

组件	描述
`Field`	组合字段的所有部分。渲染一个 `<div>` 元素。
`FieldLabel`	与字段控件自动关联的可访问标签。渲染一个 `<label>` 元素。
`FieldControl`	需要被标签关联和校验的表单控件。渲染一个 `<input>` 元素。你也可以省略这一部分，改用任意 Base UI 输入组件。例如 `Input`、`Checkbox` 或 `Select` 等都能与 `Field` 开箱即用地协同工作。
`FieldDescription`	包含字段附加信息的段落。渲染一个 `<p>` 元素。
`FieldItem`	在复选框组或单选框组中，将单个选项与其标签和描述组合在一起。渲染一个 `<div>` 元素。
`FieldError`	当字段控件校验失败时显示的错误信息。渲染一个 `<div>` 元素。
`FieldValidity`	根据字段的校验状态显示自定义信息。`children` 必须是一个接收字段校验状态作为参数的函数。