跳到主要内容

字段配置详解

本文档详细介绍字段的通用配置属性和高级功能，包括基本属性、验证规则、各类型字段的专属配置以及高级功能。各字段类型的完整配置请参考对应的类型文档。

概述​

字段配置（详见 字段配置总览）分为三个层次：

  • 基本属性：名称、编码、类型、描述、默认值；
  • 验证属性：必填、长度限制、范围限制、正则校验、查重；
  • 展示属性：列表显示、表单显示、只读、隐藏、占位符与各类渲染方式。

其中「名称 / 编码 / 类型 / 描述」等基本属性在字段配置菜单中设置；「必填 / 只读 / 隐藏 / 占位符 / 默认值」等展示与交互属性在表单配置与视图列表配置中按场景设置。

基本属性配置​

通用基本属性​

配置项说明配置建议
名称字段显示名称使用业务术语，简洁明了
编码字段唯一标识使用英文小写字母和下划线命名
类型字段数据类型根据业务需求选择合适类型
描述字段说明详细描述字段用途
默认值新建记录时的默认值可设置动态默认值

验证属性配置​

通用验证规则​

属性说明适用类型
是否必填数据验证规则所有类型
最小长度文本最小长度限制文本类型
最大长度文本最大长度限制文本类型
最小值数字最小值数字、货币类型
最大值数字最大值数字、货币类型
精度小数位数（0-6位）数字、货币类型
正则验证自定义验证规则文本类型

展示属性配置​

通用展示属性​

属性说明
列表显示是否在列表视图列表中展示该字段
表单显示是否在表单中展示该字段
只读模式字段值不可编辑
隐藏字段完全隐藏，通常用于存储计算值
占位符输入提示，引导用户正确输入

各类型字段专属配置​

每种字段类型都有独立的属性与配置方法，详见以下类型文档：

下面汇总各类字段最常用的专属配置。

文本类型 (Text)​

文本类型支持多种渲染形式：

渲染类型选项​

渲染类型说明适用场景
单行文本标准文本输入框短文本输入
密码输入框内容隐藏显示密码等敏感信息
文本区多行文本输入长文本内容
MarkdownMarkdown 格式编辑器富格式文档
富文本富文本编辑器复杂排版需求

文本专属配置​

配置项说明范围
最小长度文本最小字符数0-100000
最大长度文本最大字符数0-100000

日期时间类型 (DateTime)​

支持三种渲染模式，并可自定义日期和时间的显示格式：

渲染模式​

渲染模式说明存储方式格式配置
日期时间包含日期和时间选择完整的日期时间值日期格式 + 时间格式
日期仅日期选择日期部分，时间归零仅日期格式
时间仅时间选择基于 2000-01-01 的日期时间值仅时间格式（日期格式不可见）
Time 类型的存储机制

为什么使用 2000-01-01 作为基准日期？

时间类型字段（如"上班时间"、"会议时长"）本质上不需要日期部分。为了保证：

  1. 搜索一致性：equal/ne 和 range 搜索都能正确工作
  2. 数据准确性：避免因随机日期导致的时间比较错误
  3. 跨时区兼容：统一基准日期确保时区转换的一致性

系统采用以下策略：

  • 前端：用户选择时间（如 09:30），前端自动拼接基准日期 2000-01-01 09:30:00
  • 后端：存储和查询时使用 UTC 格式的 ISO 字符串
  • 搜索：所有时间比较都在同一基准日期上进行，确保结果准确

示例：

  • 用户输入：09:30
  • 前端处理：2000-01-01 09:30:00
  • 后端存储：2000-01-01T01:30:00.000Z (UTC)
  • 搜索比较：所有时间值都转换为 2000-01-01 基准，然后进行比较

🆕 日期/时间格式自定义配置​

适用条件

当字段类型为日期时间时，可在字段编辑页面配置以下两项格式：

  • 日期格式（DateTimeFormat）：控制日期部分的显示方式
  • 时间格式（TimeFormat）：控制时间部分的显示方式

可见性规则：

渲染模式日期格式配置时间格式配置
日期时间✓ 可见✓ 可见
日期✓ 可见✗ 不可见
时间✗ 不可见✓ 可见
配置项说明​
配置项默认值说明可见条件
日期格式YYYY-MM-DD日期显示格式渲染模式为"日期时间"或"日期"
时间格式HH:mm时间显示格式渲染模式为"日期时间"或"时间"
常用格式示例​
配置项格式值显示效果示例适用场景
日期格式YYYY-MM-DD2026-06-14标准日期（默认）
YYYY/MM/DD2026/06/14斜杠分隔
DD-MM-YYYY14-06-2026日-月-年顺序
YYYY年MM月DD日2026年06月14日中文风格
MM/DD/YYYY06/14/2026美式日期
MMM D, YYYYJun 14, 2026英文缩写月份
MMMM D, YYYYJune 14, 2026英文完整月份
时间格式HH:mm12:56时:分（默认）
HH:mm:ss12:56:31时:分:秒
H:mm12:56非零填充小时
h:mm A12:56 PM12小时制+AM/PM
hh:mm:ss A12:56:31 PM12小时制完整+AM/PM
精度自动归零​

系统会根据时间格式的精度自动处理用户输入的时间值：

时间格式精度点击"此刻"/选择后效果示例结果
仅小时 (H / HH)分、秒、毫秒自动归零2026-06-14T12:00:00
到分钟 (HH:mm)秒、毫秒自动归零2026-06-14T12:56:00
到秒 (HH:mm:ss)毫秒自动归零2026-06-14T12:56:31

这确保了提交到服务端的时间值与用户配置的格式精度一致，避免因浏览器返回高精度时间导致的服务端处理问题。

完整组合示例​
场景渲染模式日期格式时间格式最终显示效果
标准日期时间日期时间YYYY-MM-DDHH:mm2026-06-14 12:56
含秒的日期时间日期时间YYYY-MM-DDHH:mm:ss2026-06-14 12:56:31
中文日期+12小时制日期时间YYYY年MM月DD日h:mm A2026年06月14日 12:56 PM
英文风格日期时间MMMM D, YYYYh:mm:ss AJune 14, 2026 12:56:31 PM
仅日期（Date 模式）日期YYYY-MM-DD不适用2026-06-14
上班时间（Time 模式）时间不适用HH:mm09:00
会议时长（含秒）时间不适用HH:mm:ss01:30:00

Time 类型使用场景​

适用场景：

  • 固定时间点：上班打卡时间、会议开始时间、营业时间等
  • 时间段记录：工作时长、会议时长、运动时长等
  • 时间表管理：课程表、班次表、时刻表等

不适用场景：

  • ❌ 需要记录具体日期的场景（如合同到期日）→ 使用 Date 模式
  • ❌ 需要完整时间戳的场景（如创建时间、修改时间）→ 使用 DateTime 模式

典型应用示例：

业务场景字段名称渲染模式时间格式示例值
考勤打卡上班时间时间HH:mm09:00
会议安排开始时间时间HH:mm14:30
课程表第一节课时间HH:mm08:00
运动记录运动时长时间HH:mm:ss01:30:00

支持的格式化占位符​

系统底层使用 day.js 进行日期格式化，以下占位符均可在配置中使用：

📖 完整文档参考：day.js 格式化占位符列表

日期占位符​
占位符输出示例说明
YY18两位数的年份
YYYY2018四位数的年份
M1-12月份，从1开始
MM01-12月份，两位数
MMMJan-Dec缩写的月份名称
MMMMJanuary-December完整的月份名称
D1-31月份里的一天
DD01-31月份里的一天，两位数
d0-6一周中的一天，星期天是0
ddSu-Sa最简写的星期几
dddSun-Sat简写的星期几
ddddSunday-Saturday星期几
时间占位符​
占位符输出示例说明
H0-23小时（24小时制）
HH00-23小时，两位数（24小时制）
h1-12小时（12小时制）
hh01-12小时，两位数（12小时制）
m0-59分钟
mm00-59分钟，两位数
s0-59秒
ss00-59秒，两位数
SSS000-999毫秒，三位数
Z+05:00UTC偏移量，±HH:mm
ZZ+0500UTC偏移量，±HHmm
AAM PM上午/下午标识（大写）
aam pm上午/下午标识（小写）
本地化格式​

需要启用 LocalizedFormat 插件后可用的本地化格式：

占位符示例输出说明
LT8:02 PM时:分 AM/PM
LTS8:02:18 PM时:分:秒 AM/PM
L08/16/2018月/日/年
LLAugust 16, 2018月 日, 年
LLLAugust 16, 2018 8:02 PM月 日, 年 时:分 AM/PM
LLLLThursday, August 16, 2018 8:02 PM星期几, 月 日, 年 时:分 AM/PM
l8/16/2018月/日/年（简化）
llAug 16, 2018月 日, 年（简化）
lllAug 16, 2018 8:02 PM月 日, 年 时:分 AM/PM（简化）
llllThu, Aug 16, 2018 8:02 PM星期几, 月 日, 年 时:分 AM/PM（简化）

是否类型 (Boolean)​

Boolean 类型字段支持自定义显示文案：

配置项说明默认值
是值显示文案true 时显示的文本"是"
否值显示文案false 时显示的文本"否"
null值显示文案null 时显示的文本-

适用场景：

  • 状态标记
  • 开关控制
  • 二元选择

数字类型 (Number)​

数字类型支持多种渲染形式：

渲染类型选项​

渲染类型说明适用场景
数字输入标准数字输入框常规数值输入
评分星级评分组件评分、满意度等
滑动条通过滑动条选择数值范围选择、音量调节等
进度条以进度条展示数值（只读）进度展示、完成率等

数字专属配置​

配置项说明适用渲染类型
精度小数位数（0-6）数字输入
最小值允许的最小数值数字输入、滑动条
最大值允许的最大数值数字输入、滑动条
滑动步长滑动条每次移动的步长滑动条模式

货币类型 (Currency)​

货币类型是高精度数字类型，适用于金额等需要精确计算的场景。

特点：

  • 更高的精度保证
  • 避免浮点数误差
  • 支持最小值/最大值/精度配置

适用场景：金额、价格、汇率等。

文件上传类型 (FileUpload)​

用于文件附件或图片上传，支持以下配置：

配置项说明选项范围
文件数量限制单次可上传的文件数1-10 个
单文件大小限制每个文件的大小上限1-50 MB
文件格式限制允许的文件格式采用 HTML input accept 标准

文件格式限制示例：

.pdf,.doc,.docx,.xls,.xlsx
image/*,video/*
.mp3,.mp4,.avi

人员选择类型 (UserSelect)​

员工选择控件，支持以下特性：

基础配置​

配置项说明
选择模式单选或多选
数据源选择数据来源（系统内置或自定义数据源）
Lookup 关联关联其他对象的数据

高级功能​

功能说明
标签展示在列表页以标签形式展示选中的人员
多种渲染模式下拉选择器、树形选择器、单选按钮、复选框
Lookup 功能自动关联并展示其他对象字段

组织选择类型 (OrganizationSelect)​

组织架构选择控件，支持以下特性：

基础配置​

配置项说明
选择模式单选或多选
数据源选择数据来源
渲染模式控制控件的具体展现形式 ⭐

渲染模式选项​

渲染模式说明适用场景
下拉选择器标准下拉选择选项较多时使用
树形选择器树形结构展示有层级关系的数据
单选按钮/复选框以单选按钮或复选框展示选项较少且需要直观对比时 ⭐
级联选择器级联联动选择多级关联数据

表单项布局方式配置（Layout）​

当渲染模式设置为单选按钮/复选框时，可以进一步配置表单项的布局方式：

适用条件

此配置项仅在以下条件同时满足时才会显示：

  1. 字段类型为：人员选择、组织选择 或 数据源
  2. 渲染模式为：单选按钮/复选框（RadioCheckbox）
  3. 场景：编辑表单配置页面
Layout 配置说明​
布局方式值效果示意适用场景
水平布局horizontal○ 选项A ○ 选项B ○ 选项C选项较少（2-4个），希望横向排列节省垂直空间
垂直布局vertical○ 选项A○ 选项B○ 选项C选项较多（5个以上），或选项文本较长

默认值: vertical（垂直布局）

配置位置: 字段管理 → 编辑字段 → Properties.Layout

代码中的枚举定义:

// MetaFieldTypes.ts
export const SelectRenderMode = {
    Select: 0,        // 下拉选择器
    TreeSelect: 1,   // 树形选择器
    RadioCheckbox: 2, // 单选按钮/复选框 ⭐
    Cascader: 3,     // 级联选择器
} as const;

前端组件应用:

// DataSourceSelectFormItemCmp.tsx
<ProFormRadio.Group
    layout={metaFormItem.Layout || 'vertical'}  // 动态读取布局配置
    // ... 其他属性
/>
选择建议​
场景推荐布局原因
性别选择（男/女）水平布局只有2个选项，横向排列更紧凑
优先级（高/中/低）水平布局3个选项，文本短，适合一行展示
星期选择（周一到周日）垂直布局7个选项，垂直排列更清晰
自定义状态（多个长文本选项）垂直布局文本较长，垂直排列避免换行

其他高级功能​

  • 标签展示：在列表页以标签形式展示选中的组织
  • Lookup 功能：自动关联并展示其他对象字段
  • 字段监听：监听其他字段变化，动态刷新数据源

数据源类型 (DataSource)​

用于从候选数据列表中选择数据，是最常用的关联类型。除了具备组织选择的全部特性外，还额外支持：

额外特性​

特性说明
级联选择器支持多级级联选择（第4种渲染模式）
连接符配置多选时选项间的连接符（仅下拉模式+普通展示生效）
显示模式配置列表页以标签或普通文本展示
标签颜色规则标签展示时的颜色方案（默认色/随机色）

渲染模式与 Layout 配置​

数据源类型的渲染模式和 Layout 配置与组织选择类型完全相同，请参考上方组织选择类型的相关章节。

高级功能配置​

开启 Lookup​

适用范围: 数据源类型字段

作用:

  • 建立字段与其他实体的关联关系
  • 在列表和详情页自动展示关联对象的字段
  • 减少额外的数据查询操作

配置方法: 在字段编辑页面开启 "LookupByDataId"，然后选择要关联的 MetaObject。

效果:

  • 列表页可直接显示关联对象的名称、状态等字段
  • 详情页可完整展示关联对象的详细信息

开启索引​

作用: 提升条件搜索性能

注意事项:

  • 并不是所有字段都需要开启索引
  • 开启索引会大大增加数据存储空间
  • 建议仅对常用作查询条件的字段开启索引

推荐开启索引的字段:

  • 经常作为筛选条件的字段
  • 用于排序的字段
  • 用于关联查询的外键字段

开启字段监听​

适用范围: 仅数据源类型字段

功能说明: 当表单中监听的字段值发生变更时，触发当前字段数据源刷新。

典型应用场景:

  • 选择省份后，自动刷新城市列表
  • 选择分类后，自动刷新子分类列表
  • 选择客户后，自动刷新联系人列表

配置方法:

  1. 开启 "OpenFieldMonitor"
  2. 选择要监听的字段（支持多选）
  3. 配置数据源查询参数的映射关系

校验规则​

采用正则表达式对字段输入值进行校验。

特点:

  • 内置多种常用的正则表达式
  • 支持自定义正则表达式匹配
  • 数据级别校验：任何来源的数据（导入、API写入）都将遵循字段校验规则约束

常用内置规则:

规则说明
手机号验证手机号格式
邮箱验证邮箱格式
身份证验证身份证号格式
URL验证网址格式

查重规则​

作用: 配置对象数据存储时的查重规则，防止重复数据录入。

查重模式:

模式说明
任意字段重复任一字段重复即判定为重复
全部字段重复所有字段都重复才判定为重复

适用场景:

  • 新增数据时查重
  • 编辑数据时查重
  • 导入数据时查重

字段默认值配置​

系统内置了部分特殊功能的默认值，会在执行时动态解析为相应的值：

默认值类型说明示例
当前时间自动填充当前时间2026-05-23 14:30:00
当前用户自动填充当前登录用户张三
当前组织自动填充当前用户所属组织技术部
固定值手动输入固定值待处理、草稿等
自定义脚本通过脚本动态计算根据其他字段计算

最佳实践​

字段设计原则​

  1. 命名规范
    • 名称：使用业务术语，如"客户名称"、"订单金额"
    • 编码：使用英文驼峰命名，如 customerName、orderAmount
  2. 类型选择
    • 金额相关 → 货币类型（精度高）
    • 数量统计 → 数字类型（范围广）
    • 关联实体 → 数据源类型（自动维护关系）
    • 状态标记 → 是否类型（简单直观）
  3. 性能考虑
    • 避免在列表视图列表中展示过多字段
    • 仅对常用查询字段开启索引
    • 复杂计算使用后端处理
  4. 用户体验
    • 设置合理的占位符提示
    • 必填字段要有明确标识
    • 使用默认值减少用户输入

常见问题​

Q: 什么时候应该使用 Lookup？ A: 当需要在列表或详情页展示关联对象的字段信息时，应该开启 Lookup。例如：订单列表中需要显示客户姓名。

Q: 如何选择合适的渲染模式？ A:

  • 选项少于5个 → 单选按钮/复选框 + 水平布局
  • 选项有层级关系 → 树形选择器或级联选择器
  • 选项很多（>10个）→ 下拉选择器（带搜索）
  • 需要多级关联 → 级联选择器

Q: 字段监听和 Lookup 可以同时使用吗？ A: 可以。字段监听用于表单内的级联联动，Lookup 用于跨对象的关联展示，两者互不冲突。

下一步​