表单
Field
一行带标签的表单:标签、控件,和下面那一条消息。
示例
states
We never share it.
Name is required.
Markdown is fine.
说明
一行带标签的表单:标签、控件,以及底下那唯一一条消息。
看得见的消息只是可访问校验的一半——它还必须传到控件上。这里会把 aria-describedby、aria-required 和 aria-invalid 接到那个唯一的子控件上,让“必填”和“错误”是被播报出来的,而不只是画出来的(WCAG 1.3.1 / 3.3.1 / 4.1.2)。
早先的版本从 htmlFor 推导消息的 id,于是没传 htmlFor 的调用方得到的是一条渲染了但永远不会被播报的提示——这个故障在浏览器里完全看不出来,对读屏用户却是彻底的。现在没提供 id 时会自动生成。
hint 和 error 是同一个插槽,不是两条叠着的消息:当一个字段填错了,该读的是它错在哪。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| children必填 | ReactNode | — | |
| error | ReactNode | 校验消息;存在时优先于 `hint`。 | |
| hint | ReactNode | 没有 `error` 时,显示在控件下方的辅助文字。 | |
| htmlFor | string | 控件的 `id`。可选:不传时字段会生成一个,并放到子控件自己身上,这样标签仍然指向了某个东西。当这个 id 必须在多次渲染之间保持稳定时——比如某个表单库要按名字引用它——就显式传进来。 | |
| label | ReactNode | 可见的标签文字;`required` 时会渲染一个 `--danger` 色的星号。 | |
| required | boolean | — |
同时接受 HTMLAttributes<HTMLDivElement> 里的全部属性,它们会直接透传给底层元素,不再逐条列出。
无障碍
- 没传 id 时会自己生成一个,所以标签永远指向某个东西。
- 把 aria-describedby、aria-required、aria-invalid 接到控件上,所以校验是被念出来的,不只是被画出来的。
- hint 和 error 是同一个位置,不是两条叠着:字段错了的时候,该读的是它哪里错了。