Field 表单字段 - Docs - Artefact

Field 表单字段

Forms

智能自动检测

简介

一个基础输入控件，旨在以清晰且无障碍的方式管理表单。它将输入标签、上下文辅助文本、动态错误验证状态以及基于自定义 JS 的规则检查聚合到一个内聚且对开发者友好的界面中。

Field 组件已作为交互式 field 区块完全集成到 Page Builder 中。这使内容创建者和设计者无需编写布局样板即可直接从 Sveltia CMS 起草字段、放置自定义 HTML 表单输入，并提供即时客户端验证逻辑。

用法

以下示例展示了内容编辑者如何绑定和配置表单字段结构。

1. 标准输入框

一个标准文本字段，带有配套标签、占位符提示，以及位于输入元素正下方的描述性辅助文本。

{
  "type": "field",
  "label": "Username",
  "placeholder": "e.g. jules_architect",
  "helperText": "Choose a unique public username.",
  "name": "username",
  "interactive": true
}

Username

Choose a unique public username.

2. 带客户端验证的动态输入

使用自定义验证逻辑。当用户输入少于 5 个字符或跳过 @ 符号时，错误消息会自动显示并动态播报。

{
  "type": "field",
  "label": "Email Address",
  "placeholder": "architect@domain.com",
  "defaultValue": "invalid-email",
  "validator": "(value) => value.includes('@') || 'Must be a valid email containing \'@\''",
  "name": "email",
  "interactive": true
}

Email Address

Must be a valid email containing '@'

3. 必填与禁用选项字段

展示标准 HTML 区块状态下的表单字段样式。这有助于内容作者直观地了解字段在必填（星号标记）或因权限锁定时呈现的外观。

{
  "type": "field",
  "label": "Secret Key",
  "defaultValue": "SUPER_SECURE_TOKEN",
  "readOnly": true,
  "required": true,
  "interactive": true
}

Secret Key

Legacy Code

属性

属性	CMS 字段类型	默认值	描述 / 支持选项
标签文本 (`label`)	`string`	-	位于输入元素正上方的视觉标题或描述。
名称 (`name`)	`string`	-	随表单提交一起发送的标准 HTML name 属性。
占位符 (`placeholder`)	`string`	-	当输入完全为空时在输入框内显示的浅色占位符文本。
辅助文本 (`helperText`)	`string`	-	打印在输入字段下方的上下文提示或说明文本。
错误文本 (`errorText`)	`string`	-	手动错误消息覆盖。触发无效样式和屏幕阅读器播报。
默认值 (`defaultValue`)	`string`	-	在页面加载时预填充输入。强制进入客户端交互孤岛模式。
必填 (`required`)	`boolean`	`false`	渲染红色星号标记，表示该输入不得留空。
禁用 (`disabled`)	`boolean`	`false`	阻止所有输入或光标交互，并使整个字段变暗。
只读 (`readOnly`)	`boolean`	`false`	保持值可选且可通过 Tab 聚焦，但阻止编辑文本。
无效状态 (`invalid`)	`boolean`	`false`	显式强制字段进入错误状态，以红色高亮边框。
验证器表达式 (`validator`)	`string`	-	评估字符串输入的高级 JavaScript 函数表达式。通过 `new Function()` 在客户端重建。示例： `(value) => value.includes('@')
强制交互 (`interactive`)	`boolean`	`true`	确保以交互孤岛的形式进行客户端水合，以支持实时用户验证。

开发者说明与无障碍

智能切换器水合： 默认情况下，如果该字段是标准静态展示，没有自定义验证触发器或动态绑定，它会保持轻量的静态 SSR 标记。提供 validator、defaultValue 或 "interactive": true 中的任意一项都会自动将该元素提升为完全水合的客户端孤岛。
WAI-ARIA 描述性连接： 外层包装元素动态管理 aria 连接。输入元素会自动注册 aria-describedby，指向辅助文本和错误文本插槽的精确生成 ID。
属性泄漏防护： FieldRoot 原语内置过滤器，可防止标准输入属性（如 placeholder、autocomplete 或 name）泄漏到外层包装 <div> 上，确保生成完全有效、干净的 HTML 输出。
组合上下文： Field 组件支持组合架构。在 Page Builder 中将子元素（如自定义 Textarea 或自定义选择元素）嵌套为子项时，它们会自动消费外层 Field 的共享上下文以解析适当的验证属性。

Editable 可编辑文本

FileUpload 文件上传