Files
print-tag-system/plugin/README.md
T
funjia 85f7f9abb4 fix: 打印不再输出浏览器页眉与序号(原 Web 版 + 插件版都修)
用户反馈:打印时页眉带日期时间,序号 1–44 也被印出来。两处根因如下。

1. 浏览器页眉(左上角日期时间 + 标题)
   @page 边距非 0 时,浏览器会在「页边距那块空白」里画它自己的页眉页脚。
   CSS 里没有关掉它的开关 —— 把边距清零、让那块空白消失,是 Chromium/Edge 上
   唯一可靠的做法(Firefox 的页眉页脚是打印对话框里的独立选项,CSS 管不了)。
   代价:标签纸在纸上的位置不能再靠 @page margin 给,改由 .page / .pt-paper 的
   left / top 控制 —— 物理结果与之前完全一致,顶栏「上下/左右边距」的含义
   变成「标签纸离纸边的距离」。

2. 序号角标与空格虚线引导照样打印
   visibility 是**可被子元素覆盖的继承属性**。原来只隐 `.id` / `.pt-cell__idx`,
   父元素确实隐了,但下面那条让标签纸整体可见的 `.page * { visibility: visible }`
   会**直接命中里面的 <span>1</span>** 把它又显出来 —— 序号照样印在纸上,
   而这条规则看上去毫无问题。现在所有「打印时不该出现」的选择器一律写成
   `.x, .x *` 两段;插件版还要求它们排在 `.pt-paper *` 之后
   (同特异性 + 同 !important 时后写的赢,写前面等于没写、还不报错)。
   顺带修掉双击「隐藏(不打印)」的格子内容仍被打印的问题。

顺带加固:
- Ctrl+P 也走同一套样式 —— 加 beforeprint 监听(原来只有点插件按钮才注入)。
- 撤销样式改用 node.remove():对已脱离的节点调 removeChild 会抛 NotFoundError,
  把整段注入打断在半路,症状是「这次打印什么都没生效」。

验证(Playwright + 本机 Edge,走真实打印管线):
- 插件版 13 项断言通过;原 Web 版 12 项断言通过。
- 两版都生成 PDF(displayHeaderFooter: true)并用浏览器 PDF 视图渲染确认:
  页眉无日期时间、无序号、双击隐藏的格子留白、有内容的格子正常打印。
- 插件产物已升版本发布为 funjia.print-tag@1.0.1。
2026-10-04 00:32:03 +08:00

7.9 KiB
Raw Blame History

标签打印插件(funjia.print-tag)

本目录是 print-tag-system 的插件化形态:同一套标签排版 / 打印能力, 改造成可被 FunjiaUI 宿主装载的远端插件,并加了可选的 SN 码 → 条码 / 二维码能力。

  • 插件 id:funjia.print-tag
  • 产物:dist/PrintTagBundle.iife.js + dist/PrintTagBundle.css(IIFE,自注册)
  • 上架位置:funjia-plugin-repository 插件仓库的 repository/plugins/funjia.print-tag/<版本>/ (版本号在 plugin.config.json 里改,当前见该文件)

仓库根目录那份 src/ 是原独立 Web 版,两者并存、互不影响。


一、和原 Web 版的关系

能力 原 Web 版 本插件
启动方式 createApp(App).mount('#app'),自己起 Vite 服务 宿主装载 → activate(ctx) → ctx.addRoute 挂页面
路由 / 菜单 无(单页) 注册到宿主侧边栏(设备管理 → 标签打印)
内置模板 11 个 .vue 文件 11 个模板,渲染收敛成 SpecTag,差异集中在 templates/registry.ts
二维码图片 站点根目录 /qrcode.png 打包成 data URL 内置(远端插件没有自己的 public/)
下拉选择 @headlessui/vue Listbox 原生 <select>(少 30KB,且浮层不会进打印流)
样式 Tailwind 4 + 全局 CSS 纯 CSS,类名一律 pt- 前缀(插件 CSS 是注入宿主全局的)
店铺名 / 电话 写死在每个模板里 面板可改,记忆到插件私有存储
SN 码 / 条码 / 二维码 无 可选(见第三节)

标签尺寸、44 格版面、模板字段与选项、打印边距、双击隐藏等行为逐项保持原样。


二、开发与交付

cd plugin
npm install

npm run dev        # 本地预览(http://127.0.0.1:5310),改 src/** 立刻生效
npm run build      # 产物落到 dist/
npm run typecheck  # tsc --noEmit
npm run verify     # 自检:清单自洽 / 源码边界 / 产物形态 / 预览资产
npm run preview    # 产物模式预览(http://127.0.0.1:5310/artifact.html),验 external 与 CSS 抽取

交付到插件仓库(构建 → 归档 → 重写索引,一步到位):

node scripts/deploy.mjs --repo ../plugin-repo --no-build

⚠️ 发布脚本要求 plugins/dist/ 里齐备 repo.config.json 中所有插件的产物 (那是它的暂存区,已被 gitignore)。仓库里其它插件的产物在 repository/plugins/ 下已归档,回填即可:

cd ../plugin-repo
for d in repository/plugins/*/*/; do for f in "$d"*; do
  b=$(basename "$f"); [ "$b" = plugin.json ] || cp -n "$f" plugins/dist/
done; done
node scripts/publish-repo.mjs

三、SN 码 / 条码 / 二维码(可选)

面板「② SN 码 · 条码 / 二维码(可选)」有一个总开关,默认关闭。

开关 行为
关闭 完全保持原样:左侧用内置静态二维码图,不调用任何接口
开启 走宿主后端 api::sn-code,按 SN 现场生成真 Code 128 条码与可扫二维码

开启后:

  • 批量领码并填充 —— 优先贴到「已排好版但还没 SN」的格子上,不够才往空格新建标签 (顺序很重要:先排版再贴码才是真实用法,否则点一下会多出一堆空壳标签);
  • 单格编辑面板里可手工填 SN,或「领 1 条」单独取码;
  • 校验选中格 SN —— 格式 + 校验位 + 台账存在性,都由后端判定。

接口(与 funjia.sn-tools 插件共用同一套后端,定义在 库存管理系统/backend/src/api/sn-code/):

GET  /api/sn-codes/meta              业务类型 / 默认前缀 / 码长
POST /api/sn-codes/generate          单条发放
POST /api/sn-codes/batch             批量发放 → { batch, count, items: [...] }
POST /api/sn-codes/verify            校验 → { valid, reason, exists, record }

发放时请求体里带 source: "funjia.print-tag" —— 后端把它记进 SN 台账, 用来区分「这条码是插件发的还是别的入口发的」(不填一律记成 pc)。

两个命令也注册给了别的插件:

  • print-tag:issue-sn —— 按业务类型领 N 条 SN;
  • print-tag:render-svg —— 纯本地把文本渲染成条码 / 二维码 SVG(不调接口)。 别的插件想在自己的标签上画码,调这一条即可,不必各自引一份条码库、 也不必各自踩一遍 Code 128 校验位的坑。

物理尺寸:必须知道的三个数

标签格是 48.5mm × 25.4mm。格子放不下两个「全尺寸」图形,所以:

项 值 说明
二维码模块 约 0.54mm/模块 16 位 SN 在 EC-M 下是 25×25 模块,18mm 出图 → 203dpi 下约 4 个点/模块,很稳
二维码(开条码后) 约 0.34mm/模块 条码条吃掉 6.6mm,二维码被挤到约 11mm
条码模块 约 0.199mm(7.8 mil) 46mm 宽塞 211 个模块(16 位 SN)。这已接近 Code 128 下限 7.5 mil,203dpi 下每模块不到 2 个点

界面上会把这两个数实时算出来并给出建议(换 300dpi / 关掉条码)。

一句话:二维码是可靠路径,条码在这个格子上是「勉强够用」。 需要高可靠条码时应换更大的标签纸,或让标签软件(BarTender 等)去出图。


四、目录结构

plugin/
├── plugin.config.json        ★ 元数据唯一真源(id / 版本 / 产物名 / 扩展点声明)
├── postcss.config.js         截断 PostCSS 查找链(否则会加载仓库根目录的 Tailwind 配置)
├── src/
│   ├── index.ts              ★ 插件入口:生命周期 + 注册菜单/路由/2 个命令
│   ├── codes.ts              Code 128 与真 QR 的 SVG 生成(纯函数,单位 mm)
│   ├── sdk.ts / runtime.ts   宿主能力契约与 ctx 持有者
│   ├── components/           LabelCell / TagShell / DynamicForm / Input / Select
│   ├── templates/            SpecTag / ErrorTag / CustomTag + registry.ts(模板注册表)
│   ├── pages/PrintTagPage.vue  ★ 主页面:44 格版面 + 面板 + SN 集成
│   └── assets/default-qr.ts  内置默认二维码(data URL)
├── scripts/                  deploy / verify
└── preview/                  本地预览器(迷你宿主 + 调试面板 + mock 后端)

preview/mock-api.ts 里额外实现了 /api/sn-codes/*(模板原本只有通用 CRUD)。 少了它,本地一打开 SN 开关就是 404,只能走「构建 → 发布 → 装进宿主 → 点一遍」, 一圈几分钟。

mock 的 SN 部分是逐位镜像真后端的(库存管理系统/backend/src/api/sn-code/): 前缀表、SN 形状、格式正则、序号补位口径,以及校验位算法与字符表都照抄 —— 所以预览里生成的 SN 拿去真后端 /verify 也能过校验位,本地调通的链路切到真后端不会失效。 唯一不是真的地方是数据:台账在进程内存里,重启即清空。只验链路,别对号段。

调真后端:

PREVIEW_API_TARGET=http://127.0.0.1:1337 npm run dev

五、已知边界

  • --no-build 之外的重建:dist/ 与 node_modules/ 已被仓库根 .gitignore 忽略,不会进版本库。
  • print 样式是临时注入的:打印时才插 <style media="print">,afterprint 时移除。 常驻的话,用户在宿主里打印任何别的页面都会得到一张白纸 —— 插件 CSS 分不清 「现在打印的是不是我的页面」。
  • postcss.config.js 不能删:本工程住在有 Tailwind 的仓库里,Vite 的 PostCSS 配置查找会往上走,加载到那份 Tailwind 配置后构建直接失败。
  • 预览器做不到的三件事(没有真 FunjiaUI、ctx.plugin.repository 为空、无路由守卫) 见 funjia-plugin-starter 的 README §3.3。