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
+689
View File
@@ -0,0 +1,689 @@
<template>
<div class="pv">
<!-- ------------------------------------------------------ 顶栏 -->
<header class="pv-top">
<div class="pv-top__line">
<h1 class="pv-top__name">{{ config.name }}</h1>
<code class="pv-top__id">{{ config.id }}</code>
<el-tag size="small" :type="loader.mode === 'source' ? 'success' : 'warning'" effect="dark">
{{ loader.label }}模式
</el-tag>
<el-tag size="small" :type="phaseType">{{ phaseText }}</el-tag>
<span v-if="state.activatedAt" class="pv-top__time">启用时间 {{ state.activatedAt }}</span>
</div>
<div class="pv-top__line pv-top__meta">
<span>v{{ config.version }}</span>
<span>形态 {{ config.kind }}</span>
<span>activation {{ config.activation ?? "未声明" }}</span>
<span v-if="config.globalKey">globalKey {{ config.globalKey }}</span>
<span v-if="config.style">style {{ config.style }}</span>
<span class="pv-top__warn">repository 字段为空(预览等同于「手工填 URL 安装」)</span>
</div>
<div class="pv-top__line pv-top__ops">
<el-button v-if="isIdle" type="primary" size="small" :loading="busy" @click="start">
装载并启用
</el-button>
<template v-else>
<el-button size="small" :loading="busy" @click="stop">停用</el-button>
<el-button size="small" :loading="busy" @click="rerun">重新装载</el-button>
<el-button size="small" type="danger" plain @click="remove">卸载</el-button>
</template>
<!--
登录区。这里显示的是**真实**登录态(令牌来自 `/api/auth/login`,
请求时由请求层自动带上),不再是早前那个「模拟已登录」开关 ——
开关是个谎话:它让插件以为自己拿到了用户,而接口根本没带令牌。
-->
<div class="pv-auth">
<template v-if="state.user">
<el-tag size="small" type="success" effect="plain">
{{ state.user.name }} · {{ state.user.role }}
</el-tag>
<el-button size="small" :loading="state.authBusy" @click="onLogout">退出登录</el-button>
</template>
<template v-else>
<el-tag size="small" type="info" effect="plain">未登录</el-tag>
<el-button size="small" type="primary" plain @click="openLogin">登录</el-button>
</template>
</div>
</div>
</header>
<p class="pv-hint">{{ loader.hint }}</p>
<!-- 令牌失效:任何一次接口调用拿到 401 都会走到这里(宿主里对应「跳登录页」) -->
<el-alert
v-if="state.authNotice && !state.user"
type="warning"
:closable="false"
show-icon
:title="`登录态已失效:${state.authNotice}`"
class="pv-alert"
/>
<el-alert v-if="error" type="error" :closable="false" show-icon :title="error" class="pv-alert" />
<el-alert
v-for="w in warnings"
:key="w"
type="warning"
:closable="false"
show-icon
:title="w"
class="pv-alert"
/>
<!-- -------------------------------------------- 菜单 + 页面 + 命令 -->
<div class="pv-body">
<aside class="pv-side">
<section>
<h3>侧边菜单 <em>{{ state.menus.length }}</em></h3>
<ul class="pv-list">
<li
v-for="m in state.menus"
:key="m.id"
:class="{ 'is-active': isCurrent(m.path) }"
@click="pick(m.path)"
>
<span class="pv-list__title">{{ m.title }}</span>
<code>{{ m.path || "(无路径)" }}</code>
</li>
<li v-if="!state.menus.length" class="pv-list__empty">activate 里没有注册菜单</li>
</ul>
</section>
<section>
<h3>路由 <em>{{ state.routes.length }}</em></h3>
<ul class="pv-list">
<li
v-for="r in state.routes"
:key="r.name"
:class="{ 'is-active': isCurrent(r.path) }"
@click="pick(r.path)"
>
<span class="pv-list__title">{{ r.name }}</span>
<code>{{ r.path }}</code>
</li>
<li v-if="!state.routes.length" class="pv-list__empty">activate 里没有注册路由</li>
</ul>
</section>
</aside>
<main class="pv-main">
<section class="pv-stage">
<div class="pv-bar">
<span class="pv-bar__label">页面区</span>
<code v-if="selectedRoute">{{ selectedRoute.path }}</code>
<span v-else class="pv-muted">(未选中路由)</span>
</div>
<div class="pv-stage__body">
<component v-if="selectedRoute" :is="selectedRoute.component" />
<div v-else class="pv-empty">
<p>没有可渲染的页面。</p>
<p>
插件用 <code>ctx.addRoute({ path, component })</code> 注册页面,注册完这里就会显示。
</p>
</div>
</div>
</section>
<section class="pv-stage pv-stage--cmd">
<div class="pv-bar">
<span class="pv-bar__label">命令台</span>
<span class="pv-muted">命令是跨插件协作的正规通道 —— 在这里直接调它,看返回值</span>
</div>
<div class="pv-cmd__form">
<el-select
v-model="cmdName"
size="small"
placeholder="选一个命令"
:disabled="!commandNames.length"
style="width: 200px"
>
<el-option v-for="n in commandNames" :key="n" :label="n" :value="n" />
</el-select>
<el-input
v-model="cmdArgs"
size="small"
placeholder='参数(JSON 数组),如 ["世界"]'
style="width: 260px"
/>
<el-button size="small" type="primary" :disabled="!cmdName" @click="runCommand">执行</el-button>
<span v-if="!commandNames.length" class="pv-muted">当前没有注册命令</span>
</div>
<pre v-if="cmdResult" class="pv-cmd__result" :class="{ 'is-error': !cmdResult.ok }">{{
cmdResult.ok ? format(cmdResult.value) : cmdResult.error
}}</pre>
<div v-if="cmdResult" class="pv-cmd__ms">耗时 {{ cmdResult.ms.toFixed(1) }} ms</div>
</section>
</main>
</div>
<!-- --------------------------------------------------- 底部面板 -->
<el-tabs v-model="bottomTab" class="pv-bottom">
<el-tab-pane name="log">
<template #label>日志<em v-if="state.logs.length"> {{ state.logs.length }}</em></template>
<div class="pv-bar">
<span class="pv-muted">logger 与 ui.* 的输出都落在这里(真实宿主里进浏览器控制台)</span>
<el-button size="small" type="text" @click="host.clearLogs()">清空</el-button>
</div>
<div ref="logBox" class="pv-lines">
<div v-for="l in state.logs" :key="l.seq" class="pv-line" :class="'is-' + l.level">
<span class="pv-line__time">{{ l.time }}</span>
<span class="pv-line__tag">{{ l.level }}</span>
<span class="pv-line__text">{{ l.text }}</span>
</div>
<div v-if="!state.logs.length" class="pv-line__empty">(暂无输出 —— 点上面的「装载并启用」)</div>
</div>
</el-tab-pane>
<el-tab-pane name="event">
<template #label>事件<em v-if="state.events.length"> {{ state.events.length }}</em></template>
<div class="pv-cmd__form">
<el-select
v-model="evChannel"
size="small"
placeholder="选一个通道"
:disabled="!channelOptions.length"
style="width: 230px"
>
<el-option v-for="c in channelOptions" :key="c.value" :label="c.label" :value="c.value" />
</el-select>
<el-input v-model="evArgs" size="small" placeholder="参数(JSON),如 [{ &quot;a&quot;: 1 }]" style="width: 230px" />
<el-button size="small" :disabled="!evChannel" @click="fireEvent">手动触发</el-button>
<span class="pv-muted">局部通道的事件名在宿主里会自动加插件前缀,所以不必担心重名</span>
</div>
<div class="pv-lines">
<div v-for="e in state.events" :key="e.seq" class="pv-line is-event">
<span class="pv-line__time">{{ e.time }}</span>
<span class="pv-line__tag">{{ e.scope === "global" ? "全局" : "局部" }}</span>
<span class="pv-line__text"><code>{{ e.name }}</code><template v-if="e.payload"> {{ e.payload }}</template></span>
</div>
<div v-if="!state.events.length" class="pv-line__empty">(暂无事件流水)</div>
</div>
</el-tab-pane>
<el-tab-pane name="ext">
<template #label>扩展点</template>
<div class="pv-ext">
<div class="pv-ext__col">
<h4>仪表盘卡片 <em>{{ state.widgets.length }}</em></h4>
<ul>
<li v-for="w in state.widgets" :key="w.id">{{ w.id }} · span={{ w.span ?? "默认" }}</li>
<li v-if="!state.widgets.length" class="pv-list__empty">无</li>
</ul>
<h4>顶栏动作 <em>{{ state.toolbarActions.length }}</em></h4>
<ul>
<li v-for="a in state.toolbarActions" :key="a.id">{{ a.title }}({{ a.id }})</li>
<li v-if="!state.toolbarActions.length" class="pv-list__empty">无</li>
</ul>
<h4>设置区块 <em>{{ state.settingsSections.length }}</em></h4>
<ul>
<li v-for="s in state.settingsSections" :key="s.id">{{ s.title }}</li>
<li v-if="!state.settingsSections.length" class="pv-list__empty">无</li>
</ul>
</div>
<div class="pv-ext__col">
<h4>视图模型 / 配置类 <em>{{ Object.keys(state.viewModels).length }}</em></h4>
<ul>
<li v-for="(_, name) in state.viewModels" :key="name">{{ name }}</li>
<li v-if="!Object.keys(state.viewModels).length" class="pv-list__empty">无</li>
</ul>
<h4>命令 <em>{{ commandNames.length }}</em></h4>
<ul>
<li v-for="n in commandNames" :key="n">{{ n }} · {{ state.commands[n].description || "无说明" }}</li>
<li v-if="!commandNames.length" class="pv-list__empty">无</li>
</ul>
<h4>待回收项 <em>{{ state.disposerCount }}</em></h4>
<p class="pv-note">
停用时宿主会一次性回收这些注册(连同 <code>ctx.onDispose()</code> 登记的自清理函数)。
停用后回到本页看,菜单和路由应当<strong>全部消失</strong>。
</p>
</div>
</div>
</el-tab-pane>
<el-tab-pane name="storage">
<template #label>私有存储<em v-if="Object.keys(state.storage).length"> {{ Object.keys(state.storage).length }}</em></template>
<div class="pv-bar">
<span class="pv-muted">
<code>ctx.storage</code> 的实时内容(真实宿主落在浏览器存储里,按插件 id 隔离,卸载时清空)
</span>
<span>
<el-button size="small" type="text" @click="host.syncStorageMirror()">刷新</el-button>
<el-button size="small" type="text" @click="host.clearStorage()">清空</el-button>
</span>
</div>
<div class="pv-kv">
<div v-for="(v, k) in state.storage" :key="k" class="pv-kv__row">
<code>{{ k }}</code><span>{{ v }}</span>
</div>
<div v-if="!Object.keys(state.storage).length" class="pv-line__empty">
(空 —— 插件还没往 storage 里写过东西)
</div>
</div>
</el-tab-pane>
</el-tabs>
<!--
登录框。对应宿主里的登录页(`src/views/LoginView.vue`)——
预览没有路由与守卫,所以「未登录」的表现就是一个可以随时关掉的弹窗,
而不是「整站被拦到登录页」。接口该回 401 的照样回 401。
-->
<el-dialog v-model="loginVisible" title="登录预览后端" width="380px" append-to-body>
<p class="pv-login__tip">
预览的 <code>/api</code> 来自内置的最小后端 <code>preview/mock-api.ts</code>
(响应契约与宿主一致)。登录后,插件里每一次
<code>ctx.http</code> 请求都会自动带上 <code>Authorization</code> 头。
</p>
<el-form label-width="52px" @submit.prevent>
<el-form-item label="账号">
<el-input v-model="loginForm.account" placeholder="funjia" @keyup.enter="submitLogin" />
</el-form-item>
<el-form-item label="密码">
<el-input
v-model="loginForm.password"
type="password"
show-password
placeholder="funjia123"
@keyup.enter="submitLogin"
/>
</el-form-item>
</el-form>
<el-alert v-if="dialogMessage" type="error" :closable="false" show-icon :title="dialogMessage" />
<div v-if="demos.length" class="pv-login__demos">
<span class="pv-muted">演示账号(点一下填入):</span>
<el-tag
v-for="d in demos"
:key="d.account"
size="small"
class="pv-login__demo"
@click="fillDemo(d)"
>
{{ d.account }} / {{ d.password }}({{ d.role }})
</el-tag>
</div>
<p v-else class="pv-login__tip pv-muted">
当前后端没有提供演示账号接口(真后端不会有)——手工填账号密码即可。
</p>
<template #footer>
<el-button size="small" @click="loginVisible = false">取消</el-button>
<el-button size="small" type="primary" :loading="state.authBusy" @click="submitLogin">
登录
</el-button>
</template>
</el-dialog>
</div>
</template>
<script setup lang="ts">
/**
* 预览界面。
*
* 定位是**开发时的镜子**:把插件注册出来的东西全部摊开 —— 菜单、页面、
* 命令、事件、扩展点、私有存储 —— 好回答「我实现的东西长什么样」。
*
* 生命周期按钮刻意与宿主同语义:
*
* | 按钮 | 发生什么 |
* | ---- | -------- |
* | 装载并启用 | `install`(仅首次)→ `activate`;注册项进注册表 |
* | 停用 | `deactivate` → **统一回收**全部注册项 |
* | 卸载 | 停用 + `uninstall` + 清空私有存储与 install 标记 |
* | 重新装载 | 源码模式刷新页面;产物模式重新拉一次产物 |
*
* 尤其是「停用」:点完回来看一眼,菜单和路由应该全没了。这条最容易验证
* 「插件有没有偷偷留下幽灵菜单」,而在宿主里要装两遍才看得出来。
*/
import { computed, nextTick, onMounted, reactive, ref, watch } from "vue";
import type { PreviewHost, CommandResult } from "./host";
import type { PluginConfig, PreviewLoader } from "./loaders";
import type { DemoAccount } from "./api-contract";
const props = defineProps<{
host: PreviewHost;
loader: PreviewLoader;
config: PluginConfig;
}>();
const state = props.host.state;
const busy = ref(false);
const error = ref("");
/** 当前装载到的插件模块(用来驱动停用/卸载)。名字避开 `module` —— 它在别处是个敏感词 */
const pluginModule = ref<any>(null);
const selectedRoute = ref<any>(null);
const bottomTab = ref("log");
const logBox = ref<HTMLElement | null>(null);
/* ------------------------------------------------------------ 生命周期 */
const isIdle = computed(() => state.phase !== "active");
const phaseText = computed(() =>
state.phase === "active" ? "已启用" : state.phase === "error" ? "出错" : "未启用"
);
const phaseType = computed(() =>
state.phase === "active" ? "success" : state.phase === "error" ? "danger" : "info"
);
async function start() {
if (busy.value) return;
busy.value = true;
error.value = "";
try {
const loaded = await props.loader.getModule();
pluginModule.value = loaded.module;
for (const note of loaded.notes) props.host.pushLog("info", note);
await props.host.activate(loaded.module);
// 装载完自动选中第一个路由,省一次点击
selectedRoute.value = state.routes[0] ?? null;
} catch (e) {
error.value = String((e as Error)?.message ?? e);
props.host.pushLog("error", error.value);
} finally {
busy.value = false;
}
}
async function stop() {
busy.value = true;
try {
await props.host.deactivate(pluginModule.value);
} finally {
busy.value = false;
}
}
async function rerun() {
// 源码模式下模块已经求值过(自注册被消费、模块内状态也变了),
// 重新装载最可靠的方式是刷新页面 —— 预览启动很快,刷新几乎无感
if (props.loader.reloadPageOnRerun) {
location.reload();
return;
}
busy.value = true;
try {
await props.host.deactivate(pluginModule.value);
await start();
} finally {
busy.value = false;
}
}
async function remove() {
busy.value = true;
try {
await props.host.uninstall(pluginModule.value);
pluginModule.value = null;
selectedRoute.value = null;
} finally {
busy.value = false;
}
}
/* -------------------------------------------------------- 菜单与页面 */
function pick(path?: string) {
if (!path) return;
const hit = state.routes.find((r) => r.path === path);
if (hit) selectedRoute.value = hit;
}
const isCurrent = (path?: string) => !!path && selectedRoute.value?.path === path;
// 重新装载后旧的 route 对象已经失效,指向它会让页面区渲染不出东西
watch(
() => state.routes.map((r) => r.path).join("|"),
() => {
if (!state.routes.includes(selectedRoute.value)) {
selectedRoute.value = state.routes[0] ?? null;
}
}
);
/* ------------------------------------------------------------ 命令台 */
const commandNames = computed(() => Object.keys(state.commands));
const cmdName = ref("");
const cmdArgs = ref("[]");
const cmdResult = ref<CommandResult | null>(null);
watch(
commandNames,
(names) => {
if (!names.includes(cmdName.value)) cmdName.value = names[0] ?? "";
},
{ immediate: true }
);
function parseArgs(text: string): { args: any[]; error?: string } {
const trimmed = text.trim();
if (!trimmed) return { args: [] };
try {
const parsed = JSON.parse(trimmed);
return { args: Array.isArray(parsed) ? parsed : [parsed] };
} catch (e) {
return { args: [], error: (e as Error).message };
}
}
async function runCommand() {
const { args, error: bad } = parseArgs(cmdArgs.value);
if (bad) {
cmdResult.value = { ok: false, error: `参数不是合法 JSON:${bad}`, ms: 0 };
return;
}
cmdResult.value = await props.host.callCommand(cmdName.value, args);
}
/* ------------------------------------------------------------ 事件 */
const channelOptions = computed(() =>
state.channels.map((c) => ({
value: `${c.scope}:${c.name}`,
label: `${c.scope === "global" ? "全局" : "局部"} · ${c.name}`,
}))
);
const evChannel = ref("");
const evArgs = ref("[]");
watch(
() => channelOptions.value.map((c) => c.value).join("|"),
() => {
if (!channelOptions.value.some((c) => c.value === evChannel.value)) {
evChannel.value = channelOptions.value[0]?.value ?? "";
}
},
{ immediate: true }
);
function fireEvent() {
const idx = evChannel.value.indexOf(":");
const scope = evChannel.value.slice(0, idx);
const name = evChannel.value.slice(idx + 1);
const { args, error: bad } = parseArgs(evArgs.value);
if (bad) props.host.pushLog("warn", `事件参数不是合法 JSON(${bad}),已按空参数触发`);
if (scope === "global") props.host.invokeGlobal(name, args);
else props.host.invokeLocal(name, args);
}
/* ------------------------------------------------------------ 登录态 */
/**
* 登录框的状态。
*
* `demos` 是从 `/api/auth/demo-accounts` 取回来的 —— **不是写死在界面里**。
* 真后端没有这个接口时它为空数组,整块演示账号区域自动消失,
* 界面因此不需要知道「当前连的是 mock 还是真后端」。
*/
const loginVisible = ref(false);
const loginError = ref("");
const loginForm = reactive({ account: "", password: "" });
const demos = ref<DemoAccount[]>([]);
function fillDemo(d: DemoAccount) {
loginForm.account = d.account;
loginForm.password = d.password;
// 清掉「上一次登录失败」的提示:用户换了账号,旧错误已经没意义了。
// ⚠️ 这里只清 `loginError`(本次表单的错误),**不能碰 `state.authNotice`** ——
// 上面那句「凭什么是它弹出的框」归 state 管,见 `dialogMessage`。
loginError.value = "";
}
function openLogin() {
// 手动打开时把上一次的失效提示清掉,否则会带着一句不相干的旧原因弹出来
state.authNotice = "";
loginError.value = "";
loginVisible.value = true;
}
async function submitLogin() {
loginError.value = "";
const account = loginForm.account.trim();
if (!account || !loginForm.password) {
loginError.value = "请输入账号与密码";
return;
}
const result = await props.host.login(account, loginForm.password);
if (!result.ok) {
loginError.value = result.message || "登录失败";
return;
}
loginVisible.value = false;
// 密码不留在内存里:预览页面对的是开发者的真机,没必要留一份
loginForm.password = "";
}
async function onLogout() {
await props.host.logout();
loginVisible.value = false;
}
/**
* 对话框里那条提示。
*
* ## 为什么不是直接用一个 `loginError`
*
* 这里有两个**来源不同**的原因,早前把它们塞进同一个 `ref` 时踩过一个很隐蔽的坑:
*
* 1. **本次登录失败**(密码错)→ 表单自己的状态,换账号就该清掉;
* 2. **凭什么是它弹出的框**(令牌失效 / 接口需要登录)→ 属于会话层的事实,
* 存在 `state.authNotice` 里。
*
* 合成一个 ref 之后,「切换演示账号」那次 `loginError = ""` 会把第 2 类原因
* 一起抹掉。而这个抹除只在**请求先后的竞态**下发生(启动恢复的 401 早于
* 演示账号请求),所以表现是「有时弹出来的框没有提示、有时又有」。
*
* 现在:表单原因覆盖会话原因,会话原因**只读不改**,谁也抹不掉谁。
*/
const dialogMessage = computed(() => loginError.value || state.authNotice);
/** 取演示账号。真后端没有这个接口 → 空数组 → 界面自动收起那一块 */
async function loadDemos() {
demos.value = await props.host.demoAccounts();
}
/**
* 令牌失效 / 需要登录时自动把登录框弹出来。
*
* 监听的是**计数器**而不是提示文本:watch 只在值变化时触发,
* 而未登录时连点两次「拉设备列表」会给出两条一模一样的 401 ——
* 只看文本的话第二次就不会弹框了。
*
* 宿主里这一步是「清会话 + 跳登录页」,预览没有路由,对应物就是这个弹窗。
*/
watch(
() => state.authNoticeSeq,
() => {
if (!state.authNotice || state.user) return;
// 弹框的原因是「会话失效 / 接口需要登录」,不是上一次的密码错误 —— 清掉表单那份,
// 让提示完整地由 state.authNotice 提供(见 dialogMessage 的说明)
loginError.value = "";
loginVisible.value = true;
}
);
/* ------------------------------------------------------------ 杂项 */
/** 日志跟着长 —— 不自动滚到底的话,最新那条永远要手动拉 */
watch(
() => state.logs.length,
async () => {
await nextTick();
if (logBox.value) logBox.value.scrollTop = logBox.value.scrollHeight;
}
);
/**
* 静态可查的配置问题。
*
* 这里只挑「预览里就能判定」的几条;真正的体检(产物、checksum、索引一致性)
* 在 `npm run verify` 与仓库的 `repo-doctor` 里,不在这里重复做。
*/
const warnings = computed(() => {
const out: string[] = [];
const contributes = props.config.contributes ?? {};
const hasEntry = (contributes.menus?.length ?? 0) > 0 || (contributes.routes?.length ?? 0) > 0;
if (props.config.activation === "lazy" && !hasEntry) {
out.push(
"activation 是 lazy,但 contributes 里既没有 menus 也没有 routes —— 宿主找不到入口," +
"延迟装载的插件会被退回 eager(代价是启动变慢)"
);
}
if (state.phase === "active" && !state.routes.length) {
out.push("activate 跑完了,但没有注册任何路由 —— 页面区会是空的,用户也找不到这个插件");
}
if (props.config.style && props.loader.mode === "source") {
out.push(
`plugin.config.json 声明了 style=${props.config.style},但源码模式不产出 CSS 文件 —— ` +
"想验证样式真的被抽出来,切到产物模式(npm run preview)"
);
}
return out;
});
const format = (value: any) => {
try {
return JSON.stringify(value, null, 2);
} catch {
return String(value);
}
};
onMounted(async () => {
props.host.syncStorageMirror();
if (props.loader.mode === "artifact") {
props.host.pushLog("info", "产物模式:正在从 /artifact/ 加载 dist/ 里的产物…");
}
/**
* ⚠️ 会话恢复必须**早于**插件装载。
*
* 插件的 `activate` 里会调 `ctx.getUser()` 决定「要不要渲染管理入口」。
* 如果那时会话还没接回来,它会认为没人登录 —— 页面看着正常、功能却是降级过的,
* 而且没有任何报错。宿主里是同一条约束(还要更严:早于路由守卫),
* 见宿主 `src/main.ts` 的启动步骤。
*
* 顺带取一次演示账号;取不到(真后端)不影响装载。
*/
await Promise.all([props.host.restoreSession(), loadDemos()]);
// 首次打开就预填一个演示账号,省掉手打密码;只在表单为空时填,不覆盖用户输入
if (!loginForm.account && !loginForm.password && demos.value.length) fillDemo(demos.value[0]);
start();
});
</script>
+117
View File
@@ -0,0 +1,117 @@
/**
* 预览器的**接口契约**:客户端(`preview/host.ts`)与服务端(`preview/mock-api.ts`)
* 共用这一份定义。
*
* ## 为什么单独一个文件
*
* 这两边是同一份契约的两个实现方。如果各写各的 `AuthUser`、各写各的
* `parseAuthHeader`、各写各的令牌前缀,那么「客户端以为令牌是 `Bearer x`、
* 服务端以为就是 `x`」这类错误**不会有任何编译错误**,只会表现为
* 「登录成功但所有接口都 401」。
*
* 放一个文件里,改一边就同时改了另一边。
*
* ## 它不管什么
*
* 这里只有**线上跑的东西**(存储键、令牌形状、响应包络、请求头解析)。
* 数据表种子、内存 CRUD 逻辑属于实现,在 `mock-api.ts` 里。
*
* ## 与宿主的关系
*
* 契约本身**以宿主为准**(`src/mock/auth.ts` + `src/core/http/index.ts`):
* 同一个地址、同一个包络、同样的 401 语义。预览器是独立工程、拿不到宿主源码,
* 所以这里是一份**手抄的副本** —— 它必然有漂移的风险,这是一处已知的取舍,
* 由 `npm run verify` 的契约断言兜住最关键的几个字段。
*/
/* ------------------------------------------------------------ 存储键 */
/**
* 令牌存储键。
*
* **刻意与宿主不同名**(宿主是 `funjia-plugin-host:token`)。两者平时确实是
* 不同的 origin(预览 5310 / 宿主 5180),但一旦有人把预览挂到宿主同源的
* 子路径下调试,同名的键就会互相覆盖 —— 表现为「预览里登录把宿主的会话踢了」,
* 而且没人会往 localStorage 的键名上想。
*/
export const TOKEN_KEY = "funjia-plugin-preview:token";
/** 用户信息存储键,理由同上 */
export const USER_KEY = "funjia-plugin-preview:user";
/* ------------------------------------------------------------ 令牌形状 */
/** 令牌前缀。明文自描述,肉眼能看出「这是预览 mock 签的」 */
export const TOKEN_PREFIX = "mock";
/** 令牌有效期,与宿主 mock 一致 */
export const TOKEN_TTL_MS = 2 * 60 * 60 * 1000;
/* -------------------------------------------------------------- 类型 */
/** 登录用户(**不含密码**)。字段与宿主 mock 返回的 `user` 对齐 */
export interface AuthUser {
id: number;
name: string;
account: string;
role: string;
dept?: string;
}
/** 演示账号:登录页直接列出来,省掉「文档里翻账号」这一步 */
export interface DemoAccount {
account: string;
password: string;
role: string;
}
/** 统一响应包络。`code === 0` 表示成功 */
export interface ApiResult<T = any> {
code: number;
msg: string;
data: T;
total?: number;
}
/* ------------------------------------------------------------ 约定值 */
/**
* 未授权的业务码。
*
* 与宿主取同一个数字,且**刻意与 HTTP 状态码同值** —— 于是客户端一句
* `result.code === 401` 就能同时覆盖「内置 mock 返回的 code」与
* 「真后端返回的 HTTP 401」(后者由请求层归一成前者)。见 `host.ts` 的 `httpCall`。
*/
export const UNAUTHORIZED_CODE = 401;
/**
* 登录态广播的**全局事件名**(与宿主 `src/core/session.ts` 完全一致)。
*
* 插件用 `ctx.event.onGlobal("user:login", ...)` 监听的就是这两条。
* 预览器也发同样的名字,插件才能在预览里验到「登出后我被通知了」。
*/
export const AUTH_EVENTS = {
login: "user:login",
logout: "user:logout",
} as const;
/* -------------------------------------------------------- 请求头解析 */
/**
* 从 `Authorization` 头的值里取出裸令牌。
*
* **严格校验 `Bearer ` 前缀**,与真后端(和宿主 mock)同口径。
* 宽松处理会把「客户端忘了加前缀」这个 bug 藏起来 —— 而这个 bug 在
* 预览阶段暴露出来只需要一次请求,拖到接真后端那天就变成了
* 「登录明明成功、接口全 401」。
*
* 只有**服务端**(`mock-api.ts`)用到它;放在这里是因为它描述的是
* 契约的校验规则,写错就两边对不上。
*/
export function parseAuthHeader(raw?: string): { token: string; reason?: string } {
const value = (raw || "").trim();
if (!value) return { token: "", reason: "缺少 Authorization 请求头" };
if (!/^Bearer\s+/i.test(value)) {
return { token: "", reason: "Authorization 头缺少 `Bearer ` 前缀" };
}
const token = value.replace(/^Bearer\s+/i, "").trim();
return token ? { token } : { token: "", reason: "Authorization 头里的令牌为空" };
}
+26
View File
@@ -0,0 +1,26 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>插件预览 · 产物模式</title>
<!--
与 index.html 同一份 import map,理由见那边。
产物模式**真的会用到它**:dist/ 里的 ESM 产物保留着裸说明符 `from "vue"`,
浏览器要靠这张表才知道去哪儿取 Vue。
-->
<script type="importmap">
{
"imports": {
"vue": "/runtime.ts",
"funjiaui": "/shims/funjiaui.ts"
}
}
</script>
</head>
<body>
<div id="app"></div>
<script type="module" src="/main-artifact.ts"></script>
</body>
</html>
+96
View File
@@ -0,0 +1,96 @@
/**
* 全局契约的**最小安装**(副作用模块:import 即生效)。
*
* ## 为什么它得单独存在,不能写进 host.ts
*
* 插件的入口脚本在**模块求值的那一刻**就调用了 `window.FunjiaPlugin.register()`
* —— 也就是 `src/index.ts` 只要被 import,注册就已经发生完了。而预览宿主
* (ctx、扩展点注册表、界面)是之后才建起来的。如果契约安装晚于插件源码求值,
* 就会看到那句熟悉的报错:
*
* > 找不到 window.FunjiaPlugin:本脚本必须由宿主页面加载
*
* 而真正的原因只是**顺序**。ESM 的求值顺序是「按 import 声明顺序、深度优先」,
* 所以只要让本模块排在插件源码前面就够了:
*
* ```ts
* import "./contract"; // ① 先求值:契约就位
* import plugin from "../src/index"; // ② 后求值:register 落进队列,不会落空
* ```
*
* 这与宿主里的顺序问题同源:宿主也是「先 `installHostGlobals()`,再装载插件」。
*
* ## 它只装「谁来接」的部分
*
* 队列 + `window.vue` + `window.funjiaui` 兜底 + `window.FunjiaHost` 骨架。
* 真正的 ctx、扩展点注册表、回收逻辑在 `host.ts` 里,由预览界面驱动。
* 这样拆开还有一个好处:`window.FunjiaHost` 是个**稳定的对象引用**,
* 插件在求值时就算把它存起来了,后面 `host.ts` 补充实现(`Object.assign` 到同一个
* 对象上)它也能看到 —— 而不是拿着一个过期的空壳。
*/
import * as Vue from "vue";
import { createFunjiauiFallback } from "./shims/funjiaui";
/** 宿主版本。带 `-preview` 后缀是刻意的:插件若据此分支,日志里能一眼看出环境 */
export const HOST_VERSION = "1.0.0-preview";
/** 宿主标识,对应真实宿主的 `funjia-plugin-host` */
export const HOST_NAME = "funjia-plugin-host-preview";
/** 插件自注册时提交的形状(与宿主 `loader.ts` 的注册队列一致) */
export interface PendingRegistration {
manifest: { id?: string; [key: string]: any };
module: any;
}
/**
* 自注册队列。
*
* 用队列而不是「立即认领」,是因为真实宿主也这么做:脚本可能在宿主还没准备好
* 元数据(来自仓库索引)时就把自己注册进来了。预览沿用同一套语义,
* 免得出现「预览里能认领、宿主里认领不到」的差异。
*/
export const pendingRegistrations: PendingRegistration[] = [];
/** `window.FunjiaHost` 的骨架。**引用要稳定** —— host.ts 会往这个对象上补实现 */
export const hostInfo: Record<string, any> = {
name: HOST_NAME,
version: HOST_VERSION,
http: {
// 先给一个「明说没接上」的实现。host.ts 会换成真的请求层
// (真发请求、带鉴权头、401 统一处理 —— 见 host.ts 的 send)
get: async () => ({ code: 0, msg: "preview: 尚未接入请求层", data: null }),
post: async () => ({ code: 0, msg: "preview: 尚未接入请求层", data: null }),
put: async () => ({ code: 0, msg: "preview: 尚未接入请求层", data: null }),
del: async () => ({ code: 0, msg: "preview: 尚未接入请求层", data: null }),
},
getViewModel: () => undefined,
// 骨架里先给个「没人登录」。host.ts 会覆盖成读真实会话的那两个
getUser: () => null,
isLoggedIn: () => false,
stats: () => ({}),
};
const w = window as any;
// window.vue:**必须是预览页自己那一份 Vue**。IIFE 插件从全局取它,
// 取到的就是渲染这个页面的同一个实例 —— 这正是「同实例」的保证。
w.vue = Vue;
// window.funjiaui:桩(见 shims/funjiaui.ts)。Proxy 能兜住任意名字
w.funjiaui = createFunjiauiFallback();
w.FunjiaHost = hostInfo;
w.FunjiaPlugin = {
register(input: PendingRegistration) {
pendingRegistrations.push(input);
},
};
console.info(
`[preview] %c全局契约已安装%c:window.vue / window.funjiaui(桩) / window.FunjiaHost / window.FunjiaPlugin(版本 ${HOST_VERSION})`,
"color:#3b82f6;font-weight:bold",
"color:inherit"
);
+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>;
+35
View File
@@ -0,0 +1,35 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>插件预览 · 源码模式</title>
<!--
⚠️ import map 必须**静态写在 head 里**,且排在第一个 module 脚本之前。
模块加载一旦开始,再插入 <script type="importmap"> 会被浏览器**静默忽略**
—— 不报错、不生效,症状是 ESM 产物里那句 `import { ref } from "vue"`
解析失败。import map 也没有「回退」语法,所以只声明一次、位置固定。
两个映射分别指向:
- vue → preview/runtime.ts(把预览页自己那份 Vue 原样再导出,保证同实例)
- funjiaui → preview/shims/funjiaui.ts(桩,见该文件顶部说明)
源码模式其实用不到它(源码由 Vite 处理裸说明符),但留着,
好让「源码模式 » 产物模式」的切换不依赖任何额外前提。
-->
<script type="importmap">
{
"imports": {
"vue": "/runtime.ts",
"funjiaui": "/shims/funjiaui.ts"
}
}
</script>
</head>
<body>
<div id="app"></div>
<script type="module" src="/main-source.ts"></script>
</body>
</html>
+195
View File
@@ -0,0 +1,195 @@
/**
* 「插件从哪来」的两种模式。
*
* | 模式 | 插件来源 | 回答的问题 | 快慢 |
* | ---- | -------- | ---------- | ---- |
* | `source` | `src/index.ts` 的静态 import | 我写的东西长什么样、逻辑对不对 | 改完即见(Vite 热更新) |
* | `artifact` | `dist/` 里的真实产物 | **交给宿主的那几个字节**能不能跑 | 要先 `npm run build` |
*
* 之所以两个都要,是因为它们会分别失败在不同的地方:
*
* - 源码模式跑得通、产物模式跑不通 → 问题在**构建配置**(`external` 没生效、
* 产物名不对、`output.globals` 映射错了、样式没抽出来);
* - 两个都跑通、宿主里不跑 → 问题在**仓库与装载链路**(路径、`checksum`、
* import map、`activation` 与 `contributes` 不匹配)。
*
* 这条分界线能省掉大量「到底哪一步坏了我」的排查时间,所以别只用一个模式。
*/
import type { PluginModule } from "../src/sdk";
import { pendingRegistrations } from "./contract";
/** `plugin.config.json` 的形状(只声明预览用得上的字段) */
export interface PluginConfig {
id: string;
name: string;
version: string;
kind: "iife" | "esm";
artifact: string;
style?: string;
globalKey?: string;
activation?: string;
[key: string]: any;
}
export interface LoadedPlugin {
module: PluginModule;
/** 装载过程中的说明,会写进预览的日志台 —— 让「怎么装载的」可见 */
notes: string[];
}
export interface PreviewLoader {
mode: "source" | "artifact";
/** 顶栏徽标上的短标签 */
label: string;
/** 一句话说明这个模式在验什么 */
hint: string;
/**
* 点「重新装载」时是不是该刷新页面。
*
* 源码模式:模块已经求值过(自注册被消费、模块内状态也变了),重新装载
* 最可靠的方式是刷新页面 —— 预览页启动很快,刷新几乎无感。
* 产物模式:重新拉一次产物即可,不必刷新。
*/
reloadPageOnRerun: boolean;
getModule(): Promise<LoadedPlugin>;
}
/* ------------------------------------------------------------ 工具 */
/**
* 用 `<script>` 加载产物 —— 与宿主装载 IIFE 插件的方式完全一致。
*
* `async = false` 是有意的:让脚本按插入顺序执行。这里只有一个脚本,
* 但不写会让「加载完成」与「执行完成」之间多一个不确定的间隙。
*/
function loadScript(src: string): Promise<void> {
return new Promise((resolve, reject) => {
const el = document.createElement("script");
el.src = src;
el.async = false;
el.onload = () => resolve();
el.onerror = () =>
reject(
new Error(
`产物加载失败:${src}\n` +
"多半是还没构建 —— 跑一次 npm run build(或直接用 npm run preview,它会先构建)。"
)
);
document.head.appendChild(el);
});
}
/**
* 注入样式表,模拟宿主按 `manifest.style` 注入插件样式。
*
* 失败**不阻断**装载:样式拿不到插件逻辑照样能跑,真实宿主也是尽力注入。
* (但控制台里会留一条 404,能看出 `style` 字段写了却没产出对应文件。)
*/
function injectStyle(href: string): Promise<void> {
return new Promise((resolve) => {
const el = document.createElement("link");
el.rel = "stylesheet";
el.href = href;
el.onload = () => resolve();
el.onerror = () => resolve();
document.head.appendChild(el);
});
}
/** 从自注册队列里认领指定 id 的插件(真实宿主的认领动作,在此复刻) */
function claimById(id: string): PluginModule | null {
const i = pendingRegistrations.findIndex((r) => r?.manifest?.id === id);
if (i < 0) return null;
return pendingRegistrations.splice(i, 1)[0].module as PluginModule;
}
/* ------------------------------------------------------- 源码模式 */
/**
* 源码模式。
*
* 模块由调用方**静态 import** 并传进来 —— 这一点是必需的:只有静态依赖,
* Vite 的 HMR 依赖图里才有它,改 `pages/*.vue` 才能热更新;而且静态 import
* 的求值顺序受 import 声明控制,契约(`./contract`)能排在它前面先执行。
*/
export function createSourceLoader(module: PluginModule): PreviewLoader {
return {
mode: "source",
label: "源码",
hint: "直接跑 src/ 下的源码:改页面组件由 Vite 热更新,不走构建、不碰仓库",
reloadPageOnRerun: true,
async getModule() {
return {
module,
notes: ["模块来自 src/index.ts 的静态 import(契约已先于它求值,所以自注册不会落空)"],
};
},
};
}
/* ------------------------------------------------------- 产物模式 */
/**
* 产物模式:把 `dist/` 里的东西当远端插件装一遍。
*
* 每一步都刻意贴着宿主的真实动作:
*
* 1. 按 `manifest.style` 注入 CSS(宿主的做法);
* 2. `iife` → `<script src>`;`esm` → `import()`,裸说明符由 import map 解析;
* 3. 认领:先看自注册队列(`window.FunjiaPlugin.register`),再退回
* `window[globalKey]` —— 与宿主的两条认领通道一致。
*/
export function createArtifactLoader(config: PluginConfig): PreviewLoader {
return {
mode: "artifact",
label: "产物",
hint: "加载 dist/ 里的真实产物,走宿主装载时的同一套路径规则(能验 external 是否真的生效)",
reloadPageOnRerun: false,
async getModule() {
const notes: string[] = [];
// 每次装载都换一个查询串,避免浏览器把上一次的产物缓存住 ——
// 「重新装载还是旧行为」是最容易浪费时间的假象之一
const bust = `?t=${Date.now()}`;
if (config.style) {
await injectStyle(`/artifact/${config.style}`);
notes.push(`已按 manifest.style 注入 ${config.style}`);
}
if (config.kind === "esm") {
const mod = await import(/* @vite-ignore */ `/artifact/${config.artifact}${bust}`);
notes.push(
"以 ESM 形态 import():产物里的裸说明符 vue 由 index.html 的 import map 解析到预览页同一份 Vue"
);
const module = (mod as any).default ?? mod;
if (!module) throw new Error("ESM 产物没有默认导出,宿主会拿不到插件对象");
return { module, notes };
}
await loadScript(`/artifact/${config.artifact}${bust}`);
const claimed = claimById(config.id);
if (claimed) {
notes.push("产物自注册成功(window.FunjiaPlugin.register),按 id 认领");
return { module: claimed, notes };
}
const byGlobal = config.globalKey ? (window as any)[config.globalKey] : undefined;
if (byGlobal) {
notes.push(`走老生态通道 window.${config.globalKey} 认领`);
return { module: byGlobal, notes };
}
// 这条报错要尽量说清「是哪一环断了」——它对应宿主里那个
// 「脚本已执行,但自注册队列与全局变量都没拿到插件」的经典现场
throw new Error(
`产物已执行,但两条认领通道都没拿到插件:\n` +
` · 自注册队列里没有 id 为 "${config.id}" 的注册(检查 src/index.ts 里的 PLUGIN_ID)\n` +
` · window.${config.globalKey} 也是空的(检查 plugin.config.json 的 globalKey,` +
`以及产物是不是被打成了 namespace:window.X = { default: … })`
);
},
};
}
+21
View File
@@ -0,0 +1,21 @@
/**
* 产物模式入口(`npm run preview`)。
*
* 与源码模式唯一的区别:**不 import `../src/index`**。
*
* 这里加载的是 `dist/` 里的真实产物(`/artifact/<产物名>`),走的是宿主装载
* 远端插件时的同一套路径规则:`<script src>` 加载 IIFE、`import()` 加载 ESM、
* 按 `manifest.style` 注入 CSS、再按 id 或全局名认领。
*
* 所以这个模式回答的问题很具体:**我交出去的产物,换台机器还能不能跑。**
* 源码跑得通但这里跑不通,就是构建配置的问题(external、产物名、globalKey…)。
*/
import "./contract"; // 契约仍然要装:产物自注册时需要有队列接住
import config from "../plugin.config.json";
import { mountPreview } from "./mount";
import { createArtifactLoader } from "./loaders";
import type { PluginConfig } from "./loaders";
mountPreview(config as PluginConfig, createArtifactLoader(config as PluginConfig));
+22
View File
@@ -0,0 +1,22 @@
/**
* 源码模式入口(`npm run dev`)。
*
* ⚠️ **import 的书写顺序就是执行顺序,不能调换:**
*
* 1. `./contract` —— 先把契约装上(`window.FunjiaPlugin` 的队列)
* 2. `../src/index` —— 插件源码求值,此时它的自注册才有地方落
*
* 调换的话会看到「找不到 window.FunjiaPlugin:本脚本必须由宿主页面加载」,
* 而真正的原因只是顺序 —— 这类误判(去查路径、CORS、缓存,绕一大圈)
* 正是预览器存在的意义之一:它把顺序固定下来,让环境问题不再伪装成代码问题。
*/
import "./contract"; // ① 必须是第一个
import pluginModule from "../src/index"; // ② 插件源码,在契约之后求值
import config from "../plugin.config.json";
import { mountPreview } from "./mount";
import { createSourceLoader } from "./loaders";
import type { PluginConfig } from "./loaders";
mountPreview(config as PluginConfig, createSourceLoader(pluginModule as any));
+498
View File
@@ -0,0 +1,498 @@
/**
* 预览器的最小后端(Vite 中间件)。
*
* ## 为什么预览器需要它
*
* 插件里最常见的功能就是「拉列表、存表单」。如果预览环境一律把 http 拦掉,
* 插件作者就只能看到一堆「被拦截」的日志 —— 页面渲染对不对能验,**功能对不对验不了**。
* 这个中间件让 `ctx.http.get("/api/device/list")` 在预览里真的能拿到数据。
*
* ## 它与宿主 mock 的关系
*
* 宿主自己也有一套 mock(`src/mock/`),跑在**浏览器内**、拦的是前端请求。
* 预览器是独立工程,拿不到那套代码(也不该依赖宿主源码),所以这里**重写一份**
* —— 但只重写「数据与路由」这层,契约里的关键定义与客户端共用,见下。
*
* 代价是两份实现可能漂移。因此约定:
*
* - **接口契约以宿主为准**,这里是它的**子集**(只实现最常用的几个);
* - 响应形状、`code` 取值、401 的语义**必须一致** —— 不一致就等于骗了插件作者;
* - 契约里那几个**线上跑的东西**(存储键、令牌形状、包络、请求头解析)
* 不在这份文件里重写,而是与客户端共用 `preview/api-contract.ts`;
* - 真后端就绪后,用 `PREVIEW_API_TARGET` 把 `/api` 代理过去,
* 这份 mock 自动让位(见 `vite.preview.config.ts`)。
*
* ## 401 与宿主对齐的地方
*
* 1. 未授权同时给 **HTTP 401** 和 **`code: 401`**(宿主 http 层认后者,
* 但真后端可能只给状态码,两边都给最稳);
* 2. `Authorization` 必须是 `Bearer <token>`,**严格校验前缀** ——
* 这样「请求层忘了加前缀」会在预览阶段暴露;
* 3. 登录接口用 `code: 1` 表达密码错误(业务失败),**不用 401**
* (401 的含义是「未授权」,会被上层当成「令牌失效」去清会话)。
*/
import type { IncomingMessage, ServerResponse } from "node:http";
import {
TOKEN_PREFIX,
TOKEN_TTL_MS,
UNAUTHORIZED_CODE,
parseAuthHeader,
type ApiResult,
type AuthUser,
} from "./api-contract";
/* ------------------------------------------------------------------ 类型 */
/** 用户表里的一行 = 对外的用户 + 密码(密码**绝不**出现在响应里) */
interface MockUser extends AuthUser {
password: string;
}
type Row = Record<string, any>;
/* ------------------------------------------------------------------ 数据 */
/** 与宿主 `src/mock/auth.ts` 的演示账号保持一致 */
const USERS: MockUser[] = [
{
id: 1,
account: "funjia",
password: "funjia123",
name: "管理员",
role: "超级管理员",
dept: "信息中心",
},
{
id: 2,
account: "viewer",
password: "viewer123",
name: "巡检员",
role: "普通用户",
dept: "运维组",
},
];
/**
* 种子数据:宿主 `src/mock/db.ts` 的一小部分。
*
* 刻意**不搬全**。预览要的是「有数据可看」,不是「数据与宿主逐行一致」;
* 搬全了一份 10 行的设备表反而会让这里变成第二个需要同步维护的地方。
*/
const SEED: Record<string, Row[]> = {
device: [
{ id: 1, code: "PC-2024-0001", name: "联想 ThinkCentre M720", category: "主机", brand: "联想", status: "在租", price: 1200, owner: "市政务服务中心信息科" },
{ id: 2, code: "MN-2024-0031", name: "AOC 24B1XH", category: "显示器", brand: "AOC", status: "在租", price: 300, owner: "市政务服务中心信息科" },
{ id: 3, code: "PC-2024-0007", name: "戴尔 OptiPlex 3080", category: "主机", brand: "戴尔", status: "闲置", price: 1100, owner: "" },
{ id: 4, code: "AIO-2024-0002", name: "惠普 ProOne 400 G6", category: "一体机", brand: "惠普", status: "维修中", price: 1600, owner: "第三实验中学" },
],
notice: [
{ id: 1, title: "租赁设备季度巡检安排", level: "重要", publisher: "运维组", content: "本季度巡检覆盖全部在租设备。" },
{ id: 2, title: "系统升级通知", level: "普通", publisher: "系统管理员", content: "本周六 22:00 升级,期间暂停服务约 30 分钟。" },
],
};
/* -------------------------------------------------------------- 响应助手 */
const ok = (data: any, total?: number): ApiResult => ({
code: 0,
msg: "ok",
data,
...(total === undefined ? {} : { total }),
});
const fail = (msg: string, code = 1): ApiResult => ({ code, msg, data: null });
const unauthorized = (reason: string): ApiResult => ({
code: UNAUTHORIZED_CODE,
msg: reason || "未登录或登录已过期",
data: null,
});
/* ------------------------------------------------------------------ 令牌 */
const toPublic = (user: MockUser): AuthUser => {
const { password: _password, ...rest } = user;
return rest;
};
function signToken(userId: number, ttl: number = TOKEN_TTL_MS): string {
const exp = Date.now() + ttl;
const nonce = Math.random().toString(36).slice(2, 10);
return `${TOKEN_PREFIX}.${userId}.${exp}.${nonce}`;
}
function verifyToken(token: string): { ok: true; user: AuthUser } | { ok: false; reason: string } {
const parts = String(token || "").split(".");
if (parts.length !== 4 || parts[0] !== TOKEN_PREFIX) {
return { ok: false, reason: "令牌格式不正确" };
}
const userId = Number(parts[1]);
const exp = Number(parts[2]);
if (!Number.isFinite(userId) || !Number.isFinite(exp)) {
return { ok: false, reason: "令牌格式不正确" };
}
if (Date.now() > exp) return { ok: false, reason: "登录状态已过期,请重新登录" };
const user = USERS.find((item) => item.id === userId);
if (!user) return { ok: false, reason: "令牌对应的用户不存在" };
return { ok: true, user: toPublic(user) };
}
/* ------------------------------------------------------------------ 请求 */
function readBody(req: IncomingMessage): Promise<any> {
return new Promise((resolve) => {
let raw = "";
req.on("data", (chunk) => {
raw += chunk;
// 1MB 上限:预览后端不该被一个大 body 拖死
if (raw.length > 1024 * 1024) raw = raw.slice(0, 1024 * 1024);
});
req.on("end", () => {
try {
resolve(raw ? JSON.parse(raw) : {});
} catch {
resolve({});
}
});
req.on("error", () => resolve({}));
});
}
/* ------------------------------------------------------------------ SN 码 */
/**
* SN 码的预览后端(对应宿主后端的 `api::sn-code` 模块)。
*
* ## 为什么模板里要额外带这一段
*
* 模板自带的通用 CRUD 只覆盖 `/api/<name>/list|detail|add|update|delete`,
* 而「标签打印」插件的核心增量能力是**可选接入 SN 码接口** —— 少了这一段,
* `npm run dev` 里一打开「② SN 码」开关就是 404,本地根本验不了,
* 只能构建 → 发布 → 装进宿主 → 点一遍,一圈几分钟。
*
* ## 与真后端的关系
*
* 参数口径(`targetType` / `count` / `refId` / `refLabel` / `remark`、返回
* `{ items }`、校验返回 `{ valid, reason, exists, record }`)**照着真后端抄**,
* 但**数据是进程内的**、格式里的校验位算法也是这里自己定的 ——
* 所以:**别看号段,只验链路**。真要对接,关掉开关或设 `PREVIEW_API_TARGET`。
*/
/** 业务类型 → 号段前缀。真后端同结构,前缀值以真后端 `/meta` 为准 */
const SN_PREFIX: Record<string, string> = {
DEVICE: "ZP",
PART: "PJ",
LEASE: "ZL",
MAINTENANCE: "SH",
CUSTOMER: "KH",
OTHER: "SN",
};
/** 校验位:body 各字符按 31 进制滚动求和后取模 36,映射到 0-9A-Z */
function snChecksum(body: string): string {
let sum = 0;
for (let i = 0; i < body.length; i += 1) {
sum = (sum * 31 + body.charCodeAt(i)) % 36;
}
return "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"[sum];
}
function makeSn(targetType: string, seq: number): string {
const pad = (n: number) => String(n).padStart(2, "0");
const now = new Date();
const prefix = SN_PREFIX[targetType] || "SN";
const body = `${prefix}-${String(now.getFullYear()).slice(2)}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${String(seq).padStart(4, "0")}`;
return `${body}-${snChecksum(body)}`;
}
function issueSn(ledger: Row[], body: any, count: number): Row[] {
const targetType = String(body?.targetType || "DEVICE");
const batch = `B${Date.now().toString(36).toUpperCase()}`;
const out: Row[] = [];
for (let i = 0; i < count; i += 1) {
const sn = makeSn(targetType, ledger.length + 1);
const row: Row = {
sn,
targetType,
batch,
status: "ISSUED",
issuedAt: new Date().toISOString(),
...(body?.refId ? { refId: body.refId } : {}),
...(body?.refLabel ? { refLabel: body.refLabel } : {}),
...(body?.remark ? { remark: body.remark } : {}),
};
ledger.push(row);
out.push(row);
}
return out;
}
/** 命中 `/api/sn-codes*` 时返回结果;不命中返回 null,交回通用流程 */
function handleSnCode(
method: string,
path: string,
query: Record<string, string>,
body: any,
store: Record<string, Row[]>
): ApiResult | null {
if (path !== "/api/sn-codes" && !path.startsWith("/api/sn-codes/")) return null;
if (!store.__sn) store.__sn = [];
const ledger = store.__sn;
if (method === "GET" && path === "/api/sn-codes/meta") {
return ok({
targetTypes: Object.keys(SN_PREFIX),
defaultPrefix: SN_PREFIX,
typicalLength: 15,
maxLength: 16,
});
}
if (method === "POST" && path === "/api/sn-codes/generate") {
return ok(issueSn(ledger, body, 1)[0]);
}
if (method === "POST" && path === "/api/sn-codes/batch") {
const count = Math.min(Math.max(1, Number(body?.count) || 1), 200);
const items = issueSn(ledger, body, count);
return ok({ items, batch: items[0]?.batch });
}
if (method === "POST" && path === "/api/sn-codes/verify") {
const text = String(body?.sn || "").trim();
if (!text) return ok({ valid: false, reason: "EMPTY" });
const matched = text.match(/^([A-Z]{2})-(\d{6})-(\d{4})-([0-9A-Z])$/);
if (!matched) return ok({ valid: false, reason: "FORMAT" });
if (snChecksum(`${matched[1]}-${matched[2]}-${matched[3]}`) !== matched[4]) {
return ok({ valid: false, reason: "CHECKSUM" });
}
const record = ledger.find((row) => row.sn === text) || null;
return ok({ valid: true, exists: !!record, record });
}
if (method === "GET" && path === "/api/sn-codes") {
const pageSize = Number(query.pageSize) || 50;
let rows = ledger.slice();
for (const key of ["targetType", "status", "batch"] as const) {
if (query[key]) rows = rows.filter((row) => String(row[key]) === query[key]);
}
if (query.sn) rows = rows.filter((row) => String(row.sn).includes(query.sn));
// 看最新发放的在前,和真后端一致
rows = rows.slice().reverse();
return ok(rows.slice(0, pageSize), rows.length);
}
const voided = path.match(/^\/api\/sn-codes\/([^/]+)\/void$/);
if (method === "POST" && voided) {
const target = ledger.find((row) => row.sn === decodeURIComponent(voided[1]));
if (!target) return fail("SN 不存在");
target.status = "VOID";
target.voidedAt = new Date().toISOString();
return ok(target);
}
return null;
}
/* ------------------------------------------------------------------ 路由 */
/**
* 路由分发。
*
* `store` 由调用方传进来(而不是读模块级的变量):数据必须**每个预览进程一份**,
* 且要能被 `createPreviewApi()` 的闭包持有 —— 写成模块级单例的话,
* 多次创建中间件会共用一份脏数据。
*/
function handle(
method: string,
path: string,
query: Record<string, string>,
body: any,
store: Record<string, Row[]>,
authorization?: string
): ApiResult {
/* ---- 免登录 ---- */
if (method === "POST" && path === "/api/auth/login") {
const user = USERS.find(
(item) => item.account === String(body.account || "").trim() && item.password === body.password
);
if (!user) return fail("账号或密码不正确");
return ok({
token: signToken(user.id),
expiresIn: Math.floor(TOKEN_TTL_MS / 1000),
user: toPublic(user),
});
}
// 登出幂等且免登录:令牌已过期时也必须能登出,否则用户卡在跳不出去的状态
if (method === "POST" && path === "/api/auth/logout") return ok(true);
if (method === "GET" && path === "/api/auth/demo-accounts") {
return ok(USERS.map((u) => ({ account: u.account, password: u.password, role: u.role })));
}
/* ---- 鉴权闸门:以下一律要求合法令牌 ---- */
const parsed = parseAuthHeader(authorization);
if (parsed.reason) return unauthorized(parsed.reason);
const auth = verifyToken(parsed.token);
if (!auth.ok) return unauthorized(auth.reason);
if (method === "GET" && path === "/api/auth/me") return ok(auth.user);
/* ---- SN 码:插件专属接口,优先于通用 CRUD 匹配 ---- */
const snResult = handleSnCode(method, path, query, body, store);
if (snResult) return snResult;
/* ---- 通用 CRUD ---- */
const crud = path.match(/^\/api\/([\w-]+)\/(list|detail|add|update|delete)$/);
if (crud) {
const [, name, action] = crud;
// 集合不存在就就地创建:宿主也是这个行为(`collection()` 动态建表),
// 于是插件自带的数据表不需要先在种子里登记
if (!store[name]) store[name] = [];
const storeRows = store[name];
if (action === "list") {
const page = Number(query.page) || 1;
const pageSize = Number(query.pageSize) || 10;
const keyword = (query.keyword || "").trim().toLowerCase();
/**
* 保留字不参与等值过滤。
*
* `userId` / `pluginId` 尤其要注意:宿主会给插件请求自动附加这两个归属参数
* (见宿主 mock 的同名路由),把它们当业务字段去等值过滤会**永远筛出空集**,
* 而症状是「列表页一个插件都查不到数据」—— 很难往参数名上想。
*/
const RESERVED = ["page", "pageSize", "keyword", "userId", "pluginId"];
let matched = storeRows.slice();
for (const [key, value] of Object.entries(query)) {
if (RESERVED.includes(key)) continue;
if (value === undefined || value === null || value === "") continue;
matched = matched.filter((row) => String(row[key]) === String(value));
}
if (keyword) {
// 关键字按**第一行的字段名**搜(与宿主 `db.query` 的默认 keywordFields 一致),
// 而不是按每一行自己的字段 —— 否则字段不齐的行会搜出不一样的结果
const fields = Object.keys(matched[0] || {});
matched = matched.filter((row) =>
fields.some((field) => String((row as Row)[field] ?? "").toLowerCase().includes(keyword))
);
}
const start = (page - 1) * pageSize;
// 列表的 `data` 是**数组本身**,条数是同级的 `total` —— 与宿主一致。
// (写成 `data: { rows, total }` 是最常见的抄错,插件那边会永远拿不到行)
return ok(matched.slice(start, start + pageSize), matched.length);
}
if (action === "detail") {
return ok(storeRows.find((row) => String(row.id) === String(query.id)) || null);
}
if (action === "add") {
const nextId = storeRows.reduce((max, row) => Math.max(max, Number(row.id) || 0), 0) + 1;
const row: Row = { ...body, id: nextId, createdAt: new Date().toISOString() };
storeRows.push(row);
return ok(row);
}
if (action === "update") {
const index = storeRows.findIndex((row) => String(row.id) === String(body.id));
if (index < 0) return fail("记录不存在");
storeRows[index] = { ...storeRows[index], ...body };
return ok(storeRows[index]);
}
if (action === "delete") {
const raw = body.ids !== undefined ? body.ids : body.id;
const ids = (Array.isArray(raw) ? raw : raw === undefined ? [] : [raw]).map(String);
if (!ids.length) return fail("没有指定要删除的记录");
const before = storeRows.length;
// 整体替换而不是原地 splice:保持「store 里的数组对象」这一层的稳定性,
// detail/update 拿到的是同一份引用,语义简单
store[name] = storeRows.filter((row) => !ids.includes(String(row.id)));
return ok(before - store[name].length);
}
}
// 明确报「没有这个接口」而不是静默 404 —— 插件作者一眼就知道是路径写错了,
// 而不是后端挂了
return fail(`预览后端没有这个接口:${method} ${path}(实现见 preview/mock-api.ts)`, 404);
}
/* ------------------------------------------------------------------ 出口 */
/**
* 创建中间件。数据存在闭包里,**进程重启即重置**(预览不需要持久化)。
*/
export function createPreviewApi() {
// 深拷贝:种子数据不该被请求改到,否则第二次装载就看到脏数据了
const store: Record<string, Row[]> = JSON.parse(JSON.stringify(SEED));
/**
* 已经提醒过的空集合名。
*
* 通用 CRUD 会**动态创建**没见过的集合(宿主同行为),于是表名打错
* (`/api/devices/list` 而种子是 `device`)的表现是「接口成功、列表是空的」——
* 看起来像「没数据」,不像「表名错了」。
*
* 响应**不动**(那是契约,宿主也是这么答的),只在预览服务端的终端里提醒一句:
* 那里正是开发者跑 `npm run dev` 时盯着的窗口。用 Set 去重,只提醒一次。
*/
const warned = new Set<string>();
const seedKeys = new Set(Object.keys(SEED));
function warnIfUnknownCollection(path: string) {
const match = path.match(/^\/api\/([\w-]+)\/(list|detail)$/);
if (!match) return;
const [, name] = match;
if (seedKeys.has(name) || warned.has(name)) return;
warned.add(name);
console.warn(
`\n \x1b[33m[preview]\x1b[0m 集合 \`${name}\` 不在预览种子里,已自动建成空表(宿主也是这样)。` +
`\n 如果你以为它有数据,先检查表名拼写;种子里现有:${[...seedKeys].join(" / ")}\n`
);
}
return async function previewApiMiddleware(
req: IncomingMessage,
res: ServerResponse,
next: (err?: any) => void
): Promise<void> {
const rawUrl = req.url || "/";
const path = rawUrl.split("?")[0];
if (!path.startsWith("/api/")) return next();
const query: Record<string, string> = {};
for (const [key, value] of new URL(rawUrl, "http://127.0.0.1").searchParams) {
query[key] = value;
}
const method = (req.method || "GET").toUpperCase();
const body = method === "GET" ? {} : await readBody(req);
if (method === "GET") warnIfUnknownCollection(path);
let result: ApiResult;
try {
result = handle(method, path, query, body, store, req.headers.authorization);
} catch (error) {
result = fail(`预览后端内部错误:${(error as Error)?.message ?? error}`, 500);
}
// 未授权同时给 HTTP 状态码与业务码:真后端可能只给其一,
// 两边都给能让预览的行为最接近「两种后端都试过」
res.statusCode = result.code === UNAUTHORIZED_CODE ? UNAUTHORIZED_CODE : 200;
res.setHeader("Content-Type", "application/json; charset=utf-8");
res.setHeader("Cache-Control", "no-store");
res.end(JSON.stringify(result));
};
}
+59
View File
@@ -0,0 +1,59 @@
/**
* 预览页的挂载入口 —— 两个 entry(源码 / 产物)共用这一份。
*
* 这里做的事,对应真实宿主 `main.ts` 里的同一批步骤:装 Element Plus、
* 注册图标、创建宿主、挂载界面。差别只在「宿主是谁」。
*/
import { createApp } from "vue";
import ElementPlus from "element-plus";
import "element-plus/dist/index.css";
import * as Icons from "@element-plus/icons-vue";
import App from "./App.vue";
import "./style.css";
import { createPreviewHost, type PreviewManifest } from "./host";
import * as apiContract from "./api-contract";
import type { PluginConfig, PreviewLoader } from "./loaders";
export function mountPreview(config: PluginConfig, loader: PreviewLoader): void {
const manifest: PreviewManifest = {
id: config.id,
name: config.name,
version: config.version,
kind: config.kind,
activation: config.activation,
/**
* `repository` / `checksum` 刻意留空。
*
* 预览不是从仓库装的,对应的是真实宿主里「手工填 URL 安装」那一种情形 ——
* 而 `ctx.plugin.repository` 有没有值,本身就是插件判断自己来源的判据
* (`demo.repo-badge` 就靠它显示「来自仓库」)。
* 所以:**依赖 `repository` 的分支在预览里走不到**,这是已知且刻意的差异,
* 界面顶部也会标出来。
*/
repository: undefined,
checksum: undefined,
};
const host = createPreviewHost(manifest);
const app = createApp(App, { host, loader, config });
app.use(ElementPlus);
// 图标全量注册,与宿主一致 —— 插件的 menuIcon: "Star" 在预览里才显示得出来
for (const [name, component] of Object.entries(Icons)) {
app.component(name, component as any);
}
app.mount("#app");
document.title = `插件预览 · ${config.name}(${loader.label}模式)`;
// 顺手挂到 window 上:卡住的时候可以直接在控制台里手玩
//
// `apiContract` 也一起挂出来,是为了让**排查与自动化脚本**能读到契约常量
// (存储键、401 的业务码…),而不是在几处各写一遍字面量 ——
// 写错了不会有任何编译错误,只会让脚本「查了一个错的键」然后静默通过。
(window as any).__preview__ = { host, manifest, config, loader, apiContract };
}
+27
View File
@@ -0,0 +1,27 @@
/**
* ESM 产物在预览环境里的 `vue` 解析目标。
*
* `preview/index.html` 的 import map 把裸说明符 `vue` 指到这里。ESM 产物里
* 保留着 `import { ref } from "vue"` 这样的裸说明符(rollup 的 `output.globals`
* 对 ESM 无效),浏览器不认识它,必须由 import map 指到一个真实 URL。
*
* ```js
* // 产物里(没被改写)
* import { defineComponent, ref } from "vue";
* ```
*
* ## 为什么是 `export * from "vue"` 而不是指向别处
*
* 预览页自己已经加载了一份 Vue(`main.ts` 里 `createApp`)。本文件把**同一份**
* 重新导出,于是产物拿到的 Vue 和预览页用的是同一个实例 —— 这正是宿主
* `funjia-runtime.js` 存在的理由,只是预览环境里它的作用域小得多。
*
* 如果这里换成另一份 Vue(比如让产物自带、或从这里 import 一个别的副本),
* 症状是**页面画得出来但完全点不动** —— 事件与响应式不在同一个依赖图里。
* 所以这个文件只有一行,且不要动。
*
* > 注意 `export *` 不导出 `default`。宿主那份 runtime 也是同样写法,
* > 插件应当用具名导入(`import { ref } from "vue"`),这一点与宿主一致。
*/
export * from "vue";
+164
View File
@@ -0,0 +1,164 @@
/**
* 预览环境里的 `funjiaui` 替身。
*
* ## 先讲清楚它不是什么
*
* **它不是 FunjiaUI。** 预览服务器只装了 Vue 和 Element Plus —— FunjiaUI 是
* 宿主的私有依赖(`git+…#v1.4.0` 那种),插件工程没有理由依赖它,预览也不该
* 为了它把安装成本抬上去。所以这里是一组桩:**保证 import 成功、装饰器调用
* 不崩、占位可见**,但不会产生任何真实表格/表单行为。
*
* 于是有一条你得记住的边界:
*
* > 预览里能跑通 ≠ 宿主里一定能跑通。
* > 预览回答的是「我写的这些东西长什么样」,用到 FunjiaUI 深水区
* > (`UmTable` 的列配置、远程配置类、装饰器元数据)的行为仍然要在宿主里验一遍。
*
* ## 两条通道,两个实现
*
* | 通道 | 谁在用 | 实现 |
* | ---- | ------ | ---- |
* | ESM 具名导入 `import { UmTable } from "funjiaui"` | `kind: esm` 的产物 | 本文件的静态导出 |
* | 全局取用 `window.funjiaui.UmTable` | `kind: iife` 的产物 | `createFunjiauiFallback()` 的 Proxy |
*
* ESM 必须有**静态具名导出**(浏览器要能在实例化阶段解析出每一个名字),所以
* 下面是一个个列出来的,不能用循环生成。IIFE 走 Proxy,任意名字都能兜住,
* 代价是拿到的东西一律是「装饰器桩」形态(能当装饰器、能当函数调,不能当组件渲染)。
*
* 如果你 import 了一个下面没列的名字,`npm run verify` 会指出来让你补 ——
* 这样桩和实际用法不会悄悄脱节。
*/
import { defineComponent, h } from "vue";
/* ------------------------------------------------------------ 组件桩 */
const STUB_STYLE = {
border: "1px dashed #e6a23c",
borderRadius: "6px",
padding: "8px 10px",
margin: "4px 0",
background: "#fdf6ec",
color: "#a06d1f",
fontSize: "12px",
lineHeight: "1.6",
};
/**
* 把组件渲染成一块显眼的占位。
*
* 刻意做得「丑且明显」—— 它必须和真实界面区分得开,否则会出现
* 「预览里看着挺正常,装到宿主里发现完全不是这回事」这种最坏的情况。
*/
function stubComponent(name: string) {
return defineComponent({
name,
inheritAttrs: false,
setup(_props, { slots }) {
return () =>
h("div", { style: STUB_STYLE, "data-funjiaui-stub": name }, [
`[预览桩] funjiaui.${name} —— 真实渲染要在宿主里看`,
slots.default ? h("div", { style: { marginTop: "4px", opacity: "0.75" } }, slots.default()) : null,
]);
},
});
}
export const AreaTree = stubComponent("AreaTree");
export const Iconfont = stubComponent("Iconfont");
export const UmByClass = stubComponent("UmByClass");
export const UmByClassEnhance = stubComponent("UmByClassEnhance");
export const UmColumnRender = stubComponent("UmColumnRender");
export const UmDialog = stubComponent("UmDialog");
export const UmDistrictTree = stubComponent("UmDistrictTree");
export const UmDistrictTreeNode = stubComponent("UmDistrictTreeNode");
export const UmPagination = stubComponent("UmPagination");
export const UmRemoteClass = stubComponent("UmRemoteClass");
export const UmSearchForm = stubComponent("UmSearchForm");
export const UmSyncNodeForm = stubComponent("UmSyncNodeForm");
export const UmTable = stubComponent("UmTable");
export const UmTableColumn = stubComponent("UmTableColumn");
export const UmTableDialog = stubComponent("UmTableDialog");
export const UmTableForm = stubComponent("UmTableForm");
export const UmTableOperate = stubComponent("UmTableOperate");
export const UmTableToolbar = stubComponent("UmTableToolbar");
export const UmTree = stubComponent("UmTree");
export const UmTreeSelect = stubComponent("UmTreeSelect");
/* ---------------------------------------------------------- 装饰器桩 */
/**
* 装饰器桩:要同时吃得下两种写法。
*
* ```ts
* class X { @TableColumnPropertyDecorator({ title: "编号" }) code = "" }
* class Y { @TableColumnPropertyDecorator code = "" }
* ```
*
* 判据是「参数里有没有『类/原型 + 字符串属性名』」—— 有就是被当成装饰器直接调用了。
* 工厂形式先收到一份配置对象,此时返回**自身**,等下一次调用落到直用分支,
* 于是两种写法都不会抛 `… is not a function`。
*
* 配置类插件的**定义期**就执行装饰器,所以这里一旦崩,整个插件模块都求值不了 ——
* 表现是「脚本已执行但没拿到插件」,极容易误判成路径问题。这就是为什么它必须够宽容。
*/
function stubDecorator(...args: any[]): any {
const looksLikeDecoratorCall =
args.length >= 2 &&
(typeof args[0] === "function" || (typeof args[0] === "object" && args[0] !== null)) &&
typeof args[1] === "string";
if (looksLikeDecoratorCall) return args[2];
return stubDecorator;
}
export const TableColumnMethodDecorator = stubDecorator;
export const TableColumnPropertyDecorator = stubDecorator;
export const TableFormColumnPropertyDecorator = stubDecorator;
export const TableSearchFormPropertyDecorator = stubDecorator;
/* -------------------------------------------------------- 常量与工具 */
export const DEFAULT_DEFER_TYPES: any[] = [];
export const EVENT_PHASES: any[] = [];
export const FIXED_VALUES: any[] = [];
export const SAFE_SCRIPT_PATH = "";
/** 纯函数居多,给个「形状对得上」的空实现,够插件在预览里跑通非 UI 流程 */
export const toGlobalKey = (name: string): string => String(name).replace(/[^A-Za-z0-9_$]/g, "_");
export const normalizeFieldName = (name: string): string => String(name);
export const transformFields = (..._args: any[]): Record<string, any> => ({});
export const collectClassMembers = (..._args: any[]): any[] => [];
export const collectDataColumns = (..._args: any[]): any[] => [];
export const collectOperateGroups = (..._args: any[]): any[] => [];
export const collectToolbar = (..._args: any[]): any[] => [];
export const collectTypedTasks = (..._args: any[]): any[] => [];
export const sortTasksByPriority = (..._args: any[]): any[] => [];
export const buildOperateColumn = (..._args: any[]): any => null;
export const resolveScriptUrl = (..._args: any[]): string => "";
export const loadRemoteScript = async (..._args: any[]): Promise<void> => undefined;
export const clearRemoteScript = (): void => undefined;
/* ------------------------------------------------------ Proxy 兜底 */
/**
* `window.funjiaui` 的兜底实现(给 IIFE 插件用)。
*
* Proxy 能兜住**任意**名字,所以老插件里那些没被上面列全的 API 也不会抛错。
* 局限要说清楚:取到的值统一是「装饰器桩」形态 —— 当装饰器用没问题,
* 当组件渲染不行(组件需要 `render`/`setup`,不是普通函数)。
* 真遇到这种插件,就在上面补一个具名 `stubComponent`。
*/
export function createFunjiauiFallback(): any {
const cache = new Map<string, any>();
return new Proxy(
{ __previewStub: true },
{
get(_target, key) {
if (typeof key === "symbol") return undefined;
if (!cache.has(key)) cache.set(key, stubDecorator);
return cache.get(key);
},
has: () => true,
}
);
}
+534
View File
@@ -0,0 +1,534 @@
/**
* 预览界面的样式。
*
* 只作用于预览页本身,**不进插件产物** —— `preview/` 目录不参与
* `vite.config.ts` 的 lib 构建,所以这里的任何东西都不会被发布出去。
*
* 类名统一 `pv-` 前缀,避免与插件自己的样式(`hello-page__xxx` 那类)撞车 ——
* 预览里两者是同一个页面,撞了会很难判断问题在哪一边。
*/
* {
box-sizing: border-box;
}
html,
body {
margin: 0;
height: 100%;
}
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft YaHei", sans-serif;
font-size: 13px;
color: #1f2329;
background: #f5f7fa;
}
#app {
height: 100%;
}
.pv {
height: 100%;
display: flex;
flex-direction: column;
}
/* ------------------------------------------------------------- 顶栏 */
.pv-top {
flex: none;
background: #fff;
border-bottom: 1px solid #e4e7ed;
padding: 10px 16px 12px;
}
.pv-top__line {
display: flex;
align-items: center;
gap: 8px;
flex-wrap: wrap;
}
.pv-top__line + .pv-top__line {
margin-top: 6px;
}
.pv-top__name {
margin: 0;
font-size: 16px;
font-weight: 600;
}
.pv-top__id {
font-size: 12px;
color: #6b7280;
background: #f3f4f6;
border-radius: 4px;
padding: 1px 6px;
}
.pv-top__meta {
font-size: 12px;
color: #6b7280;
}
.pv-top__meta > span:not(:last-child)::after {
content: "·";
margin-left: 8px;
color: #d0d5dd;
}
.pv-top__time {
font-size: 12px;
color: #9aa1ac;
}
.pv-top__warn {
color: #b07d1f;
}
.pv-top__ops {
gap: 10px;
}
.pv-hint {
flex: none;
margin: 0;
padding: 6px 16px;
background: #f0f6ff;
border-bottom: 1px solid #e4e7ed;
color: #4b5563;
font-size: 12px;
}
/* ---------------------------------------------------------- 提示条 */
.pv-alert {
flex: none;
margin: 8px 16px 0;
width: auto;
}
/* ------------------------------------------------------ 主体两栏 */
.pv-body {
flex: 1;
min-height: 0;
display: flex;
gap: 12px;
padding: 12px 16px;
overflow: hidden;
}
.pv-side {
flex: none;
width: 232px;
overflow: auto;
background: #fff;
border: 1px solid #e4e7ed;
border-radius: 6px;
padding: 8px 10px 12px;
}
.pv-side section + section {
margin-top: 14px;
}
.pv-side h3 {
margin: 0 0 6px;
font-size: 12px;
font-weight: 600;
color: #4b5563;
}
.pv-side h3 em {
font-style: normal;
color: #9aa1ac;
font-weight: 400;
}
.pv-list {
margin: 0;
padding: 0;
list-style: none;
}
.pv-list li {
padding: 5px 8px;
border-radius: 4px;
cursor: pointer;
display: flex;
flex-direction: column;
gap: 1px;
line-height: 1.4;
}
.pv-list li:hover {
background: #f5f7fa;
}
.pv-list li.is-active {
background: #ecf5ff;
}
.pv-list__title {
font-weight: 500;
}
.pv-list li code {
font-size: 11px;
color: #9aa1ac;
}
.pv-list__empty {
cursor: default;
color: #b6bcc6;
font-size: 12px;
padding: 4px 8px;
}
.pv-list__empty:hover {
background: transparent;
}
.pv-main {
flex: 1;
min-width: 0;
display: flex;
flex-direction: column;
gap: 12px;
overflow: auto;
}
.pv-stage {
background: #fff;
border: 1px solid #e4e7ed;
border-radius: 6px;
}
.pv-stage__body {
padding: 14px;
}
/* 命令台不跟着页面一起长高,给它一个自己的滚动区 */
.pv-stage--cmd .pv-cmd__result {
max-height: 200px;
overflow: auto;
}
.pv-bar {
display: flex;
align-items: center;
gap: 10px;
padding: 7px 12px;
border-bottom: 1px solid #eef1f5;
background: #fafbfc;
border-radius: 6px 6px 0 0;
font-size: 12px;
}
.pv-bar__label {
font-weight: 600;
color: #4b5563;
}
.pv-bar code {
color: #6b7280;
}
.pv-bar .el-button {
margin-left: auto;
}
.pv-muted {
color: #9aa1ac;
font-size: 12px;
}
.pv-empty {
color: #9aa1ac;
padding: 28px 12px;
text-align: center;
line-height: 1.9;
}
.pv-empty p {
margin: 0;
}
.pv-empty code {
background: #f3f4f6;
border-radius: 3px;
padding: 1px 5px;
}
/* ------------------------------------------------------------ 命令台 */
.pv-cmd__form {
display: flex;
align-items: center;
gap: 8px;
flex-wrap: wrap;
padding: 10px 12px;
}
.pv-cmd__result {
margin: 0 12px 8px;
padding: 10px 12px;
background: #f7f8fa;
border: 1px solid #eef1f5;
border-radius: 5px;
font-family: Consolas, Menlo, monospace;
font-size: 12px;
line-height: 1.6;
white-space: pre-wrap;
word-break: break-word;
color: #1f2329;
}
.pv-cmd__result.is-error {
background: #fef0f0;
border-color: #fde2e2;
color: #c0392b;
}
.pv-cmd__ms {
padding: 0 12px 10px;
font-size: 11px;
color: #9aa1ac;
}
/* ------------------------------------------------------------ 底部 */
.pv-bottom {
flex: none;
height: 33vh;
display: flex;
flex-direction: column;
background: #fff;
border-top: 1px solid #e4e7ed;
padding: 0 16px;
overflow: hidden;
}
/* el-tabs 的内容区要能自己滚,否则日志长了会把整个页面顶长 */
.pv-bottom > .el-tabs__header {
margin: 0 0 6px;
}
.pv-bottom .el-tabs__content {
flex: 1;
min-height: 0;
overflow: auto;
}
.pv-bottom .el-tab-pane {
height: 100%;
display: flex;
flex-direction: column;
}
.pv-bottom .el-tabs__item em {
font-style: normal;
color: #9aa1ac;
font-size: 11px;
margin-left: 4px;
}
/* ------------------------------------------------------- 日志/事件台 */
.pv-lines {
flex: 1;
min-height: 0;
overflow: auto;
font-family: Consolas, Menlo, monospace;
font-size: 12px;
line-height: 1.75;
padding: 4px 0 10px;
}
.pv-line {
display: flex;
gap: 8px;
padding: 1px 4px;
border-radius: 3px;
}
.pv-line:hover {
background: #f7f8fa;
}
.pv-line__time {
flex: none;
color: #b6bcc6;
}
.pv-line__tag {
flex: none;
width: 42px;
text-align: center;
border-radius: 3px;
font-size: 11px;
line-height: 18px;
height: 18px;
background: #eef1f5;
color: #6b7280;
}
.pv-line__text {
min-width: 0;
word-break: break-word;
white-space: pre-wrap;
}
.pv-line.is-debug {
color: #9aa1ac;
}
.pv-line.is-info .pv-line__tag {
background: #ecf5ff;
color: #337ecc;
}
.pv-line.is-warn .pv-line__tag {
background: #fdf6ec;
color: #b07d1f;
}
.pv-line.is-warn .pv-line__text {
color: #a06d1f;
}
.pv-line.is-error .pv-line__tag {
background: #fef0f0;
color: #c0392b;
}
.pv-line.is-error .pv-line__text {
color: #c0392b;
}
.pv-line.is-ui .pv-line__tag {
background: #f0f9eb;
color: #529b2e;
}
.pv-line.is-event .pv-line__tag {
background: #f4f0ff;
color: #6b4fc4;
}
.pv-line__empty {
color: #b6bcc6;
padding: 6px 4px;
}
/* ------------------------------------------------------------ 扩展点 */
.pv-ext {
display: flex;
gap: 24px;
padding: 6px 2px 12px;
}
.pv-ext__col {
flex: 1;
min-width: 0;
}
.pv-ext h4 {
margin: 12px 0 4px;
font-size: 12px;
font-weight: 600;
color: #4b5563;
}
.pv-ext h4 em {
font-style: normal;
color: #9aa1ac;
font-weight: 400;
}
.pv-ext ul {
margin: 0;
padding-left: 18px;
color: #4b5563;
line-height: 1.8;
}
.pv-note {
margin: 4px 0 0;
color: #6b7280;
font-size: 12px;
line-height: 1.8;
}
.pv-note code {
background: #f3f4f6;
border-radius: 3px;
padding: 1px 4px;
}
/* ---------------------------------------------------------- 登录区 */
/* 顶栏最右:用 margin-left:auto 推开,而不是给左侧那一串按钮加 flex ——
* 左侧按钮的数量会随装载状态变(1 个还是 4 个),靠自动外边距最稳 */
.pv-auth {
margin-left: auto;
display: flex;
align-items: center;
gap: 8px;
}
.pv-login__tip {
margin: 0 0 12px;
font-size: 12px;
line-height: 1.7;
color: #6b7280;
}
.pv-login__tip code {
background: #f3f4f6;
border-radius: 3px;
padding: 1px 4px;
}
.pv-login__demos {
margin-top: 12px;
display: flex;
align-items: center;
gap: 8px;
flex-wrap: wrap;
}
.pv-login__demo {
cursor: pointer;
}
/* ---------------------------------------------------------- 存储视图 */
.pv-kv {
padding: 4px 2px 12px;
}
.pv-kv__row {
display: flex;
gap: 12px;
padding: 3px 4px;
border-bottom: 1px solid #f5f7fa;
font-family: Consolas, Menlo, monospace;
font-size: 12px;
}
.pv-kv__row code {
flex: none;
width: 180px;
color: #6b7280;
}
.pv-kv__row span {
min-width: 0;
word-break: break-word;
}