feat: 新增 plugin/ 插件化形态(funjia.print-tag)+ 可选 SN 条码/二维码

把本工程的标签排版能力改造成 FunjiaUI 远端插件,放进 plugin/ 子目录,
与原独立 Web 版并存(两者功能一致,模板/版面/打印行为逐项对齐)。

- 入口从 createApp().mount() 改为 activate(ctx) + ctx.addRoute,注册 1 菜单 / 1 路由 / 2 命令
- 11 个模板的渲染收敛成 SpecTag,差异集中到 templates/registry.ts(字段/选项/默认值原样保留)
- 店铺名 / 电话从写死改为可配置,记忆在插件私有存储
- 内置二维码图片改为打包 data URL —— 远端插件没有自己的 public/
- 去掉 @headlessui/vue(换原生 select)与 Tailwind,样式类名统一 pt- 前缀避免污染宿主
- 可选接入宿主 api::sn-code:按 SN 生成真 Code 128 条码与可扫二维码;
  关闭时(默认)完全保持原静态二维码行为。领码优先贴到已排版的格子,不够才新建
- 新增 commands: print-tag:issue-sn / print-tag:render-svg(后者纯本地出图,供其它插件复用)
- code128.ts 实现真 Code 128 Set B(含校验位);二维码走 qrcode-generator(真 QR)
- 自带本地预览器(preview/mock-api.ts 补了 /api/sn-codes mock)与 deploy / verify 脚本
- verify.mjs 修掉一处误报:源码边界判据改为「解析后是否逃出工程根」,
  而不是「说明符是否以 .. 开头」(后者会把 src/components/X.vue → ../codes 误判为越界)

已发布到插件仓库:funjia.print-tag@1.0.0
This commit is contained in:
2026-10-03 23:48:32 +08:00
parent 1896d1032b
commit ef41d98838
43 changed files with 8835 additions and 0 deletions
+891
View File
@@ -0,0 +1,891 @@
/**
* 预览用的迷你宿主。
*
* ## 它做什么
*
* 把真实宿主在启动时做的事,在浏览器里搭一份**最小可跑**的版本:
* 扩展点注册表(菜单/路由/命令/事件/视图模型)、`ctx` 工厂、以及
* 「注册即自动回收」的禁用语义。好让插件在**不构建、不发布、不开宿主**
* 的情况下被看见。
*
* ## 它明确不做什么(这段比上面那段重要)
*
* | 缺口 | 后果 / 怎么办 |
* | ---- | ------------- |
* | 没有路由框架 | 预览直接把注册的页面组件渲染出来。真实宿主里的路径规则、权限、嵌套路由验不到 |
* | `funjiaui` 是桩 | 用 `UmTable` 等真实行为要在宿主里看;预览只保证不崩、有占位 |
* | 后端是**内置 mock** | `ctx.http` 真的发请求、真的拿得到数据,但数据是 `preview/mock-api.ts` 里的固定几行,进程重启即重置。接真后端用 `PREVIEW_API_TARGET` 代理过去 |
* | 没有路由守卫 | 预览有登录/登出,但「未登录一律拦到登录页」是**宿主**的行为,预览不拦 —— 插件页面在未登录时照样打得开,只是接口会回 401 |
* | 不做权限判定 | `ctx.getUser()` 拿得到真实角色,但拦不拦由插件自己写。宿主里也一样,只是宿主多了守卫那一层 |
* | 不校验完整性 | 产物模式加载的是本地 `dist/`,不做 checksum 比对 |
*
* 所以请把预览当作**开发时的镜子**,而不是验收环境:
*
* > 预览里看不到的东西 ≠ 宿主里也没问题。
* > 交付前那一次 `deploy` + 宿主安装,仍然要走。
*
* ## 与真实宿主的实现差异(有意为之)
*
* 真实宿主的扩展点注册表在 `src/core/plugin/extensionRegistry.ts`,预览这份是
* **独立实现**,没有 import 宿主的任何模块 —— 插件工程看不到宿主源码,
* 也不该为了预览去依赖它。代价是两边可能慢慢漂移,收益是插件工程零宿主依赖。
* 判断「漂移了没有」的方式很直接:在宿主里装一次,对比行为。
*/
import { markRaw, reactive } from "vue";
import type { PluginCtx, PluginModule } from "../src/sdk";
import { HOST_NAME, HOST_VERSION, hostInfo, pendingRegistrations } from "./contract";
import {
AUTH_EVENTS,
TOKEN_KEY,
UNAUTHORIZED_CODE,
USER_KEY,
type ApiResult,
type AuthUser,
type DemoAccount,
} from "./api-contract";
/** 宿主注入给插件的元数据。真实宿主里来自仓库索引条目 */
export interface PreviewManifest {
id: string;
name: string;
version: string;
kind: string;
activation?: string;
repository?: string;
checksum?: string;
}
export type LogLevel = "debug" | "info" | "warn" | "error" | "ui";
export interface LogItem {
seq: number;
level: LogLevel;
text: string;
time: string;
}
export interface EventItem {
seq: number;
scope: "local" | "global";
name: string;
payload: string;
time: string;
}
export interface CommandResult {
ok: boolean;
value?: any;
error?: string;
ms: number;
}
const MAX_LOG = 400;
/** 屏蔽 Vue 把组件对象变成响应式代理 —— 那会让 Vue 自己发出警告,且渲染行为改变 */
function raw<T>(value: T): T {
return (typeof value === "object" && value !== null) ? markRaw(value as any) : value;
}
export function createPreviewHost(manifest: PreviewManifest) {
/* ------------------------------------------------------------ 状态 */
const state = reactive({
menus: [] as any[],
routes: [] as any[],
widgets: [] as any[],
toolbarActions: [] as any[],
settingsSections: [] as any[],
viewModels: {} as Record<string, any>,
commands: {} as Record<string, any>,
logs: [] as LogItem[],
events: [] as EventItem[],
/** 插件私有存储的镜像(真身在 localStorage,这里只为了界面能显示) */
storage: {} as Record<string, any>,
/** 已注册的事件通道(供界面手动触发) */
channels: [] as { scope: "local" | "global"; name: string }[],
/** idle(未启用)/ active(已启用)/ error(activate 抛错) */
phase: "idle" as "idle" | "active" | "error",
error: "",
activatedAt: "",
/** 上一次 activate 里登记了多少个自动清理项 */
disposerCount: 0,
/** 预览环境的登录态:`null` = 未登录,与宿主 `ctx.getUser()` 同口径 */
user: null as AuthUser | null,
/** 裸令牌(**不带** `Bearer ` 前缀 —— 前缀由请求层统一补,见 authHeaderOf) */
token: "",
/** 上一次鉴权失败的原因。401 时由 send 写入,界面据此给提示 */
authNotice: "",
/**
* 401 计数器。**不能只用 `authNotice` 文本**:
* 界面用 `watch` 监听它来弹登录框,而 watch 只在**值变化**时触发 ——
* 连续两次同样的 401(比如未登录时点了两次「拉列表」)第二次就不会弹框了,
* 表现为「第一次有反应、之后点着没动静」。计数器每次必增,绕开这个坑。
*/
authNoticeSeq: 0,
/** 登录/登出进行中,界面用来禁用按钮 */
authBusy: false,
});
let seq = 0;
const now = () => new Date().toLocaleTimeString("zh-CN", { hour12: false });
function pushLog(level: LogLevel, text: string) {
state.logs.push({ seq: ++seq, level, text, time: now() });
if (state.logs.length > MAX_LOG) state.logs.splice(0, state.logs.length - MAX_LOG);
}
function pushEvent(scope: "local" | "global", name: string, args: any[]) {
// 事件流水单独一个列表:它和日志混在一起会看不清「谁发了什么、谁收到了」
state.events.push({
seq: ++seq,
scope,
name,
payload: args.length ? safeStringify(args.length === 1 ? args[0] : args) : "",
time: now(),
});
if (state.events.length > MAX_LOG) state.events.splice(0, state.events.length - MAX_LOG);
}
function safeStringify(value: any): string {
try {
const s = typeof value === "string" ? value : JSON.stringify(value);
return s === undefined ? String(value) : s;
} catch {
return String(value);
}
}
/* -------------------------------------------------- 插件私有存储 */
// 用 localStorage 而不是内存 Map:刷新页面后插件还能看到自己上次存的东西,
// 这样「install 只跑一次」「bootCount 递增」这类行为才验得出来
const prefix = `funjia-preview:${manifest.id}:`;
function storageKeys(): string[] {
const keys: string[] = [];
for (let i = 0; i < localStorage.length; i++) {
const k = localStorage.key(i);
if (k && k.startsWith(prefix)) keys.push(k.slice(prefix.length));
}
return keys;
}
function syncStorageMirror() {
const dump: Record<string, any> = {};
for (const k of storageKeys()) dump[k] = localStorage.getItem(prefix + k);
state.storage = dump;
}
const storage = {
get<T = any>(key: string, fallback?: T): T {
const raw = localStorage.getItem(prefix + key);
if (raw === null) return fallback as T;
try {
return JSON.parse(raw) as T;
} catch {
return raw as unknown as T;
}
},
set(key: string, value: any) {
localStorage.setItem(prefix + key, JSON.stringify(value));
syncStorageMirror();
},
remove(key: string) {
localStorage.removeItem(prefix + key);
syncStorageMirror();
},
};
function clearStorage() {
for (const k of storageKeys()) localStorage.removeItem(prefix + k);
syncStorageMirror();
}
/* -------------------------------------------------------- 事件总线 */
/**
* 局部 / 全局两个通道分成两个 Map,而不是「一个带前缀的复合 key」。
*
* 复合 key 看着省事,但读回来要靠 `split` 的位置约定 —— 写错不会报错,
* 只会让「已注册通道」列表显示成别的字段(第一版就踩了这个:通道名
* 解析成了插件 id,于是界面上出现一个 `:acme.hello` 这样的鬼东西)。
* 分成两个 Map,结构上就不可能串。
*/
const localListeners = new Map<string, Set<(...args: any[]) => void>>();
const globalListeners = new Map<string, Set<(...args: any[]) => void>>();
const bucketOf = (scope: "local" | "global") =>
scope === "global" ? globalListeners : localListeners;
function syncChannels() {
const out: { scope: "local" | "global"; name: string }[] = [];
for (const name of localListeners.keys()) out.push({ scope: "local", name });
for (const name of globalListeners.keys()) out.push({ scope: "global", name });
state.channels = out;
}
function on(scope: "local" | "global", name: string, handler: (...args: any[]) => void) {
const bucket = bucketOf(scope);
if (!bucket.has(name)) bucket.set(name, new Set());
bucket.get(name)!.add(handler);
syncChannels();
return () => {
bucket.get(name)?.delete(handler);
syncChannels();
};
}
function emit(scope: "local" | "global", name: string, args: any[]) {
pushEvent(scope, name, args);
const set = bucketOf(scope).get(name);
if (!set || set.size === 0) {
pushLog("debug", `emit ${scope === "global" ? "全局" : "局部"}事件 ${name} —— 当前没有监听者`);
return;
}
for (const handler of [...set]) {
try {
handler(...args);
} catch (e) {
// 一个监听器抛错不该带崩整条总线 —— 真实宿主也是逐个隔离的
pushLog("error", `事件监听器抛错(${name}):${(e as Error)?.message ?? e}`);
}
}
}
/* -------------------------------------------------- 回收与注册表 */
const disposers: Array<() => void> = [];
function track(dispose: () => void) {
disposers.push(dispose);
return dispose;
}
function runDisposers() {
// 倒序执行:后注册的先撤,与「栈」的直觉一致
for (const fn of disposers.splice(0).reverse()) {
try {
fn();
} catch (e) {
pushLog("warn", `自动清理项抛错:${(e as Error)?.message ?? e}`);
}
}
}
/** 清空注册表。真实宿主在禁用时做的正是这件事 —— 所以插件不需要写反注册 */
function clearRegistry() {
state.menus = [];
state.routes = [];
state.widgets = [];
state.toolbarActions = [];
state.settingsSections = [];
state.viewModels = {};
state.commands = {};
localListeners.clear();
globalListeners.clear();
state.channels = [];
}
/** 从数组里摘掉一个元素,并返回「摘掉」这个动作 —— 这就是注册返回的 disposer */
function register<T>(list: T[], item: T): () => void {
list.push(raw(item));
return () => {
const i = list.indexOf(item);
if (i >= 0) list.splice(i, 1);
};
}
/* ------------------------------------------------------------ 登录态 */
/**
* 令牌与用户信息的读写集中在这几个小函数里,别处**不再直接碰 localStorage**。
*
* 宿主里对应的是 `src/core/auth/token.ts`。之所以要收敛:老版本把令牌的存取
* 散在三处(会话层读写、请求层 `getItem`、清空时各自 `removeItem`),
* 任何一处改了 key 都会出现「登录明明成功、请求却不带令牌」——
* 只在运行时暴露,且一定会被误判成后端问题。
*/
function readStoredToken(): string {
try {
return localStorage.getItem(TOKEN_KEY) || "";
} catch {
// 隐私模式读不到就当匿名,别让一个存储异常把启动带崩
return "";
}
}
function readStoredUser(): AuthUser | null {
try {
const raw = localStorage.getItem(USER_KEY);
return raw ? (JSON.parse(raw) as AuthUser) : null;
} catch {
return null;
}
}
function saveAuth(token: string, user: AuthUser | null) {
state.token = token;
state.user = user ? raw(user) : null;
try {
localStorage.setItem(TOKEN_KEY, token);
if (user) localStorage.setItem(USER_KEY, JSON.stringify(user));
else localStorage.removeItem(USER_KEY);
} catch {
// 存不下(隐私模式 / 配额满)不影响当前会话,只是刷新后要重新登录
}
}
function clearAuth() {
state.token = "";
state.user = null;
try {
localStorage.removeItem(TOKEN_KEY);
localStorage.removeItem(USER_KEY);
} catch {
/* 同上:清不掉也不该抛 */
}
}
/**
* `Authorization` 头的值。未登录返回**空串** → 请求头里干脆不带这个字段。
*
* 前缀只在这里补一次。localStorage 里存的是**裸令牌** —— 想验证这条约定
* 有没有被破坏,看 `mock-api.ts`:它按真后端的严格程度校验那个头,
* 少一个 `Bearer ` 就当未授权。
*/
const authHeaderOf = () => (state.token ? `Bearer ${state.token}` : "");
/**
* 广播登录态。**事件名与宿主完全一致**(`src/core/session.ts` 的 `globalBus`),
* 所以插件里那句 `ctx.event.onGlobal("user:logout", ...)` 在预览里同样接到东西。
*/
function broadcastAuth(name: string, payload?: any) {
emit("global", name, payload === undefined ? [] : [payload]);
}
/**
* 未授权的统一处理:清会话(如果有)+ 提示 + 广播。
*
* **清会话这一步必须幂等**:一个页面并发五个请求时,401 会连着来五次。
* 判据是「当前会话是否已经空了」—— 与宿主 session 侧同构。
*
* ## 与宿主**有意不同**的一处
*
* 宿主靠**路由守卫**保证「未登录根本进不来任何页面」,所以它只在
* 「原本有会话、现在失效了」时才提示。预览没有守卫:一个未登录的插件页面
* 照样打得开,这时如果 401 一声不吭,作者看到的是「点了按钮没反应」,
* 而真正的原因在浏览器网络面板里(一个 401)—— 这属于最难查的一类问题。
*
* 所以预览里**一律**把登录框弹出来,并在文案上区分两种情况。
*/
function handleUnauthorized(reason: string) {
const hadSession = !!(state.token || state.user);
if (hadSession) {
clearAuth();
broadcastAuth(AUTH_EVENTS.logout);
}
state.authNotice = hadSession
? reason || "登录状态已失效,请重新登录"
: `接口需要登录(${reason || "未登录"})—— 登录后重试`;
state.authNoticeSeq += 1;
pushLog(
"warn",
hadSession
? `接口返回 401(${state.authNotice})→ 已清除预览环境的登录态`
: `接口返回 401:${state.authNotice}`
);
}
/**
* 启动恢复:刷新页面后把登录态接回来。
*
* ⚠️ **必须在插件装载之前完成** —— 插件 `activate` 里的 `ctx.getUser()`
* 会据此判断「有没有人登录」。宿主里这个顺序更严格(还要早于路由守卫),
* 预览里没有路由,只剩这一条约束。见 `App.vue` 的 `onMounted`。
*
* 三个取舍都与宿主一致:
* - **没有令牌就立即返回,不发请求** —— 未登录的首屏不该为一次必然 401 的往返付延迟;
* - 有令牌却没有用户信息 → 本地数据不一致,**丢掉重来**;
* - **后端不可达时保留登录态** —— 网络抖动不该把用户清下线。
*/
async function restoreSession() {
const token = readStoredToken();
if (!token) {
clearAuth();
return;
}
const cached = readStoredUser();
if (!cached) {
clearAuth();
pushLog("warn", "启动恢复:本地有令牌但没有用户信息(数据不一致),已清除");
return;
}
state.token = token;
state.user = raw(cached);
let result: ApiResult<AuthUser>;
try {
result = await send("GET", "/api/auth/me", undefined);
} catch (e) {
// 网络层失败:保留本地登录态(与宿主 bootstrapSession 的 catch 分支同口径)
pushLog("warn", `启动恢复:后端不可达,沿用本地登录态(${(e as Error)?.message ?? e})`);
return;
}
if (result.code === UNAUTHORIZED_CODE) {
// 401 已经由 send → handleUnauthorized 处理(清态 + 提示 + 广播),这里不重复
return;
}
if (result.code !== 0 || !result.data) {
clearAuth();
pushLog("warn", `启动恢复失败(${result.msg}),已清除本地登录态`);
return;
}
// 用服务端的权威信息覆盖本地缓存:名字、角色可能已被改过
saveAuth(token, result.data);
pushLog("info", `启动恢复:已登录为 ${state.user?.name}(${state.user?.role})`);
}
/**
* 登录。业务失败(账号密码不对)**不抛错**,返回 `{ ok: false, message }` ——
* 与宿主 `session.login()` 的返回形状一致,登录页两边都能直接用。
*/
async function login(account: string, password: string): Promise<{ ok: boolean; message?: string }> {
if (state.authBusy) return { ok: false, message: "正在处理上一个请求,请稍候" };
state.authBusy = true;
state.authNotice = "";
const hadUser = !!state.user;
try {
const result = await send("POST", "/api/auth/login", { account, password });
if (result.code !== 0 || !result.data?.token) {
// 刻意不区分「账号不存在」与「密码错误」:与后端、宿主同口径,避免账号枚举
return { ok: false, message: result.msg || "登录失败" };
}
const user = result.data.user as AuthUser;
saveAuth(result.data.token, user);
pushLog("info", `已登录:${user?.name ?? account}(${user?.role ?? ""})`);
// 只在「从无到有」时广播:恢复会话会用服务端信息覆盖一次,那不算新登录
if (!hadUser && user) broadcastAuth(AUTH_EVENTS.login, user);
return { ok: true };
} catch (e) {
return { ok: false, message: `网络异常:${(e as Error)?.message ?? e}` };
} finally {
state.authBusy = false;
}
}
/**
* 登出。
*
* 通知后端是**尽力而为**:令牌已过期时这个请求本身就是必然 401,
* 但本地**必须**清干净 —— 否则用户会卡在「点了退出还是登录态」里,
* 只能手动清 localStorage。这里用 try/catch 而不是让 401 抛出来打断清理。
*/
async function logout() {
if (state.authBusy) return;
state.authBusy = true;
try {
await send("POST", "/api/auth/logout", {});
} catch {
// 后端不通不影响登出:本地清掉就等于登出了
} finally {
clearAuth();
state.authNotice = "";
state.authBusy = false;
// 广播放最后:监听者拿到事件时,登录态已经是干净的了
broadcastAuth(AUTH_EVENTS.logout);
pushLog("info", "已退出登录:本地令牌与用户信息已清空");
}
}
/**
* 演示账号清单(登录页直接列出来,省掉「翻文档找账号」这一步)。
*
* 走接口而不是写死在界面里是有意的:**真后端不会实现这个接口**,
* 那时这里返回空数组,登录页自动把整块收起来 ——
* 界面不需要知道「当前连的是 mock 还是真后端」。
*
* 用 `rawRequest` 而不是 `send`:这是一次探针调用,
* 失败是正常情况,不该在日志里刷一条 404 警告,也不该触发 401 处理。
*/
async function demoAccounts(): Promise<DemoAccount[]> {
try {
const result = await rawRequest<DemoAccount[]>("GET", "/api/auth/demo-accounts", undefined);
return result.code === 0 && Array.isArray(result.data) ? result.data : [];
} catch {
// 真后端没有这个接口 → 静默留空
return [];
}
}
/* --------------------------------------------------------- ctx 请求层 */
/**
* 请求层错误(**基础设施**故障,不是业务码)。
*
* 与宿主的 `HttpError` 同形:业务码非 0 **不抛错**(老系统的写法是
* `const {code,msg} = await api.add()`,抛错会让那套写法全部失效),
* 只有连不上、网关 5xx、响应不是 JSON 这类才抛。
*/
class PreviewHttpError extends Error {
constructor(public readonly status: number, message: string, public readonly url: string) {
super(message);
this.name = "PreviewHttpError";
}
}
/** 把参数对象拼成查询串,跳过空值(与宿主 `toQuery` 同规则) */
function toQuery(params?: Record<string, any>): string {
if (!params) return "";
const parts: string[] = [];
for (const [key, value] of Object.entries(params)) {
if (value === undefined || value === null || value === "") continue;
parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
}
return parts.length ? `?${parts.join("&")}` : "";
}
/**
* 发一个请求(不含 401 处理,见 `send`)。
*
* ## 与宿主 `src/core/http/index.ts` 的 `realRequest` 对齐
*
* | 情况 | 这里 | 宿主 |
* | ---- | ---- | ---- |
* | HTTP 401 | 归一成 `{code: 401}`,**不抛** | 同 |
* | 其它非 2xx | **抛** `PreviewHttpError` | 抛 `HttpError` |
* | 响应是包络 | 原样返回 | 同 |
* | 响应是裸数据 | 补成 `{code: 0, data}` | 同 |
*
* 老版本的预览桩子在这三处都不一样:HTTP 状态码直接当业务码、
* 把整个包络塞进 `data`(于是插件拿到的 `res.data.rows` 永远是 `undefined`)、
* 出错一律返回 `code: -1` 从不抛。结果是**预览里过得去的代码,到宿主里全是坑** ——
* 这里刻意改成同构。
*/
async function rawRequest<T = any>(method: string, url: string, payload: any): Promise<ApiResult<T>> {
const verb = (method || "GET").toUpperCase();
const finalUrl = verb === "GET" || verb === "DELETE" ? `${url}${toQuery(payload)}` : url;
const headers: Record<string, string> = {
"Content-Type": "application/json;charset=utf-8",
"Cache-Control": "no-cache",
};
// 未登录时**不带** Authorization 字段,而不是带一个空值 ——
// 某些网关对空的 `Authorization: ` 会直接拒请求(而不是当匿名)
const authorization = authHeaderOf();
if (authorization) headers.Authorization = authorization;
const res = await fetch(finalUrl, {
method: verb,
headers,
body: verb === "GET" || verb === "DELETE" ? undefined : JSON.stringify(payload ?? {}),
});
if (res.status === 401) {
return { code: UNAUTHORIZED_CODE, msg: "未登录或登录已过期", data: null as unknown as T };
}
if (!res.ok) {
throw new PreviewHttpError(res.status, `请求失败 ${res.status}:${url}`, url);
}
const text = await res.text();
let parsed: any = null;
try {
parsed = text ? JSON.parse(text) : null;
} catch {
throw new PreviewHttpError(res.status, `响应不是合法 JSON:${url}`, url);
}
// 真后端可能只返回裸数据(没有 code 包装),这里补齐成统一形状
if (parsed && typeof parsed === "object" && "code" in parsed) return parsed as ApiResult<T>;
return { code: 0, msg: "ok", data: parsed as T };
}
/**
* `ctx.http` 的入口:请求 + 统一的 401 处理。
*
* 401 是**唯一有副作用**的一种返回:清会话、提示、广播登出。
* **插件不需要为它写任何代码** —— 拿到 401 直接 return 即可,与宿主一致。
*/
async function send<T = any>(method: string, url: string, payload?: any): Promise<ApiResult<T>> {
const label = `http.${method.toLowerCase()}(${url})`;
try {
const result = await rawRequest<T>(method, url, payload);
if (result.code === UNAUTHORIZED_CODE) {
pushLog("warn", `${label} → 401`);
handleUnauthorized(result.msg);
} else {
pushLog("info", `${label} → code ${result.code}${result.code === 0 ? "(ok)" : `(${result.msg})`}`);
}
return result;
} catch (e) {
const err = e as PreviewHttpError;
pushLog("error", `${label} 失败:${err?.message ?? err}`);
throw e;
}
}
/** `ctx.http` 的四个方法。`payload` 对 GET/DELETE 是查询参数,对其它是请求体 */
const httpCall = (method: string, url: string, payload?: any) => send(method, url, payload);
/* ---------------------------------------------------------------- ctx */
function createCtx(): PluginCtx {
const ctx: PluginCtx = {
hostVersion: HOST_VERSION,
plugin: {
id: manifest.id,
name: manifest.name,
version: manifest.version,
kind: manifest.kind,
repository: manifest.repository,
checksum: manifest.checksum,
},
logger: {
debug: (...a: any[]) => pushLog("debug", a.map(safeStringify).join(" ")),
info: (...a: any[]) => pushLog("info", a.map(safeStringify).join(" ")),
warn: (...a: any[]) => pushLog("warn", a.map(safeStringify).join(" ")),
error: (...a: any[]) => pushLog("error", a.map(safeStringify).join(" ")),
},
storage,
http: {
// 与宿主 `PluginHttp` 同形:多一个 request(),给「method 是算出来的」场景用
request: (options: any) => {
const method = String(options?.method || "GET").toUpperCase();
const payload = method === "GET" || method === "DELETE" ? options?.params : options?.data;
return httpCall(method, options?.url, payload);
},
get: (url, params) => httpCall("GET", url, params),
post: (url, data) => httpCall("POST", url, data),
put: (url, data) => httpCall("PUT", url, data),
del: (url, params) => httpCall("DELETE", url, params),
},
ui: {
success: (m: string) => pushLog("ui", `success: ${m}`),
error: (m: string) => pushLog("ui", `error: ${m}`),
warning: (m: string) => pushLog("ui", `warning: ${m}`),
info: (m: string) => pushLog("ui", `info: ${m}`),
// 用浏览器原生弹窗:够真(会阻塞),也不必为此引入一套消息组件
confirm: async (m: string, title = "确认") => window.confirm(`${title}\n\n${m}`),
alert: async (m: string, title = "提示") => {
window.alert(`${title}\n\n${m}`);
},
},
/**
* 当前登录用户。**与宿主同口径**:直接返回会话里的那个用户对象,
* 未登录返回 `null`(而不是一个假的「预览用户」)——
* 插件据此做角色降级,预览里才能真的验到「普通用户看不到某个按钮」。
*
* 返回展开后的副本而不是原对象:调用方顺手改一下不该影响会话。
*/
getUser: () => (state.user ? { ...state.user } : null),
addMenu: (menu) => track(register(state.menus, menu)),
addRoute: (route) => track(register(state.routes, route)),
addWidget: (w) => track(register(state.widgets, w)),
addToolbarAction: (a) => track(register(state.toolbarActions, a)),
addSettingsSection: (s) => track(register(state.settingsSections, s)),
addViewModel: (model) => {
state.viewModels[model.name] = raw(model.target);
return track(() => {
delete state.viewModels[model.name];
});
},
getViewModel: (name) => state.viewModels[name],
addCommand: (command) => {
state.commands[command.name] = raw(command);
return track(() => {
delete state.commands[command.name];
});
},
getCommand: (name) => state.commands[name],
event: {
on: (name, handler) => track(on("local", name, handler)),
emit: (name, ...args) => emit("local", name, args),
onGlobal: (name, handler) => track(on("global", name, handler)),
emitGlobal: (name, ...args) => emit("global", name, args),
},
onDispose: (fn) => track(fn),
};
return ctx;
}
/* -------------------------------------------------------- 生命周期 */
/** 认领自注册队列里属于本插件的模块(真实宿主按 manifest.id 认领,这里同样) */
function claim(): PluginModule | null {
const i = pendingRegistrations.findIndex((r) => r?.manifest?.id === manifest.id);
if (i < 0) return null;
return pendingRegistrations.splice(i, 1)[0].module as PluginModule;
}
/** 探测自注册队列里都有谁 —— 认领失败时用来给出可执行的提示 */
function pendingIds(): string[] {
return pendingRegistrations.map((r) => String(r?.manifest?.id ?? "(无 id)"));
}
const installedFlag = `funjia-preview:meta:${manifest.id}:installed`;
let currentCtx: PluginCtx | null = null;
async function activate(module: PluginModule) {
// 重新启用前先清干净:真实宿主在禁用时已经回收过,这里保证同一语义
runDisposers();
clearRegistry();
const ctx = createCtx();
currentCtx = ctx;
state.error = "";
try {
// install 一辈子只跑一次 —— 用持久化标记模拟「首次装载」,与真实宿主同口径
if (localStorage.getItem(installedFlag) !== "1") {
await module.install?.(ctx);
localStorage.setItem(installedFlag, "1");
pushLog("info", "install 已执行(首次装载,标记已持久化:刷新或重新启用都不会再跑)");
}
await module.activate?.(ctx);
state.phase = "active";
state.activatedAt = now();
state.disposerCount = disposers.length;
pushLog(
"info",
`activate 完成:注册 ${state.menus.length} 菜单 / ${state.routes.length} 路由 / ` +
`${Object.keys(state.commands).length} 命令 / ${state.channels.length} 事件通道,` +
`${disposers.length} 个待回收项`
);
} catch (e) {
state.phase = "error";
state.error = String((e as Error)?.message ?? e);
pushLog("error", `activate 抛错:${state.error}`);
throw e;
}
}
async function deactivate(module?: PluginModule | null) {
if (module) {
try {
await module.deactivate?.(currentCtx as PluginCtx);
} catch (e) {
pushLog("error", `deactivate 抛错:${(e as Error)?.message ?? e}`);
}
}
runDisposers();
clearRegistry();
state.disposerCount = 0;
state.activatedAt = "";
state.phase = "idle";
pushLog("info", "已停用:菜单/路由/命令/事件监听全部回收(真实宿主在同一时机做同样的事)");
}
async function uninstall(module?: PluginModule | null) {
await deactivate(module);
if (module) {
try {
await module.uninstall?.(currentCtx as PluginCtx);
} catch (e) {
pushLog("error", `uninstall 抛错:${(e as Error)?.message ?? e}`);
}
}
clearStorage();
localStorage.removeItem(installedFlag);
pushLog("info", "已卸载:插件私有存储与 install 标记已清空(下次启用会重新走 install)");
}
/* ------------------------------------------------ 供预览界面调用 */
async function callCommand(name: string, args: any[]): Promise<CommandResult> {
const started = performance.now();
const command = state.commands[name];
if (!command) {
const ms = performance.now() - started;
pushLog("warn", `调用命令 ${name} 失败:未注册`);
return { ok: false, error: `命令 ${name} 未注册`, ms };
}
try {
const value = await command.handler(...args);
const ms = performance.now() - started;
pushLog("info", `调用命令 ${name} → ${safeStringify(value)}(${ms.toFixed(1)}ms)`);
return { ok: true, value, ms };
} catch (e) {
const ms = performance.now() - started;
const error = String((e as Error)?.message ?? e);
pushLog("error", `调用命令 ${name} 抛错:${error}`);
return { ok: false, error, ms };
}
}
function invokeLocal(name: string, args: any[]) {
emit("local", name, args);
}
function invokeGlobal(name: string, args: any[]) {
emit("global", name, args);
}
/* ---------------------------------------------- 补全 window.FunjiaHost */
// hostInfo 是 contract.ts 里那个**同一个对象引用**。这里只补字段,
// 不换对象 —— 插件若在模块求值时就把 window.FunjiaHost 存起来了,也能看到这些实现
Object.assign(hostInfo, {
name: HOST_NAME,
version: HOST_VERSION,
http: {
get: (url: string, params?: any) => httpCall("GET", url, params),
post: (url: string, data?: any) => httpCall("POST", url, data),
put: (url: string, data?: any) => httpCall("PUT", url, data),
del: (url: string, params?: any) => httpCall("DELETE", url, params),
},
getViewModel: (name: string) => state.viewModels[name],
// 与宿主 `FunjiaHost.getUser/isLoggedIn` 同名同义。给**没有 ctx** 的
// 裸脚本插件用(例如纯配置类插件),它们在预览里也要能判断登录态
getUser: () => (state.user ? { ...state.user } : null),
isLoggedIn: () => !!state.user,
stats: () => ({
menus: state.menus.length,
routes: state.routes.length,
widgets: state.widgets.length,
toolbarActions: state.toolbarActions.length,
settingsSections: state.settingsSections.length,
viewModels: Object.keys(state.viewModels).length,
commands: Object.keys(state.commands).length,
}),
});
return {
manifest,
state,
pushLog,
claim,
pendingIds,
activate,
deactivate,
uninstall,
callCommand,
invokeLocal,
invokeGlobal,
/* 登录态:预览界面用它渲染顶栏的登录区,插件页面靠 `ctx.getUser()` 读 */
login,
logout,
restoreSession,
demoAccounts,
clearLogs: () => {
state.logs = [];
state.events = [];
},
clearStorage,
syncStorageMirror,
};
}
export type PreviewHost = ReturnType<typeof createPreviewHost>;