NocoBase 模板打印时间间隔格式化：:formatI 语法、单位换算与人性化输出完全指南

NocoBase 模板打印时间间隔格式化:formatI 语法、单位换算与人性化输出完全指南【免费下载链接】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时间间隔时长格式化是业务单据打印中最高频的需求之一工单耗时、服务时长、保修周期、倒计时提示都需要把原始的毫秒数值或 ISO 8601 时长字符串翻译成人类可读的文本。NocoBase 模板打印提供的:formatI(patternOut, patternIn)格式化器专门用于完成这类转换——它既能输出2、60、28这样的纯数值时长也能输出a few seconds、in a few seconds、a few seconds ago这样的人性化文案还能直接解析P1M、P1Y2M3DT4H5M6S等 ISO 8601 时长字符串。读完本文你将完整掌握formatI的全部输出单位、单位换算规则、人性化模式以及在实际打印模板中的组合用法。1. formatI 在模板打印格式化器体系中的位置NocoBase 模板打印的格式化器formatter是一组把原始数据转换成可读文本的处理器统一通过冒号:应用于数据且可以链式调用——每个格式化器的输出会作为下一个格式化器的输入详见 格式化工具总览。其基本调用形式为{d.属性:formatter1:formatter2(...)}例如先lowerCase再ucFirst可以把JOHN渲染为JohnMy name is {d.name:lowerCase:ucFirst}. I was born on {d.birthday:formatD(LL)}.formatI正是这套格式化器体系中负责时长 / 时间间隔处理的成员与负责日期时刻的formatD见 日期格式化形成互补formatD回答这一刻是哪天几点formatI回答这段时间有多长、怎么读。2. :formatI(patternOut, patternIn) 语法说明{值:formatI(patternOut, patternIn)}参数定义参数是否必填说明patternOut必填输出格式例如second、human决定结果以什么单位或什么风格呈现patternIn可选输入单位例如milliseconds、s用于声明原始值的单位省略时默认按毫秒milliseconds解析其中patternOut支持两大类输出格式人性化显示human、human适合直接展示给最终用户阅读数值单位millisecond(s)、second(s)、minute(s)、hour(s)、year(s)、month(s)、week(s)、day(s)等单位或其简写适合后续参与计算或按固定单位对齐展示。单位简写约定与 diffD 日期差值计算 保持一致例如s表示秒、ms表示毫秒、h表示小时、d表示天。此外格式化器的常量参数如果包含逗号或空格需要用单引号包裹如prepend(my prefix)formatI的格式参数同样遵循这一约定。3. 数值输出把毫秒换算成指定单位当patternOut指定为某个时间单位时formatI会将输入值换算到该单位并返回数值。以下示例默认输入单位为毫秒ms2000:formatI(second) // 输出 2 2000:formatI(seconds) // 输出 2 2000:formatI(s) // 输出 2 3600000:formatI(minute) // 输出 60 3600000:formatI(hour) // 输出 1 2419200000:formatI(days) // 输出 28从这些示例可以归纳出单位换算关系与典型取值输入毫秒换算关系输出单位结果20002000 ÷ 1000second(s)/s236000003600000 ÷ 60000minute(s)6036000003600000 ÷ 3600000hour(s)124192000002419200000 ÷ 86400000day(s)/days28可见单数second、minute、hour、day与复数seconds、minutes、hours、days写法等效简写如s同样被接受。换算按标准进制执行1 秒 1000 毫秒1 分钟 60 秒1 小时 60 分钟1 天 24 小时1 周 7 天。需要注意的是月month与年year属于非整数倍单位具体折算系数见第 6 节关于 ISO 8601 解析的说明。4. 人性化输出human 与 human当patternOut为human或human时结果不再是纯数值而是适合界面展示的自然语言文案2000:formatI(human) // 输出 a few seconds 2000:formatI(human) // 输出 in a few seconds -2000:formatI(human) // 输出 a few seconds ago从输出风格看formatI的人性化文案遵循 humanize-duration 一类库的约定human与human的差异在于human直接输出时长描述如a few seconds数秒human针对正值附加未来语义前缀输出in a few seconds在几秒后针对负值附加过去语义后缀输出a few seconds ago几秒前。这一特性特别适合倒计时、有效期剩余时间、任务执行耗时等场景。例如距离任务开始还有几秒可以这样渲染距离开标还有 {d.timeLeft:formatI(human)}当d.timeLeft为正值时显示in …为负值时自动切换为… ago模板无需自己判断正负号。5. 单位换算通过 patternIn 声明输入单位当原始数据不是毫秒时可以通过第二个参数patternIn声明输入单位formatI会先把输入换算成毫秒再按patternOut输出60:formatI(ms, minute) // 输出 3600000 4:formatI(ms, weeks) // 输出 2419200000第一个示例输入值为60、单位为minute分钟先换算为 60 × 60000 3600000 毫秒再以ms毫秒输出结果为3600000第二个示例输入值为4、单位为weeks周先换算为 4 × 7 × 86400000 2419200000 毫秒再以ms输出结果为2419200000。这一能力让模板可以直接消费来自不同数据源、不同单位约定的字段数据库里存的是分钟就写patternIn minute表单提交的是周数就写patternIn weeks无需在数据入库前预先做单位归一化。6. 直接解析 ISO 8601 时长字符串除了纯数值formatI还能直接解析 ISO 8601 时长字符串P...T...格式这是处理跨系统时长数据时非常实用的能力P1M:formatI(ms) // 输出 2628000000 P1Y2M3DT4H5M6S:formatI(hour) // 输出 10296.085P1M表示 1 个月按月 365 ÷ 12 天折算为 30.416666… 天即 2628000000 毫秒P1Y2M3DT4H5M6S表示 1 年 2 个月 3 天 4 小时 5 分 6 秒按年 365 天、月 365 ÷ 12 天折算后以小时输出结果为 10296.085 小时即 8760 1460 72 4 0.0833… 0.00166… ≈ 10296.085。由此可以推断formatI对非整数单位的折算采用以下基准与上述官方示例的计算结果完全吻合1 年 365 天1 月 365 ÷ 12 ≈ 30.4166667 天1 周 7 天1 天 24 小时 86400000 毫秒因此在对月 / 年级时长做精确换算时应留意结果包含小数如10296.085小时模板中若需取整展示可再结合数值格式化器处理。7. 与日期类格式化器组合的实战场景formatI与模板打印中的日期格式化器搭配可以覆盖起止时间 → 时长 → 可读文案的完整链路计算两个日期的差值再人性化展示先用diffD求出两个日期之间的毫秒差再交给formatI输出。diffD默认输出单位为毫秒详见 日期格式化其返回值正好可以作为formatI的输入{d.endDate:diffD(d.startDate):formatI(human)} // 例如 a few seconds {d.endDate:diffD(d.startDate, minutes):formatI(hour)} // 先按分钟求差再换算为小时到期提醒文案用diffD求出当前时间 - 截止时间的差值负值表示已过期再以formatI(human)输出自动得到还有 X或X 之前的文案工期 / 服务时长统计直接用毫秒字段formatI(days)输出精确到天的时长或用formatI(hours)输出精确到小时的工时。由于格式化器支持链式调用前一个的输出作为后一个的输入上述组合无需编写脚本纯模板即可实现。8. 使用注意事项默认输入单位是毫秒省略patternIn时数值输入一律按毫秒解析。如果字段实际单位是秒或分钟务必显式声明patternIn否则结果会差几个数量级patternOut使用字符串字面量与格式化器常量参数约定一致格式串建议用单引号包裹如formatI(seconds)月 / 年换算存在小数ISO 8601 与月 / 年单位的折算基于 365 天/年、365÷12 天/月结果可能为小数按需配合取整格式化器数值与人性化输出并存需要参与后续计算时用单位输出second、hour等仅需展示时用human/human避免把可读文案再喂给数值计算适用版本本文语法以当前仓库 模板打印文档 及其 安装说明 为准模板打印为商业插件使用时请先按官方商业插件激活流程完成激活Docker 环境如需生成 PDF还需按 安装文档 安装 LibreOffice。综上formatI以两个参数覆盖了数值 → 指定单位、数值 → 人性化文案、指定输入单位 → 毫秒归一、ISO 8601 字符串 → 任意单位四类转换是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考