Files
funjia ef41d98838 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
2026-10-03 23:48:32 +08:00

892 lines
34 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 预览用的迷你宿主。
*
* ## 它做什么
*
* 把真实宿主在启动时做的事,在浏览器里搭一份**最小可跑**的版本:
* 扩展点注册表(菜单/路由/命令/事件/视图模型)、`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>;