Skip to content

时间日期格式 ​

WeQ 的人类可读时间统一采用北京时间(Asia/Shanghai)、24 小时制。桌面、Web、服务、MCP、Bot 和导出共用无运行时依赖的 @weq/time,避免界面、宿主与浏览器使用不同日历。

按功能选择 ​

用途格式
绝对事件、详情、资料记录、邮件、通知YYYY-MM-DD HH:mm:ss
来源确有毫秒的完整详情和导出YYYY-MM-DD HH:mm:ss.SSS
纯日期、日期筛选YYYY-MM-DD
叙事日期、年报M 月 D 日,需要年份时 YYYY 年 M 月 D 日
月份标题YYYY 年 M 月;年报独立月份标签可用“一月”等
不完整生日只显示已知字段,例如 3 月 4 日;推断说明独立保留
消息分隔今天时分秒、昨天时分秒、过去 2–6 天星期及时分秒、更早完整日期时间
紧凑会话列表今天时分、昨天时分、一周内星期、更早日期;完整值放入时间提示
其他紧凑列表按功能省略同年年份或日期,跨年带年份,完整值可查看
相对时间刚刚、分钟/小时/天前;未来使用“后”或明确时间
时间范围同日可省略右端日期;跨年明确两端年份
图表轴与时间桶按跨度显示月日、时分或小时,不把事件精度强加给聚合刻度

非当天的未来事件不能归入“今天”。“昨天”和星期按北京自然日判断,不能除以运行设备的本地日历差。

文案间距 ​

应用生成的中文文案与半角数字、英文之间统一留一个半角空格,日期不例外: 2026 年 11 月 16 日、2026 年、3 分钟前、7 天后过期、1 小时 20 分钟。 多个日期或时长字段之间也只留一个空格,不产生首尾空格。中文标点前后不额外加空格, 例如 2010 年(推断)、推断生日:2010 年 1 月 20 日至 2 月 18 日。

同一约定用于年龄、数量与英文名称,例如 20 岁、共 12 条消息、QQ 号、复制 JSON。 数字与西文单位分隔为 10 MB、100 ms;百分比保持 50%。 数字日期、时刻与媒体进度内部不拆分,仍为 2026-11-16、12:34:56、03:20。 只调整应用生成的显示文案,不对聊天原文、昵称、签名、号码、URL、路径和文件名做自动加空格处理。

来源精度与空值 ​

  • 数值输入明确以毫秒计;Unix 秒必须先经 unixDate 转换,或使用 formatUnixTime,不根据数字长度猜单位。
  • formatDateTime 默认到秒。只有已确认具备毫秒精度的来源才传 millisecond,不能因为秒值转成 ISO 后有 .000 就认为它具备毫秒精度。
  • 纯日期和明确只到分钟的文本不补造秒。转换为 Date 会丢失来源精度,调用方需在转换前确定精度。
  • 泛用格式器允许合法 epoch;业务字段如果约定零表示缺省,调用方先处理。未知、无记录及原值回显等文案由功能层决定。
  • 非法日期返回空值;日期输入须往返核验,拒绝二月三十日、24 点、60 分等自动进位。
  • 逆向预览保留原始值与推断依据;无法确认单位和来源精度时不能伪装成确定的日期。

共用入口 ​

@weq/time 提供日历基础、事件日期时间、聊天分隔、紧凑列表、范围、相对时间、时长和输入转换。不要再按页面新建 Intl.DateTimeFormat 或用设备本地 getHours() 拼接用户可见时间。

ts
import { formatUnixTime, formatDateTime, formatChatTime } from '@weq/time';

formatUnixTime(sendTime); // 秒级事件
formatDateTime(observedAtMs, 'millisecond'); // 已确认的毫秒观察时间
formatChatTime(createdAtIso); // 消息分隔

数字日期稳定补零并使用横杠,不依赖系统 locale 的斜杠、补零或 12 小时默认规则。完整时间提示注明“北京时间”。

渲染层的 TimeLabel 复用全局提示层,支持悬浮、键盘聚焦和触屏点击,不为列表中的每个时间建立定时器。紧凑时间的提示应保留来源真实精度。日期和时间可在合理边界换行,不能裁掉秒或毫秒。

时长 ​

时长不是日历时刻,不经过时区转换:

  • 媒体进度用 m:ss;通话、录音用至少两位分钟的 mm:ss,分钟允许超过 59。
  • 倒计时使用时分秒;精确说明使用天、小时、分、秒,实际具备子秒时保留必要小数。
  • 统计可用易读约数,完整提示提供更精确值;消息时间差为零只说明落在同一秒。
  • 诊断耗时使用毫秒或秒,保留其测量精度;已有抓包和日志的毫秒显示不降级。
  • 先统一舍入再进位,不能出现“1分60秒”。语音气泡的秒数标记保持媒体语义,普通说明和导出使用明确单位。

输入与调度 ​

日期输入值仍是 YYYY-MM-DD,具体消息时间使用支持秒的北京时间墙钟输入;每日调度保留 HH:mm 配置,秒固定为零。

定时导出的每日触发及“今天/最近 7 天/30 天/一年”采用北京时间日界,保留原有包含端点和天数定义。自定义绝对范围和间隔调度不变。读取旧计划时仅重算未来每日触发点,已逾期记录沿用一次恢复流程,不改历史。

机器契约 ​

统一显示不改变 Unix、UTC ISO、带偏移 ISO、HTTP GMT、协议墙钟、分页游标和结构化导出字段。日期键、既有文件名和历史目录保留原契约,不通过重新命名或重新分桶“统一”历史数据。

维护脚本可直接导入 packages/time/src/index.mjs,不要求先安装依赖。内嵌 Bot 页面使用同源的 browserTimeSource,不在 HTML 字符串中再维护一套规则。

验证 ​

测试应使用固定样例,在上海、UTC 和具有夏令时的非东八区环境下核对午夜、跨年、未来、真实毫秒、粗精度、无效日期、时长进位及输入往返。界面验证同时检查完整时间提示、窄屏换行和消息列表渲染开销。

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准