Fieldset 字段集
Layout
展示型
简介
一个结构化布局容器，将相关表单控件分组到原生 <fieldset> 下，并配有可访问的图例、辅助文本以及验证错误消息。它是复杂用户输入表单不可或缺的语义锚点，会自动将禁用、无效和必填状态向下传播到嵌套的字段控件。
Fieldset 组件已作为 fieldset 区块完全集成到 Page Builder 中，使内容作者和开发者能够直接在 CMS 中轻松构建多输入个人资料区块、地址表单或账单模块。
通过 CMS 页面构建器使用（JSON）
以下示例展示了内容编辑者如何在 JSON 页面模式（content/pages/*.json）中绑定和构建字段集分组。
1. 标准账户信息分组
一个带有必填嵌套名称字段的标准用户资料分组。包含活动的图例和辅助状态文本。
{
"type": "fieldset",
"legend": "Account Information",
"helperText": "Configure your primary account details.",
"required": true,
"children": [
{
"type": "field",
"label": "Full Name",
"placeholder": "Jane Doe",
"interactive": true
},
{
"type": "field",
"label": "Email Address",
"placeholder": "jane@example.com",
"interactive": true
}
]
}
2. 带错误消息的无效分组
展示当分组要求被违反时，Fieldset 如何显示验证错误消息。输入 errorText 会自动在所有子字段上触发无效状态。
{
"type": "fieldset",
"legend": "Billing Credentials",
"helperText": "Enter your card billing details.",
"errorText": "A valid postal code is required.",
"children": [
{
"type": "field",
"label": "Cardholder Name",
"placeholder": "Jane Doe",
"interactive": true
},
{
"type": "field",
"label": "Postal Code",
"placeholder": "90210",
"invalid": true,
"interactive": true
}
]
}
3. 禁用的账单选项区块
展示一个完全禁用的配送参数区块。停用父级 Fieldset 会自动锁定每个嵌套元素。
{
"type": "fieldset",
"legend": "Shipping Address",
"helperText": "Unavailable during local holidays.",
"disabled": true,
"children": [
{
"type": "field",
"label": "Street",
"placeholder": "123 Main St",
"interactive": true
},
{
"type": "field",
"label": "Apt #",
"placeholder": "4B",
"interactive": true
}
]
}
CMS 配置参考
这些字段直接映射到 public/admin/config.yml 下的 Sveltia CMS 区块属性，或 Page Builder 配置：
| 属性 | CMS 字段类型 | 默认值 | 描述 / 支持选项 |
|---|---|---|---|
图例文本 (legend) | string | - | 字段组的主要视觉与屏幕阅读器标题。 |
辅助消息 (helperText) | string | - | 位于图例正下方的解释性文本。 |
错误消息 (errorText) | string | - | 当分组被标记为无效时显示的视觉验证消息。 |
必填状态 (required) | boolean | false | 将分组标记为必填，并在图例上附加一个指示图标。 |
禁用状态 (disabled) | boolean | false | 禁用整个区块，锁定所有嵌套输入。 |
无效状态 (invalid) | boolean | false | 强制分组显示活动错误边框和警报。 |
子区块 (children) | list | - | 分组在 fieldset 轨道内的嵌套子输入（例如 Field、Textarea）。 |
开发者说明与无障碍
- 免水合（仅静态）： Fieldset 是一个被指定为仅静态组件（
Tier 3）的语义布局组件。它完全以标准服务端 HTML 渲染，并免除客户端水合脚本。 - 上下文传播： 它利用上下文提供者将
disabled、invalid和required状态向下传播。直接的子组件区块（如Field和Textarea）会自动监听此上下文并继承分组属性，从而省去重复的键声明。 - WAI-ARIA 合规： Fieldset 严格编译为包含直接
<legend>元素的语义 HTML<fieldset>容器，满足可访问的浏览器标题要求。