简介

在原生 <fieldset> 下对相关的表单控件进行分组，带有无障碍的图例（legend）、辅助文本与错误文本。与 Field 不同，它没有自身的校验器——它是一个静态、服务端渲染的分组原语，因此永远不会作为客户端岛屿水合。它将其 disabled/invalid/required 状态作为上下文提供给嵌套的 Field，与 Ark UI 的 Fieldset 一致——参见 上下文传播。

用法

import { Fieldset, Field } from "../components/ui";

export default function MyPage() {
  return (
    <Fieldset
      legend="User Profile"
      helperText="Manage your info."
      required
      errorText="Something went wrong."
    >
      <Field>...</Field>
    </Fieldset>
  );
}

传入 errorText 就足以让 fieldset 进入无效状态——你无需同时传入 invalid。如果你想在保留文本的同时抑制错误样式，可显式传入 invalid={false}。

向嵌套 Field 的上下文传播

Fieldset 将其 disabled/invalid/required 状态作为上下文暴露出来。每个嵌套的 Field 都会将其读取为自身状态的回退值——因此组级别的 disabled 或 required 无需在每个字段上重复：

<Fieldset legend="Shipping address" disabled required>
  <Field label="Street" />   {/* renders disabled + required */}
  <Field label="Apt #" required={false} />  {/* opts back out of required */}
</Fieldset>

Field 自身的属性始终优先于继承值。就 invalid 而言，继承仅在 Field 自身没有校验（没有 validator、minLength 或显式的 invalid 属性）时适用——自行校验其值的 Field 永远不会被组静默覆盖。

这种传播只有一层：只有 Field（以及构建于其之上的任何组件，如 Textarea）会查询 Fieldset 的上下文。直接放置在 Fieldset 内部、没有包裹 Field 的裸 Switch 或 Checkbox——不会获取组的样式，尽管原生的 <fieldset disabled> 仍会阻止与其交互。

组合

children 始终是实际的表单控件组——Fieldset 会为你将其包裹在一个间距容器中。legend / helperText / errorText 接受任意 Child，而不仅仅是字符串，因此富内容（图标、徽章）应放在那里，而非放在 children 中：

<Fieldset legend={<>Profile <Badge>New</Badge></>}>
  <Field>...</Field>
  <Textarea>...</Textarea>
</Fieldset>

不要将 FieldsetLegend（或 FieldsetHelperText / FieldsetErrorText）放在 children 内部——Fieldset 会将 children 包裹在 <div> 中，而浏览器只有在 <legend> 作为 <fieldset> 的直接子元素（而非嵌套在包裹元素内）时，才会用它来计算 fieldset 的无障碍名称。这些导出的子组件（FieldsetLegend、FieldsetHelperText、FieldsetErrorText、FieldsetContent、FieldsetControl、FieldsetRequiredIndicator）是为在完全手工编写的标记中复用而存在的，并非在 Fieldset 内部组合的另一个方式。

CMS 页面构建器

该组件在 页面构建器（content/pages/*.json）中作为 fieldset 区块提供：

{
  "type": "fieldset",
  "legend": "User Profile",
  "helperText": "Manage your info.",
  "required": true,
  "children": [
    { "type": "field", "label": "Name" }
  ]
}

属性

属性	类型	说明
children	any	fieldset 内部要渲染的表单控件。
class	string	自定义 CSS 类名。
id	string	唯一标识符。省略时自动生成。
disabled	boolean	禁用 fieldset。原生的 <fieldset disabled> 会自动禁用每一个后代控件，而嵌套的 Field 也会将其作为上下文读取——参见 上下文传播。
invalid	boolean	fieldset 是否处于无效状态。只要设置了 errorText 就默认 true，因此通常无需显式传入。
required	boolean	将组标记为必填，并向图例追加一个必填指示器。
legend	Child	fieldset 的图例文本。始终渲染为 <fieldset> 的直接子元素——参见 组合。
helperText	Child	显示在图例下方的辅助文本。
errorText	Child	fieldset 无效时显示的错误文本。

CMS 绑定

legend、helperText、errorText、disabled、invalid 和 required 作为可编辑字段暴露在 public/admin/config.yml 中，外加一个用于嵌套其他区块的 children 列表——即上述相同的便捷属性。id/class 以及组合子组件（FieldsetContent、FieldsetControl、FieldsetRequiredIndicator 等）未被暴露：它们是供开发者手工编写页面的 JSX 级 API，而非 JSON 驱动的 CMS 区块所能表达的。