NocoBase 时间字段实战指南创建、存储、校验与页面配置全解析【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase本文以 NocoBase 数据建模中的时间Time字段为主题完整覆盖其创建配置、字段特性、编辑映射、删除影响与页面区块用法并结合nocobase/database包中的TimeField与TimeInterface源码解释时间值在数据层的存储类型SequelizeTIME与写入前的格式归一化逻辑HH:mm:ss帮助读者既会配置也懂其底层实现。什么是时间字段定位与适用场景在 NocoBase 中时间Time字段用于保存一天中的时间而不是完整的日期时间。它适合营业时间、提醒时间、排班时间段等不绑定具体日期的业务数据。典型适用场景包括营业开始时间、营业结束时间每日提醒时间班次开始时间、班次结束时间固定时间点配置。如果业务需要同时保存日期和时间应选择日期时间字段而不是时间字段。两者在数据层的区别是明确的时间字段只记录“几点几分几秒”而日期时间字段记录完整的年月日加时间含时区语义。创建时间字段入口与完整配置项在数据表的「Configure fields」页面中点击「Add field」选择「时间」即可创建时间字段。创建表单中的配置项与含义如下配置说明Field interface字段的界面类型。时间对应time决定页面中如何录入和展示。Field display name字段在界面中显示的名称比如「开始时间」「提醒时间」「营业时间」。建议使用业务人员能直接理解的名称。Field name字段标识名称用于 API、关系字段、权限、工作流等内部引用。创建后通常不再修改只支持字母、数字和下划线并且必须以字母开头。Field type字段在数据层的类型。时间字段默认是time。Default value默认值。新增记录时如果用户没有填写可以自动带出默认值。Validation rules校验规则。可以配置必填、时间范围等。Description字段说明。适合写字段含义、填写要求、数据来源或维护人。注意字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名避免后续修改带来配置调整成本。Field name 只允许字母、数字和下划线且以字母开头的约束本质上是保证字段标识可以被安全地用于 JSON API 参数键、关系字段引用和工作流变量路径这也是为什么 NocoBase 建议创建前想好命名。底层实现一TimeField 与数据层类型从源码结构看时间字段在数据层的定义非常简洁。TimeField 实现中字段类型固定为time并直接映射到 Sequelize 的DataTypes.TIME// packages/core/database/src/fields/time-field.ts import { DataTypes } from sequelize; import { BaseColumnFieldOptions, Field } from ./field; export class TimeField extends Field { get dataType() { return DataTypes.TIME; } } export interface TimeFieldOptions extends BaseColumnFieldOptions { type: time; }这意味着数据库中真实的列类型由 Sequelize 的TIME数据类型决定各数据库方言PostgreSQL、MySQL、SQLite、MariaDB 等会以方言对应的时间类型建列时间字段与日期字段一样属于“不含日期”的字段类别可选 Field type 只有time一种这与文档中“可选 Field typetime”的特性表一致因为存储的是纯时间列切换 Field type 会影响真实列的建表结构这正是后文“编辑配置”章节中警告切换 Field type 需要谨慎的原因。底层实现二TimeInterface 的写入归一化与校验时间字段的界面类型为time对应的接口类 TimeInterface 负责把外部传入的值规范化为可入库的时间字符串并做合法性校验// packages/core/database/src/interfaces/time-interface.ts import dayjs from dayjs; import utc from dayjs/plugin/utc; dayjs.extend(utc); function isNumeric(value: any): value is number { return typeof value number Number.isFinite(value); } function formatExcelTimeSerial(value: number) { const normalized ((value % 1) 1) % 1; const totalSeconds Math.round(normalized * 24 * 60 * 60) % (24 * 60 * 60); const hours Math.floor(totalSeconds / 3600).toString().padStart(2, 0); const minutes Math.floor((totalSeconds % 3600) / 60).toString().padStart(2, 0); const seconds (totalSeconds % 60).toString().padStart(2, 0); return ${hours}:${minutes}:${seconds}; } export class TimeInterface extends BaseInterface { toValue(value: any, ctx?: any) { if (isNumeric(value)) { return formatExcelTimeSerial(value); } if (this.validate(value)) { const result dayjs(value).format(HH:mm:ss); return result; } return value; } validate(value) { const result dayjs(value).isValid(); return result; } }从这段实现可以读出三个关键行为统一格式为HH:mm:ss任何能被 dayjs 解析的输入如14:30、02:15:00等在写入前都会被格式化为HH:mm:ss保证入库值格式一致筛选与排序行为可预期兼容 Excel 时间序列值如果传入的是 0 到 1 之间的数字Excel 中表示一天中时间点的序列值formatExcelTimeSerial会把它换算成小时、分钟、秒例如0.5对应12:00:00。这使从电子表格导入数据时时间列的数值能被正确转换校验即 dayjs 可解析性validate直接以dayjs(value).isValid()判断值是否合法无法解析的值会原样返回而不做格式归一由上层校验规则如 Validation rules 中配置的规则拦截。这套“界面类型负责归一化、字段类型负责存储”的分工正是 NocoBase 数据建模中 Field interface 与 Field type 分离设计的体现页面录入组件由 interface 决定数据库列由 field type 决定。字段特性一览时间字段的默认行为汇总如下特性说明默认 Field interfacetime。默认 Field typetime。可选 Field typetime。页面组件编辑模式使用时间选择器。筛选支持按时间、区间、为空、不为空筛选。排序支持按时间排序。校验支持必填和时间范围等校验。由于入库值统一为HH:mm:ss字符串格式见上文TimeInterface实现按时间排序和区间筛选在语义上是稳定的——同一“一天”内的时间值可以直接比较大小这也是时间字段能直接用于表格排序与筛选区块的底层基础。编辑字段配置展示调整与字段映射创建后点击字段右侧的「Edit」可以编辑时间字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式比如修改显示名称、说明、默认值、校验规则或字段专属配置。如果字段来自主数据库中已经同步的表编辑时通常是在做字段映射——把数据库字段映射为 NocoBase 的 Field type 和 Field interface。可编辑性如下配置允许编辑说明Field display name是修改字段在界面中的显示名称不改变字段标识名称。Field name否字段标识名称创建后通常不能在编辑表单中修改。Field interface条件支持主数据库字段或同步字段在字段映射时可以调整。调整后会影响页面输入、展示和校验方式。Field type条件支持主数据库字段或同步字段在字段映射时可以调整。调整前需要确认已有数据能否按新类型使用。Default value是调整新增记录时的默认值。Validation rules是调整字段校验规则。Description是补充字段含义、填写要求、数据来源或维护人。注意切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时先确认数据格式是否匹配。结合源码来看Field type直接决定 Sequelize 列类型见 TimeField 的dataType而Field interface决定写入时的归一化与校验逻辑见 TimeInterface两者分别作用于存储层和值处理层切换任一项都可能牵动已有数据的兼容性。删除时间字段点击字段右侧的「Delete」可以删除时间字段。主数据库中还可以勾选多个字段后批量删除。删除主数据库中新建的时间字段时通常会同时删除数据库中的真实列及该列已有数据删除从数据库同步或外部数据源映射出的字段时影响范围取决于对应数据源和字段来源。警告删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。页面配置使用时间字段适合在表单和规则配置中使用覆盖四类常见区块场景场景用途表单区块选择一天中的时间。表格区块展示、排序和筛选时间。筛选区块按时间范围筛选。工作流作为时间条件字段。在表单区块中字段以时间选择器组件录入在表格区块中因为入库值统一为HH:mm:ss格式排序与筛选行为是确定的在筛选区块中支持按时间、区间、为空、不为空等条件组合在工作流中时间字段可作为时间条件字段参与规则判断例如“当提醒时间到达某值时触发通知”这类排班、提醒类流程。相关资源字段 — 了解字段的作用、分类和映射逻辑普通表 — 在普通表中创建和管理字段日期 — 只保存日期日期时间含时区 — 保存日期和时间源码实现参考TimeField、TimeInterface【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考