表单字段属性
表单设计器中每个字段项的属性配置：通用属性、按字段类型的渲染差异与字段脚本。
概述
表单设计器左侧「表单字段」分类下会列出当前实体对象的全部字段（含 Lookup 关联字段），每个字段拖入布局后成为一个字段项（FormItem）。选中字段项即可在右侧属性面板配置其属性。
字段项的属性分为两类：
- 通用属性：在表单设计器中可直接配置，用于控制该字段在本表单中的标题、显隐、必填、只读、默认值、占位符与脚本。
- 分类属性：由字段自身类型决定其渲染形态（如文本框、日期选择、评分、上传等），在字段配置中定义，表单设计器只读取并渲染，不在此处修改。
表单配置与字段配置的分工
字段配置决定「字段是什么」（类型、数据源、验证、渲染方式），表单配置决定「字段在本表单界面中如何呈现」（标题、显隐、默认值、排布）。修改本表单的字段属性不会影响字段定义本身。
配置项
字段项的通用属性如下：
| 配置项 | 说明 |
|---|---|
| 字段编码 | 字段在对象中的唯一编码，只读，来自字段定义 |
| 名称 | 字段在本表单中展示的标签，必填，默认取字段名称 |
| 是否隐藏 | 是否在表单中隐藏该字段，默认否 |
| 是否必填 | 是否强制填写，默认否 |
| 是否只读 | 是否只读展示，默认否 |
| 默认值 | 字段的默认值，支持系统环境变量 |
| 占位符 | 输入框的提示文案（Placeholder） |
| 字段脚本 | 用于控制字段联动行为的 JavaScript 脚本 |
字段项的状态标识
在画布中，被隐藏的字段会显示「隐」标签，配置了字段脚本的字段会显示脚本图标；Lookup 类型字段带有提示「Lookup 类型字段只在详情页展示」。
通用属性
名称与编码
- 字段编码（Code）：只读，与对象字段一致，是表单提交时的数据键。
- 名称（Name）：必填，即字段标签；若不填写会校验失败。
显隐与读写
- 是否隐藏（IsHide）：为
true时字段在表单中不渲染。在详情模式下还会与「详情模式下隐藏空字段」联动。 - 是否必填（IsMustInput）：为
true时由前端生成必填校验。 - 是否只读（IsReadOnly）：为
true时字段禁用编辑；详情模式下所有字段均按只读处理。
默认值与占位符
- 默认值（DefaultValue）：字段的初始值，支持系统环境变量占位（由
replaceSystemEnvironment解析）。 - 占位符（Placeholder）：输入提示，会被字段脚本的
setPlaceholder覆盖。
字段脚本
字段脚本用于实现字段联动（值联动、显隐联动、验证联动），支持 onChange、onLoad、onFocus、onBlur 等事件函数，脚本在沙箱中执行。完整 API 请参阅 表单脚本 API。
各类型字段的渲染差异
字段项最终的渲染形态由其字段类型决定，以下为表单设计器/运行时的渲染对应关系：
| 字段类型 | 取值 | 渲染形态 |
|---|---|---|
| 文本 Text | 2 | 单行文本 / 密码 / 多行文本 / Markdown / 富文本（由 TextFieldRenderType 决定）；若字段配置了数据源则渲染为选择类控件 |
| 日期时间 DateTime | 3 | 日期选择 / 时间选择 / 日期时间选择（由 DateFieldRenderType 决定），受 DateFormat、TimeFormat 控制 |
| 是否 Boolean | 5 | 单选按钮组（是 / 否），文案取自 BooleanTrueDisplayText、BooleanFalseDisplayText |
| 数字 Number | 9 | 数字输入 / 评分 / 滑动条 / 进度条（由 NumericFieldRenderType 决定，进度条仅详情模式展示） |
| 货币 Currency | 10 | 金额输入 |
| 文件上传 FileUpload | 14 | 文件上传，受 FileCountLimit、FileSizeLimit、FileFormatLimit 限制 |
| 人员选择 UserSelect | 30 | 人员下拉选择 |
| 组织选择 OrganizationSelect | 32 | 组织下拉选择 |
| 数据源 DataSource | 35 | 数据源下拉选择，受 DataSourceSelect 与 SelectRenderMode 控制 |
渲染方式的配置入口
上述渲染类型、格式、数据源等属性均在字段配置中设置，表单设计器只负责按这些属性渲染，不提供修改入口。
下一步
属性明细
以下内容面向技术实现与 AI 检索，逐个说明字段项属性在布局 meta 中的存储。
字段项 meta 属性表
| 属性名 | 类型 | 含义 | 取值/存储值 |
|---|---|---|---|
MetaFieldId | string | 字段标识 | 普通字段为字段 FullId；Lookup 字段包含 ~ |
Code | string | 字段编码 | 只读，来自字段定义 |
Name | string | 字段标签 | 必填 |
IsHide | string(bool) | 是否隐藏 | "true" / "false" |
IsMustInput | string(bool) | 是否必填 | "true" / "false" |
IsReadOnly | string(bool) | 是否只读 | "true" / "false" |
DefaultValue | string | 默认值 | 支持系统环境变量 |
Placeholder | string | 占位符 | 可被脚本覆盖 |
FieldScript | string | 字段脚本 | JavaScript 源码，为空即未启用脚本 |
MetaFieldType | string(number) | 字段类型 | 见「字段类型取值」 |
DataSourceSelect | string | 数据源选择 | 字段配置的数据源标识 |
FileCountLimit | string(number) | 文件数量限制 | 文件字段 |
FileSizeLimit | string(number) | 文件大小限制 | 文件字段 |
FileFormatLimit | string | 文件格式限制 | 文件字段 |
SelectMode | string(number) | 选择模式 | 选择类字段 |
SelectRenderMode | string(number) | 选择渲染模式 | 选择类字段 |
Precision | string(number) | 精度 | 数字/货币字段 |
字段类型取值
export const FieldType = {
Text: 2,
DateTime: 3,
Boolean: 5,
Number: 9,
Currency: 10,
FileUpload: 14,
UserSelect: 30,
OrganizationSelect: 32,
DataSource: 35,
} as const;
字段脚本状态
字段脚本执行后会得到字段状态（FieldScriptState），用于覆盖静态配置：
| 属性名 | 类型 | 含义 |
|---|---|---|
visible | bool | 覆盖 IsHide |
required | bool | 覆盖 IsMustInput |
readOnly | bool | 覆盖 IsReadOnly |
placeholder | string | 覆盖 Placeholder |
rules | array | 动态验证规则 |
存储示例
一个被设置为「只读 + 有默认值 + 带脚本」的文本字段：
{
"id": "field-item-1",
"uid": "x",
"widgetType": "FormItem",
"widgetTypeName": "表单字段",
"children": [],
"meta": {
"MetaFieldId": "a1b2c3d4-...",
"Code": "book_name",
"Name": "图书名称",
"MetaFieldType": "2",
"IsHide": "false",
"IsMustInput": "true",
"IsReadOnly": "true",
"DefaultValue": "",
"Placeholder": "请输入图书名称",
"DataSourceSelect": "",
"FileCountLimit": "0",
"FileSizeLimit": "0",
"FileFormatLimit": "",
"SelectMode": "0",
"SelectRenderMode": "0",
"Precision": "0",
"FieldScript": "function onChange(api, value) {\n api.setRequired('book_isbn', true);\n}"
}
}