NocoBase Unix 时间戳字段详解从配置到存储的完整实现解析【免费下载链接】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 的数据建模中Unix 时间戳Unix timestamp字段用于保存外部系统传入的时间戳数值它落库的是数字但业务含义是时间。本篇指南基于官方文档 unix-timestamp.md 与nocobase/database包的源码实现完整讲清该字段的适用场景、创建/编辑/删除配置、各配置项的作用以及底层如何完成「时间 ↔ 数值」的双向转换读完你可以直接把它用于外部系统对接、日志时间记录和历史数据迁移等实战场景。一、什么是 Unix 时间戳字段什么时候该用它Unix 时间戳是「从 1970-01-01 00:00:00 UTC 起经过的秒或毫秒数」这种纯数值表示法。NocoBase 提供该字段的目的是让数据库列直接保存这个数值同时在前端、筛选、工作流中按「时间」语义来使用。官方文档给出的适用场景包括外部系统同步时间戳第三方系统只吐 timestamp不给你 ISO 日期字符串日志发生时间日志系统普遍以秒级时间戳记录接口返回的 Unix timestamp历史数据迁移中的时间字段旧库整型列里存的就是时间戳。选型建议如果没有外部系统时间戳的硬约束直接使用日期时间字段更容易理解和维护。Unix 时间戳字段的价值恰恰体现在「必须按数值存」的对接场景——它让存储格式与外部系统完全一致无需转换即可对账、比对和迁移。二、创建字段与配置项说明在数据表的「Configure fields」页面中点击「Add field」选择「Unix 时间戳」即可创建字段。创建表单中的各配置项含义如下配置说明Field interface字段的界面类型。Unix 时间戳对应unixTimestamp决定页面中如何录入和展示。Field display name字段在界面中显示的名称比如「同步时间戳」「日志时间」「外部更新时间」。建议使用业务人员能直接理解的名称。Field name字段标识名称用于 API、关系字段、权限、工作流等内部引用。创建后通常不再修改只支持字母、数字和下划线并且必须以字母开头。Field type字段在数据层的类型。Unix 时间戳通常使用整数或大整数保存。Default value默认值。新增记录时如果用户没有填写可以自动带出默认值。Validation rules校验规则。可以配置必填和数值范围。Description字段说明。适合写字段含义、填写要求、数据来源或维护人。注意字段名创建后会被页面区块、权限、工作流和 API 引用。创建前先确认命名避免后续修改带来配置调整成本。默认取值与可选项源码级印证文档中「默认 Field type 为bigInt、可选integer/bigInt」这一条可以在源码中直接印证。UnixTimestampField 类 定义了默认数据类型export class UnixTimestampField extends DateField { get dataType() { return DataTypes.BIGINT; } // ... }dataType返回DataTypes.BIGINT即默认按大整型列建表这也是为什么文档标注默认 Field type 为bigInt。同时该字段在 接口注册表 中被映射到时间日期界面const interfaces { // ... datetime: DatetimeInterface, datetimeNoTz: DatetimeNoTzInterface, unixTimestamp: DatetimeInterface, // ... };也就是说unixTimestamp的界面行为复用DatetimeInterface录入、展示、校验逻辑与日期时间一致这正是文档中「页面组件编辑模式按时间戳字段组件处理」的底层来源。三、字段特性底层如何完成「时间 ↔ 数值」转换文档给出的默认行为如下表特性说明默认 Field interfaceunixTimestamp。默认 Field typebigInt。可选 Field typeinteger、bigInt。页面组件编辑模式按时间戳字段组件处理。筛选支持按时间戳数值或映射后的时间范围筛选。排序支持排序。校验支持必填和数值范围校验。这些行为背后的核心机制在 unix-timestamp-field.ts 中实现分两个方向写入方向Date/ISO 字符串 → 时间戳数值字段通过 Sequelize 的set钩子拦截写入值传入的如果是数字则原样落库Math.floor保证整数如果是日期对象或日期字符串则先转为Date再除以比例系数取整。set(value) { if (value null) { this.setDataValue(name, value); } else { // date to unix timestamp this.setDataValue( name, Math.floor(typeof value number ? value : new Date(value).getTime() / rationalNumber), ); } },这里有一个关键参数accuracy精度accuracy: second默认rationalNumber 1000即毫秒时间戳 / 1000落库为秒级时间戳accuracy: millisecondrationalNumber 1落库为毫秒级时间戳。精度取值优先级为字段options中的accuracy若uiSchema[x-component-props].accuracy存在则以后者覆盖两者都缺省时按second处理见 dateToValue 实现。这意味着精度可以在字段配置的界面组件属性x-component-props中指定覆盖创建时的设置。读取方向时间戳数值 → Date 对象读取时通过get钩子把数值还原为Date对象再乘回比例系数get() { const value this.getDataValue(name); if (value null) { return value; } return new Date(value * rationalNumber); },由于读出的是Date对象后续的格式化、筛选、排序都可以走日期时间的通用逻辑——这就是文档所说「支持按时间戳数值或映射后的时间范围筛选」「支持排序」的原理数据库里比的是整数ORM 层拿到的是 Date。测试用例印证的行为unix-timestamp-field.test.ts 中的测试覆盖了几个值得注意的行为defaultToCurrentTime: true新增记录时不填值该列自动写入当前时间对应文档 Default value 配置项的「自动带出默认值」能力写入 ISO 字符串、读出时间戳以date1: 2021-01-01T00:00:00Z创建记录后读回按 UTC 格式化结果仍为2021-01-01 00:00:00验证了 ISO 输入 → 数值落库 → Date 读出的完整链路无损秒级精度下数字原样保留accuracy: second时传入的秒级数值不会被二次换算直接以原值保存。界面录入侧的容错DatetimeInterface由于unixTimestamp复用 DatetimeInterface录入链路还具备额外的容错能力toValue支持日期字符串如YYYY-MM-DD、YYYYMMDD HH:mm:ss、Date/Dayjs 对象以及纯数字输入纯数字会被识别为 Excel 日期序列值excel-date-to-js结合请求头X-Timezone由resolveTimeZoneFromCtx解析换算为 ISO 时间避免 Excel 导入时把时间戳列误当普通数字toString展示时依据界面组件属性中的format与请求时区偏移进行格式化输出保证表格区块里显示的是可读时间而非裸数字。展示格式化formatUnixTimestamp 与精度在 API 层使用format对字段做展示格式化时QueryFormatter.format 对unixTimestamp类型的处理是case unixTimestamp: { const accuracy fieldOptions?.uiSchema?.[x-component-props]?.accuracy || fieldOptions?.accuracy || second; return this.formatUnixTimestamp(field, format, accuracy, timezone); }它从字段配置中取出精度缺省second交由具体数据库方言的formatUnixTimestamp在 SQL 层完成「数值 → 时间 → 格式化字符串」的转换并支持传入时区。这解释了为什么表格区块可以按你指定的格式展示时间戳而不需要把原始数值搬到前端换算。四、从已有表同步时的字段映射如果字段来自主数据库中已经同步的表编辑时本质上是在做字段映射——把数据库列映射为 NocoBase 的 Field type 和 Field interface。映射候选项由 field-type-map.ts 决定摘录与时间戳相关的条目const mysql { // ... int: [integer, unixTimestamp, sort], int unsigned: [integer, unixTimestamp, sort], integer: [integer, unixTimestamp, sort], bigint: [bigInt, snowflakeId, unixTimestamp, sort], bigint unsigned: [bigInt, snowflakeId, unixTimestamp, sort], // ... }; const postgres { // ... integer: [integer, unixTimestamp, sort], bigint: [bigInt, snowflakeId, unixTimestamp, sort], // ... };即 MySQL/MariaDB 的int、int unsigned以及 PostgreSQL 的integer列可映射为integer、unixTimestamp或sort中的任一bigint/bigint unsigned列额外可映射为bigInt或snowflakeId。这对应了文档中「可选 Field typeinteger、bigInt」的说法数据库列类型决定映射时的候选界面类型集合。注意SQLite 方言的映射表中没有unixTimestamp候选见同文件sqlite段在 SQLite 数据源上做整型列映射时从源码结构看该候选不会出现。五、编辑字段配置创建后点击字段右侧的「Edit」可以编辑 Unix 时间戳字段配置。编辑字段主要用于调整字段在 NocoBase 中的展示和使用方式比如修改显示名称、说明、默认值、校验规则或字段专属配置。各配置项的可编辑性如下配置允许编辑说明Field display name是修改字段在界面中的显示名称不改变字段标识名称。Field name否字段标识名称创建后通常不能在编辑表单中修改。Field interface条件支持主数据库字段或同步字段在字段映射时可以调整。调整后会影响页面输入、展示和校验方式。Field type条件支持主数据库字段或同步字段在字段映射时可以调整。调整前需要确认已有数据能否按新类型使用。Default value是调整新增记录时的默认值。Validation rules是调整字段校验规则。Description是补充字段含义、填写要求、数据来源或维护人。注意切换 Field type 或 Field interface 不等于简单改一个显示名称。它会影响字段的存储方式、输入组件、校验规则、筛选条件和工作流变量使用方式。已有数据较多时先确认数据格式是否匹配。这一点结合源码尤其直观accuracy精度同时作用于读、写、格式化三处钩子把字段从秒级切到毫秒级意味着存量数据按新系数重解释后时间会整体漂移切换前必须先确认数据口径。六、删除字段点击字段右侧的「Delete」可以删除 Unix 时间戳字段。主数据库中还可以勾选多个字段后批量删除。删除主数据库中新建的 Unix 时间戳字段时通常会同时删除数据库中的真实列及该列已有数据删除从数据库同步或外部数据源映射出的字段时影响范围取决于对应数据源和字段来源。警告删除字段可能影响页面区块、表单、筛选、权限、工作流、API、导入导出和已有数据。删除前先确认字段是否仍被业务配置引用。七、页面配置使用Unix 时间戳字段适合外部系统对接和日志类场景常见用法如下场景用途表单区块录入或映射时间戳。表格区块展示、排序和筛选时间戳。工作流作为外部系统时间条件使用。API对接要求 Unix timestamp 的接口。在 API 对接中由于写入链路天然兼容「数字原样落库」外部系统直接传秒级/毫秒级整型值即可无需在网关层做任何日期解析反向输出时可用字段格式化能力按指定 format 与时区转成可读字符串。八、延伸阅读字段 — 了解字段的作用、分类和映射逻辑普通表 — 在普通表中创建和管理字段日期时间含时区 — 保存普通日期时间整数 — 保存普通整数。本文的技术细节以当前仓库源码为准核心实现参考 unix-timestamp-field.ts、field-type-map.ts、datetime-interface.ts 与 unix-timestamp-field.test.ts。【免费下载链接】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），仅供参考