web-extend-plugin-vue2 0.2.1 → 0.2.3

package/README.md

@@ -1,47 +1,36 @@
 # web-extend-plugin-vue2
 
-面向 **Vue 2.6+** / **Vue Router 3.x** 宿主的 **Web 前端扩展插件**运行时。在浏览器中拉取插件清单、加载入口脚本、注入 **`hostApi`**（路由 / 菜单 / 扩展点 / 受控请求桥等），并提供 **`ExtensionPoint`** 在布局中挂载插件视图。与后端清单服务、静态资源目录约定配套使用（如 `extend-plugin-framework` 中的 `plugin-web-starter`）。
+面向 **Vue 2.6+** 与 **Vue Router 3** 的 Web 插件运行时：浏览器中拉取**插件清单**、加载入口脚本、执行 `activator(hostApi)`，并提供 **`ExtensionPoint`**、菜单/路由注册表与受控 **`getBridge()`**。发布物为预构建的 **`dist/`**（CJS/ESM），类型见根目录 **`index.d.ts`**。
 
-## 包形态与兼容性
+**Peer：`vue` ^2.6.14 \<3，`vue-router` ^3.2 \<4。**
 
-- **发布入口为预构建的 `dist/`（CJS + ESM）**，不含 `.vue` 源码、**运行时无 `import.meta` 语法**，避免 Vue CLI / Webpack 4 宿主再配 `transpileDependencies`、Babel `import.meta` 补丁等与版本强耦合的改动。包内存在模块顶层初始化（如 `registries` 的 `Vue.observable`），**不**声明 `sideEffects: false`，以免宿主打包器误裁剪。
-- **Webpack 4 / Vue CLI 4**：`package.json` **不**再声明 `module` 字段，默认解析 **`main` → `dist/index.cjs`**，由 Webpack 正常注入 `require`，避免误选 `index.mjs` 后在浏览器中出现 `require is not defined`。支持 `package.json` **`exports`** 的 Webpack 5、Vite、Rollup 等仍通过 **`import` 条件**使用 `dist/index.mjs`。
-- **peer**：`vue` `>=2.6.14 <3`，`vue-router` `>=3.2.0 <4`（与 2.6 / 2.7 主流栈对齐，减轻版本地狱）。
-- **Vite 宿主**：通过 `env: import.meta.env` 或 `setWebExtendPluginEnv(import.meta.env)` 注入环境，即可读取文档中的 `VITE_*` 键。
+---
 
-## 安装
+## 如何使用
 
-```bash
-npm add web-extend-plugin-vue2 vue@^2.7 vue-router@^3.6
-```
-
-（Vue 2.6 项目请将 `vue` / `vue-template-compiler` 与 `vue-router` 保持与现有工程一致即可。）
-
-## 推荐：一键接入
+**一键接入**（注册全局 `ExtensionPoint` 并异步拉清单）：
 
 ```js
-import Vue from 'vue'
-import router from './router'
 import { installWebExtendPluginVue2 } from 'web-extend-plugin-vue2'
 
-// Vue CLI：manifestBase 常与 VUE_APP_* 接口前缀一致
 installWebExtendPluginVue2(Vue, router, {
-  manifestBase: process.env.VUE_APP_BASE_API
+  manifestBase: '/fp-api', // 或与网关一致的前缀
+  env: import.meta.env // Vite：可选，便于读取 VITE_*
 }).catch(console.warn)
-
-// Vite：传入 env 以支持 VITE_* 环境变量
-// installWebExtendPluginVue2(Vue, router, {
-//   env: import.meta.env,
-//   manifestBase: import.meta.env.VITE_FRONTEND_PLUGIN_BASE
-// }).catch(console.warn)
 ```
 
-布局中使用：`<ExtensionPoint point-id="..." />`（已由 `installWebExtendPluginVue2` 全局注册）。
+**Vue CLI + 已有 axios `request`**（清单走宿主登录态）：
+
+```js
+import { installWebExtendPluginVue2, createVueCliAxiosInstallOptions } from 'web-extend-plugin-vue2'
+import request from '@/utils/request'
+
+installWebExtendPluginVue2(Vue, router, createVueCliAxiosInstallOptions({ request })).catch(console.warn)
+```
 
-## 进阶：按需组合
+**按需组合**（自行注册 `ExtensionPoint`、控制引导时机）：
 
 ```js
-import Vue from 'vue'
 import {
   bootstrapPlugins,
   createHostApi,
@@ -50,92 +39,67 @@ import {
 } from 'web-extend-plugin-vue2'
 
 Vue.component('ExtensionPoint', ExtensionPoint)
-
-const runtime = resolveRuntimeOptions({
-  // 按需覆盖，见 defaultWebExtendPluginRuntime
-})
-
+const runtime = resolveRuntimeOptions({ manifestBase: '/fp-api' })
 bootstrapPlugins(router, (id, r, kit) => createHostApi(id, r, kit), runtime).catch(console.warn)
 ```
 
-清单请求 URL 为 **`manifestBase` + `manifestListPath`**（默认 `/fp-api` + `/api/frontend-plugins`）。工厂请使用 **`(id, r, kit) => createHostApi(id, r, kit)`**，以便 bridge 白名单等配置生效。
+清单请求地址：**`manifestBase` + `manifestListPath`**（默认路径段为 `/api/frontend-plugins`）。工厂请使用 **`(id, r, kit) => createHostApi(id, r, kit)`**，以便 `bridgeAllowedPathPrefixes` 等传入 `hostApi`。
 
-## 配置与默认值
+---
 
-**优先级（后者覆盖前者）**：`resolveRuntimeOptions` 传入对象中的显式字段 → **注入环境**（`setWebExtendPluginEnv` / `globalThis.__WEP_ENV__` / `install` 的 `env`）→ `process.env`（Webpack `DefinePlugin` 等）→ **`defaultWebExtendPluginRuntime`**。
+## 主要配置（`resolveRuntimeOptions` / `install` 同源字段）
 
-**环境变量命名**：文档以 **`VITE_*`** 为准；每个键都有等价的 **`PLUGIN_*`**（把前缀 `VITE_` 换成 `PLUGIN_`）。在 **Webpack** 中可将同名键通过 `DefinePlugin` 挂到 `process.env`；在 **Vite** 中请使用 `installWebExtendPluginVue2(..., { env: import.meta.env })` 或先调用 `setWebExtendPluginEnv(import.meta.env)`，并在 `defineConfig` 中配置 `envPrefix`（如含 `PLUGIN_`）以便变量进入 `import.meta.env`。
+| 字段 | 作用 |
+|------|------|
+| `manifestBase` | 清单服务 URL 前缀（无尾 `/`），默认 `/fp-api` |
+| `manifestListPath` | 清单路径段（以 `/` 开头），拼在 `manifestBase` 后 |
+| `manifestFetchCredentials` | 拉清单时 `fetch` 的 `credentials`，默认 `include` |
+| `fetchManifest` | 自定义清单请求 `(ctx) => Promise<{ ok, data?, error? }>` |
+| `bridgeAllowedPathPrefixes` | `hostApi.getBridge().request(path)` 允许的 path 前缀 |
+| `allowedScriptHosts` | 允许加载插件脚本的主机名白名单 |
+| `isDev` / `webPluginDevOrigin` 等 | 开发态隐式 dev 入口与 SSE，见类型定义 |
+| `pluginRoutesParentName` | 插件子路由挂到的**已有**命名父路由 |
+| `adaptRouteDeclarations` / `transformRoutes` / `interceptRegisterRoutes` | 路由 PRD 适配与宿主扩展流水线 |
 
-**`isDev`**：未在对象里写 `isDev` 时，先判断注入环境中的 `DEV === true`，否则使用 `process.env.NODE_ENV === 'development'`。
+环境：Vite 可在入口调用 **`setWebExtendPluginEnv(import.meta.env)`**，或在 options 里传 **`env`**。键名支持 **`VITE_*`** 与等价 **`PLUGIN_*`**（实现内会解析）。
 
-### `resolveRuntimeOptions` / `defaultWebExtendPluginRuntime` 字段
+---
 
-| 字段 | 类型 | 默认值 | 作用 |
-|------|------|--------|------|
-| `manifestBase` | `string` | `/fp-api` | 清单与代理前缀（不含尾部 `/`），与后端 context-path 对齐 |
-| `manifestListPath` | `string` | `/api/frontend-plugins` | 清单接口路径（以 `/` 开头），完整请求 URL = `manifestBase` + `manifestListPath` |
-| `manifestFetchCredentials` | `string` | `include` | 拉清单时 `fetch` 的 `credentials`：`include` / `same-origin` / `omit` |
-| `isDev` | `boolean` | 见上 | 是否开发模式；影响隐式 dev 映射、SSE 等 |
-| `webPluginDevOrigin` | `string` | `''` | 插件 dev 服务 origin，如 `http://localhost:5188`；空则不做隐式 dev ping |
-| `webPluginDevIds` | `string` | `''` | 逗号分隔插件 id；有值且 ping 成功时生成隐式 dev 入口映射 |
-| `webPluginDevMapJson` | `string` | `''` | JSON 字符串：`{ "插件id": "完整入口URL" }`，与隐式映射合并，**显式覆盖同 id** |
-| `webPluginDevEntryPath` | `string` | `/src/plugin-entry.js` | 隐式映射里各 id 对应的入口路径（相对 `webPluginDevOrigin`）；Webpack dev 可改为 `/dist/main.js` 等 |
-| `devPingPath` | `string` | `/__web_plugin_dev_ping` | 拼在 `webPluginDevOrigin` 后的存活探测路径 |
-| `devReloadSsePath` | `string` | `/__web_plugin_reload_stream` | 插件 dev 热更新 SSE 路径（相对各 dev 入口的 origin） |
-| `devPingTimeoutMs` | `number` | `500` | dev ping 超时（毫秒） |
-| `defaultImplicitDevPluginIds` | `string[]` | `[]` | 未配置 `webPluginDevIds` 且未设对应 env 时，隐式 dev 使用的 id 列表 |
-| `allowedScriptHosts` | `string[]` | `localhost`、`127.0.0.1`、`::1` | 允许加载插件脚本（`<script>` / 动态 `import`）的主机名 |
-| `bridgeAllowedPathPrefixes` | `string[]` | `['/api/']` | `hostApi.getBridge().request(path)` 允许的 URL 前缀（须以 `/` 开头） |
-| `bootstrapSummary` | `boolean` \| `undefined` | `undefined` | 是否打印 bootstrap 结束摘要；`undefined` 时由 `VITE_PLUGINS_BOOTSTRAP_SUMMARY` 或开发模式决定 |
+## 功能示例）
 
-### 环境变量一览（`PLUGIN_*` 同名等价）
+**布局里开槽**（插件通过 `hostApi.registerSlotComponents('your.point.id', [...])` 注入组件）：
 
-| 环境变量（`PLUGIN_…` 同理） | 作用 |
-|-----------------------------|------|
-| `VITE_FRONTEND_PLUGIN_BASE` | `manifestBase` |
-| `VITE_WEB_PLUGIN_MANIFEST_PATH` | `manifestListPath` |
-| `VITE_WEB_PLUGIN_MANIFEST_CREDENTIALS` | `manifestFetchCredentials`（仅上述三取值） |
-| `VITE_WEB_PLUGIN_DEV_ORIGIN` | `webPluginDevOrigin` |
-| `VITE_WEB_PLUGIN_DEV_IDS` | `webPluginDevIds`（逗号分隔） |
-| `VITE_WEB_PLUGIN_DEV_MAP` | `webPluginDevMapJson` |
-| `VITE_WEB_PLUGIN_DEV_ENTRY` | `webPluginDevEntryPath` |
-| `VITE_WEB_PLUGIN_DEV_PING_PATH` | `devPingPath` |
-| `VITE_WEB_PLUGIN_DEV_SSE_PATH` | `devReloadSsePath` |
-| `VITE_WEB_PLUGIN_DEV_PING_TIMEOUT_MS` | `devPingTimeoutMs`（正整数） |
-| `VITE_WEB_PLUGIN_IMPLICIT_DEV_IDS` | 逗号分隔 → `defaultImplicitDevPluginIds`（仅当未在对象里传数组时） |
-| `VITE_WEB_PLUGIN_ALLOWED_SCRIPT_HOSTS` | 逗号分隔主机名 → `allowedScriptHosts` |
-| `VITE_WEB_PLUGIN_BRIDGE_PREFIXES` | 逗号分隔路径前缀 → `bridgeAllowedPathPrefixes` |
-| `VITE_PLUGINS_BOOTSTRAP_SUMMARY` | `0`/`false` 关闭摘要；`1`/`true` 强制开启；未设时在开发模式默认开启 |
-
-### 其它导出
+```vue
+<ExtensionPoint point-id="app.toolbar.demo" />
+```
 
-- **`setWebExtendPluginEnv(env)`**：Vite 入口显式注入与 `import.meta.env` 同形态对象。
-- **`HOST_PLUGIN_API_VERSION`**：宿主与插件约定的 API 版本字符串（与后端清单字段对齐），非 `resolveRuntimeOptions` 配置项。
+**读全局菜单**（插件 `registerMenuItems` 写入响应式表）：
 
-## 发布与本地开发
+```js
+import { registries } from 'web-extend-plugin-vue2'
+// computed: { menus() { return registries.menus } }
+```
 
-- **npm 发布的包**：`prepublishOnly` 会执行 `npm run build && npm test`，打包容器内已含 **`dist/`**；宿主安装时**不会**再跑构建，也**不需要**本包的 Rollup（避免依赖安装阶段因缺少 devDependencies 而失败）。
-- **从仓库 / `file:` 路径引用**：请先在包目录执行 **`npm install && npm run build`**，保证存在 `dist/`，或将 **`dist/` 纳入版本库**后再被其它项目引用。
+**路由扩展（宿主）**：在 `resolveRuntimeOptions` 里提供 `transformRoutes` 或 `adaptRouteDeclarations`，插件在 `activator` 第二个参数中取冻结的 **`pluginRecord`**（可含清单里的 `routeDeclarations`）。
 
-## 卸载
+**卸载插件**：
 
 ```js
 import { disposeWebPlugin } from 'web-extend-plugin-vue2'
-
-disposeWebPlugin('your.plugin.id')
+disposeWebPlugin('com.your.plugin.id')
 ```
 
-Vue Router 3 无公开 `removeRoute`，动态路由卸载后可能需整页刷新。
+---
+
+## API 浏览
 
-## 版本纪要
+- **具名导出**：与下述命名空间指向同一实现，便于 tree-shaking。
+- **`WebExtendPluginVue2`**：`install`、`runtime`（含 `bootstrapPlugins`、`resolveRuntimeOptions`、`wrapManifestFetchWithCache` 等）、`host`、`config`、`constants`、`components`、`presets`（`vueCliAxios`）。
 
-### 0.2.1
+更细的签名与说明以 **`index.d.ts`** 为准。
 
-- **Webpack 4 / Vue CLI**：去掉 `package.json` 的 `module` 字段，默认走 **`main`（CJS）**，避免误解析 `index.mjs` 导致浏览器端 `require is not defined`。
-- **`exports`**：补充 `default` 指向 CJS，便于仅部分实现 `exports` 条件的工具链兜底。
-- **语法兼容**：源码避免 `??` 等 Webpack 4 解析 `node_modules` 内 CJS 时可能不支持的语法，便于无 `transpileDependencies` 开箱接入。
+---
 
-## 仓库与协议
+## 仓库
 
-- 源码：[extend-plugin-framework / web-extend-plugin-vue2](https://github.com/xtemplus/extend-plugin-framework/tree/master/web-extend-plugin-vue2)
-- 许可证：Apache-2.0
+<https://github.com/xtemplus/extend-plugin-framework/tree/master/web-extend-plugin-vue2> · Apache-2.0