数据格式化 plugin-formatter

约 749 字大约 3 分钟

...

2026-09-28

插件说明

数据格式化插件：增加 sFormatter（元素级）/ sFormatter2（表格列级）属性选项，在打印渲染与 #{field} 占位符取值时对数据执行格式化函数。无第三方依赖。

核心能力：

自定义格式化函数清单 funList，在元素属性面板以下拉框选择
通过 regexList 按规则匹配占位符字段名，自动套用对应格式化函数

安装：

npm install @sv-print/plugin-formatter

示例代码

import pluginFormatter from '@sv-print/plugin-formatter';

await hiprint.register({
  // 需 await 注册；init 不收插件数组
  plugins: [
    pluginFormatter({
      name: '格式化器', // 属性面板中选项的名称
      // 同 hiprint.setConfig(config)：配置哪些元素需要格式化器
      config: {
        text: {
          tabs: [
            {
              name: '基础',
              options: [{ name: 'sFormatter', hidden: false, after: 'testData' }],
            },
          ],
        },
      },
      funList: [
        // 必填
        // 格式化函数清单（必填）
        { name: '转大写', key: 'toUpperCase', fun: (v) => `${v}`.toUpperCase() },
        { name: '金额', key: 'money', fun: (v) => `¥ ${Number(v).toFixed(2)}` },
        { name: '布尔', key: 'bool', fun: (v) => (v ? '是' : '否') },
      ],
      regexList: [
        // 占位符字段名按规则匹配后，执行 funList 中同 key 项的 fun
        { regex: /(^|\.)(amount|price|total)$/i, key: 'money' }, // RegExp
        { regex: 'isActive', key: 'bool' }, // 字符串：与 key / fullKey 严格相等
        {
          regex: (key, value, fullKey) => key.startsWith('b_'), // 函数
          key: 'bool',
        },
      ],
    }),
  ],
});

高级用法

config 参数

参数	类型	说明
name	string	属性面板中选项的名称，默认 `格式处理器`
config	object	同 `hiprint.setConfig(config)`，配置哪些元素需要格式化器
funList	`{ name, key, fun }[]`	格式化函数清单（必填）；`name` 展示名、`key` 格式化器 key、`fun(value)` 格式化函数
regexList	`{ regex, key }[]`	占位符匹配规则（可选）；`regex` 支持 RegExp / 字符串 / 函数

regexList 匹配规则

getPlaceholderValue hook 在每次解析占位符时，按顺序遍历 regexList：

regex 为 RegExp：对 key 与 fullKey 依次执行 .test()，任一命中即匹配
regex 为 字符串：与 key 或 fullKey 严格相等即匹配
regex 为函数：回调 (key, value, fullKey) => boolean，返回 true 即匹配；异常视为未命中
命中后查找 funList 中 key === rule.key 的项并执行其 fun(value)
找不到对应 key 的 funList 项时跳过该规则，继续匹配下一条
fun 抛错时打印日志并原样返回 value，不影响其他字段
全部未命中时原样返回 value

注意事项

格式化结果写入 ele.options.sFormatter（元素级）/ sFormatter2（表格列级）
默认注册到元素属性面板的「高级」tab

版权所有

版权归属：sv-print

许可证：署名 4.0 国际 (CC-BY-4.0)