用户报:数量输入框和旁边的输入框未对齐。
根因不是「差一条对齐样式」,是容器宽度写死:
.pt-toolbar__group { width: 160px } —— 但「打印设置」那组是三个 104px 的输入框
(含 gap 需要 332px),flex 只能把每个压到 46.7px。于是标签「数量」(两个字)
是一行、「上下边距(cm)」折成两行,输入域顶部实测 285 / 301 / 301,差 16px。
改法:
- .pt-toolbar__group 不再写死宽度(flex: 0 0 auto,按内容撑开);
只有下拉那一组需要定宽,单独给它 .pt-toolbar__group--template(160px)。
- 顶栏的输入标签加 white-space: nowrap、输入框加 flex: 0 0 auto:
以后标签文字再长也只会溢出,不会折行把同组其它输入框的输入域顶下去。
- 输入框 104 → 96px、inputs gap 10 → 8、toolbar gap 18 → 16:
1440px 视口下顶栏原本只差 24.5px 就换行(toolbar 内容 931.2 vs 可用 906.7),
收一收保持单行。这三个框只输「3 / 0.89 / 0.8」这类短值,宽了没收益。
原独立 Web 版查过,**没有**这个问题:它的 .tool-group 本来就没写死宽度,
1680 / 1440 / 1280 三种视口实测输入域 top 全一致(都是 83),所以本次不动它。
verify.mjs 的体积判据也换掉了:本插件内联 CSS 后产物 109KB,原来是「>60KB 就怀疑
内联了 vue」,从此会一直误报。现在改认 Vue 运行时的**实现端**符号
(__v_isRef / effectScope / createBaseVNode / shallowReadonly,本插件产物里恒为 0)。
注意不能用 createElementBlock 当判据 —— 那是编译后的渲染函数在**调用**它
(本插件产物里出现 65 次),拿它判会把正常产物判成内联。已用 vue.global.js
当负样本验证过这条断言真能拦住;自检现在 0 error 0 warning。
验证(发布产物,Playwright + 本机 Edge):
- 顶栏三格输入域 top 全为 285(aligned=true),label 全为单行;
- 1680 / 1440 单行不换行,1280 依旧同排;
- 13 项打印断言 + 5 项边框断言回归通过;
- 第三方消费方 4 项、宿主路径 4 项全过(CSS 恰好一份)。
产物已发布为 funjia.print-tag@1.0.4。
12 KiB
标签打印插件(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里改,当前见该文件)
产物自带样式。 JS 里内联了那份 CSS 并会在加载时自动注入, 所以消费方只取
entry也能正常显示 —— 不依赖它记得读style并注入<link>。 详见下面「产物形态」一节。
仓库根目录那份 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 配置)
├── vite.config.ts 构建配置;含 selfInjectStyles() —— 让产物自带样式(见 §5)
├── 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
五、产物形态:为什么 JS 里带着一份 CSS
仓库契约里 style 是独立字段:消费方要自己读它、注入 <link>。
文档写清楚了,官方参考消费方(宿主的 public/repo-consumer.html)也照做了 ——
但第三方很容易只取 entry,于是插件能跑、页面却是白板(布局全靠 CSS,
样式没了等于不可用)。实测过那种状态:文档里插件样式表数量 0,
.pt-panel 的宽度从 356px 变成撑满的 1368px。
一个交付物不该依赖消费方记得做第二步。所以 vite.config.ts 里有个
selfInjectStyles() 插件,在 generateBundle 阶段把抽出的 CSS 内联进 JS,
脚本一加载就注入 <style data-funjia-plugin="funjia.print-tag">。
| 做法 | 结果 |
|---|---|
保留 style 字段与那个 CSS 文件 |
按文档注入的宿主照常工作;CSP 禁止内联样式时,这是唯一出路 |
| JS 里再挂一层注入器 | 只取 entry 的消费方也能正常显示 |
| 注入前先检测 | 已有 <style data-funjia-plugin=…> 或 href 指向本样式文件的 <link> 就跳过 → 不会重复注入 |
为什么走 generateBundle 而不是「写完盘再改文件」:后者更简单,但注入发生在
vite 打印体积之后,日志会报 98KB、仓库索引却是 109KB,对不上账。
在产物落盘前改代码,体积 / checksum / 日志三者天然一致。
拿不到 CSS 资源时 this.warn 会显式报出来,不会静默少注入一份样式。
npm run verify 有两条断言盯着这两件事:① 产物必须含样式注入器;
② 产物里不能出现 Vue 运行时的内部实现符号(__v_isRef / effectScope …)。
判断「vue 有没有被内联」只能看这类实现端符号 —— 别用 createElementBlock:
它是编译后的渲染函数在调用,本插件产物里出现 65 次,一次都不是 Vue 的实现。
六、已知边界
--no-build之外的重建:dist/与node_modules/已被仓库根.gitignore忽略,不会进版本库。- 顶栏的分组别写死宽度:
.pt-toolbar__group里可能是单个下拉,也可能是三个并排的 输入框。写死 160px 会把三个输入框压到 46.7px —— 长标签「上下边距(cm)」折成两行、 短标签「数量」不折行,于是三格的输入域高低差 16px,看着就是「输入框没对齐」。 宽度交给各组自己定(下拉那组单独用.pt-toolbar__group--template收成 160px)。 - print 样式是临时注入的:打印时才插
<style media="print">,afterprint时移除。 常驻的话,用户在宿主里打印任何别的页面都会得到一张白纸 —— 插件 CSS 分不清 「现在打印的是不是我的页面」。beforeprint也在监听,所以Ctrl+P与宿主的打印入口 同样会走这套样式。 - 打印样式里有三处不能改的写法(改之前先读
PrintTagPage.vue里applyPrintStyles的注释): ①@page { margin: 0 }是「不要浏览器页眉页脚」的唯一开关,标签纸位置由.pt-paper的left/top给;② 隐藏类必须写成.x, .x *两段(visibility可被子元素覆盖, 只隐父元素的话里面的<span>1</span>会被.pt-paper *又显出来,序号照印); ③ 这些规则必须排在.pt-paper *之后(同特异性 + 同!important时后写的赢)。 - 虚线边框 = 「这一格纸上有东西」:空格 / 双击隐藏 / 模板内容全空都不画边框
(判定见
PrintTagPage.vue的isBlankOnPaper)。模板要自己声明hasContent,否则走通用兜底 —— 兜底偏宽松,CustomTag的color: "#000000"会被当成内容。规格类模板要标alwaysPrints(它们印左侧固定信息区,字段空也仍有墨)。 新增模板时这两项建议一并写清楚。 - Firefox 上页眉页脚关不掉:那是它打印对话框里的独立选项(「页眉和页脚」),
不是 CSS 能控制的东西;Chrome / Edge 上
@page margin: 0即可。 postcss.config.js不能删:本工程住在有 Tailwind 的仓库里,Vite 的 PostCSS 配置查找会往上走,加载到那份 Tailwind 配置后构建直接失败。- 预览器做不到的三件事(没有真 FunjiaUI、
ctx.plugin.repository为空、无路由守卫) 见funjia-plugin-starter的 README §3.3。