feat(plugin): 产物自带样式 —— 第三方只取 entry 也能正常显示

第三方系统装完后样式全丢。复现出来的根因是产物形态:CSS 被抽成独立文件,
仓库契约要求消费方自己读 `style` 并注入 <link>(文档写了、官方参考消费方也照做了),
但第三方很容易只取 `entry`:插件能跑、页面却是白板(布局全靠 CSS)。
实测:只取 entry 时文档里插件样式表数量 0,.pt-panel 宽度从 356px 变成撑满的 1368px。

改法:vite.config.ts 新增 selfInjectStyles() 插件,在 generateBundle 阶段
把抽出的 CSS 内联进 JS,脚本一加载就注入 <style data-funjia-plugin=…>。

- 保留 style 字段与 CSS 文件不变:按文档注入的宿主照常工作;CSP 禁止内联样式时
  那条路仍是唯一出路。
- 不重复注入:先检测有没有本插件的 <style data-funjia-plugin=…>,
  或 href 指向本样式文件的 <link>,有就跳过。
- 走 generateBundle 而非「写完盘再改」:后者注入发生在 vite 打印体积之后,
  日志 98KB / 索引 109KB 对不上账。
- 拿不到 CSS 资源时 this.warn 显式报出,不静默少注入。
- verify.mjs 加断言盯着它(产物必须含注入器)。

验证:第三方最小消费方 4 项断言全过;宿主路径 4 项全过(CSS 恰好一份、无重复注入);
对已发布产物跑 13 项打印断言全过。产物已发布为 funjia.print-tag@1.0.3。

注意:本工程从此不再等同于 funjia-plugin-starter 的默认产物形态 ——
其他插件若也会被第三方接入,值得把这套 self-inject 搬过去。
This commit is contained in:
2026-10-04 01:32:14 +08:00
parent a049492864
commit 21d293775d
4 changed files with 151 additions and 4 deletions
+33 -1
View File
@@ -8,6 +8,10 @@
- 上架位置:`funjia-plugin-repository` 插件仓库的 `repository/plugins/funjia.print-tag/<版本>/`
(版本号在 `plugin.config.json` 里改,当前见该文件)
> **产物自带样式。** JS 里内联了那份 CSS 并会在加载时自动注入,
> 所以消费方**只取 `entry` 也能正常显示** —— 不依赖它记得读 `style` 并注入 `<link>`。
> 详见下面「产物形态」一节。
仓库根目录那份 `src/` 是**原独立 Web 版**,两者并存、互不影响。
---
@@ -121,6 +125,7 @@ POST /api/sn-codes/verify 校验 → { valid, reason, exists, record
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)
@@ -150,7 +155,34 @@ 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` 里有一条断言盯着它(产物必须含注入器),回归时能拦住。
---
## 六、已知边界
- **`--no-build` 之外的重建**:`dist/` 与 `node_modules/` 已被仓库根 `.gitignore` 忽略,不会进版本库。
- **print 样式是临时注入的**:打印时才插 `<style media="print">`,`afterprint` 时移除。
+1 -1
View File
@@ -1,7 +1,7 @@
{
"id": "funjia.print-tag",
"name": "标签打印",
"version": "1.0.2",
"version": "1.0.3",
"kind": "iife",
"artifact": "PrintTagBundle.iife.js",
"style": "PrintTagBundle.css",
+24
View File
@@ -29,6 +29,9 @@ import { fileURLToPath } from "node:url";
const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
/** 与 vite.config.ts 里 selfInjectStyles() 用的哨兵注释保持一致 */
const INJECTOR_SENTINEL = "/* funjia:self-inject-styles */";
/* ------------------------------------------------------------------ 输出 */
let errors = 0;
@@ -290,6 +293,27 @@ if (!existsSync(distDir)) {
// 否则宿主会去注入一个 404 的样式表。
warn(`dist/${cfg.style} 不存在,但配置里声明了 style —— 页面若无 <style> 请去掉该字段`);
}
/*
* 产物必须**自带样式**(把 CSS 内联进 JS 并自动注入)。
*
* 索引里的 `style` 是独立字段,要消费方自己读、自己注入 —— 文档写清楚了,
* 官方参考消费方也照做了,但第三方很容易只取 `entry`:插件能跑、页面却是白板。
* 实测过那种状态:文档里插件样式表数量 0,`.pt-panel` 宽度从 356px 变成撑满。
*
* 所以「JS 里有没有那段注入器」是必须守住的不变量,不是可选优化。
*/
if (artifactPath && existsSync(artifactPath)) {
const text = readFileSync(artifactPath, "utf8");
if (text.includes(INJECTOR_SENTINEL)) {
ok("产物自带样式(含 self-inject 注入器)");
} else {
bad(
"产物里没有样式注入器 —— 消费方只取 entry(漏注入 style)时页面会完全没样式。\n" +
" 检查 vite.config.ts 的 selfInjectStyles() 是否还在 plugins 里。"
);
}
}
}
/* ---------------- external 是否真的生效 ---------------- */
+93 -2
View File
@@ -24,7 +24,7 @@
* 插件体积大一点没关系,宿主不必为了插件把整个组件库挂到全局。
*/
import { defineConfig } from "vite";
import { defineConfig, type Plugin } from "vite";
import vue from "@vitejs/plugin-vue";
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
@@ -63,9 +63,100 @@ const HOST_GLOBALS: Record<string, string> = {
funjiaui: "funjiaui",
};
/* ------------------------------------------------------------------ *
* 让产物「自带样式」
* ------------------------------------------------------------------ */
/** 注入器的哨兵注释:重复构建时先按它把旧的剥掉,避免 watch 下越叠越多 */
const INJECTOR_SENTINEL = "/* funjia:self-inject-styles */";
/**
* 把抽出来的 CSS 内联进 JS,脚本一加载就把样式注入文档。
*
* ## 为什么必须这么做
*
* 仓库契约里 `style` 是**独立字段**:消费方要自己读它、注入 `<link>`。文档写清楚了,
* 官方参考消费方(`repo-consumer.html`)也照做了 —— 但**第三方很容易只取 `entry`**,
* 于是插件能跑、页面却是白板(所有布局都靠 CSS,样式没了等于不可用)。
* 实测过:只用 `entry` 时文档里插件样式表数量是 0,`.pt-panel` 的宽度从 356px
* 变成撑满的 1368px。
*
* 一个「交付物」不该依赖消费方记得做第二步。所以产物自带样式:
*
* - 保留 `style` 字段与那个 CSS 文件**不变** —— 按文档注入的宿主照常工作,
* 也便于审计;CSP 禁止内联样式时,那条路是唯一出路。
* - 同时在 JS 里挂一个注入器兜底。两处都生效时**不会重复注入**:注入器会先看
* 文档里有没有本插件的 `<style data-funjia-plugin=…>`,或有没有 href 指向
* 本样式文件的 `<link>`,有就跳过。
*
* ## 为什么走 generateBundle(而不是写完盘再改文件)
*
* 「写完盘再读改」更简单,但构建日志报的体积会**不含**注入进去的那份 CSS
* (注入发生在 vite 打印体积之后),于是日志 98KB、仓库索引 109KB,
* 对不上账、还得每次解释。走 `generateBundle` 是在产物落盘之前改代码,
* 体积、checksum、日志三者天然一致。
*
* `enforce: "post"` 是必需的:CSS 资源由 Vite 内置的 css-post 插件在
* generateBundle 阶段产生,我们的钩子必须排在它之后才拿得到。
* 万一没拿到,`this.warn` 会在构建日志里**显式报出来** —— 而不是静默少注入一份样式
* (那正是这个函数要解决的问题本身)。
*/
function selfInjectStyles(): Plugin {
const styleFile = cfg.style as string | undefined;
if (!styleFile) return { name: "funjia:self-inject-styles" };
return {
name: "funjia:self-inject-styles",
apply: "build",
enforce: "post",
generateBundle(_options, bundle) {
const cssAsset = Object.values(bundle).find(
(item) => item.type === "asset" && item.fileName === styleFile
);
const entryChunk = Object.values(bundle).find(
(item) => item.type === "chunk" && item.isEntry
);
if (!cssAsset || !entryChunk) {
this.warn(
`自带样式注入被跳过:${!cssAsset ? `产物里没有 ${styleFile}` : "找不到入口 chunk"}。` +
`这通常意味着样式提取插件没跑或产物名对不上 —— ` +
`插件仍可用,但消费方漏注入 style 时页面会没有样式。`
);
return;
}
const css = typeof cssAsset.source === "string" ? cssAsset.source : String(cssAsset.source);
const injector =
`${INJECTOR_SENTINEL}\n` +
`(function(){` +
`var ID=${JSON.stringify(cfg.id)},FILE=${JSON.stringify(styleFile)};` +
// 宿主已经按 manifest.style 注入了 → 不重复注入(省一份 ~10KB 的重复 CSS)
`var links=document.querySelectorAll('link[rel="stylesheet"]');` +
`for(var i=0;i<links.length;i++){` +
`if((links[i].getAttribute("href")||"").indexOf(FILE)!==-1)return;}` +
`if(document.querySelector('style[data-funjia-plugin="'+ID+'"]'))return;` +
`var s=document.createElement("style");` +
`s.setAttribute("data-funjia-plugin",ID);` +
`s.textContent=${JSON.stringify(css)};` +
`(document.head||document.documentElement).appendChild(s);` +
`})();\n`;
// 幂等:watch 模式下同一轮可能重复经过这里,先按哨兵剥掉旧的
let code = entryChunk.code;
if (code.startsWith(INJECTOR_SENTINEL)) {
const end = code.indexOf("\n", code.indexOf("})();"));
code = end >= 0 ? code.slice(end + 1) : code;
}
entryChunk.code = injector + code;
},
};
}
export default defineConfig({
root,
plugins: [vue()],
plugins: [vue(), selfInjectStyles()],
build: {
target: "es2015",
outDir: resolve(root, "dist"),