表单字段属性

表单设计器中每个字段项的属性配置：通用属性、按字段类型的渲染差异与字段脚本。

概述

表单设计器左侧「表单字段」分类下会列出当前实体对象的全部字段（含 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` 控制

渲染方式的配置入口

上述渲染类型、格式、数据源等属性均在字段配置中设置，表单设计器只负责按这些属性渲染，不提供修改入口。

下一步

表单设计器 - 拖拽布局与容器组件
表单全局属性 - 布局方向、渲染宽度、接口绑定、提交后行为
表单脚本 API - 字段脚本 API 与联动示例
字段配置详解 - 字段类型、渲染方式与验证规则

属性明细

以下内容面向技术实现与 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}"
  }
}

概述​

配置项​

通用属性​

名称与编码​

显隐与读写​

默认值与占位符​

字段脚本​

各类型字段的渲染差异​

下一步​

属性明细​

字段项 meta 属性表​

字段类型取值​

字段脚本状态​

存储示例​

概述

配置项