web-extend-plugin-vue2 0.2.3 → 0.3.0

package/index.d.ts

@@ -37,7 +37,7 @@ export type InterceptRegisterRoutesFn = (ctx: {
   pluginId: string
   router: unknown
   routes: ReadonlyArray<VueRouteConfig>
-  /** 与默认 `registerRoutes` 相同的包装 + `addRoute` / `addRoutes` */
+  /** 与默认 `registerRoutes` 相同的包装 + `router.addRoute` */
   applyInternalRegister: (routes: VueRouteConfig[]) => void
 }) => void
 
@@ -48,7 +48,38 @@ export type AdaptRouteDeclarationsFn = (ctx: {
   declarations: ReadonlyArray<RouteDeclaration>
 }) => VueRouteConfig[]
 
+/** 宿主在 `resolveRuntimeOptions({ hostContext })` 中注入；经浅冻结后由 `hostApi.hostContext` 只读暴露 */
+export type HostContext = Readonly<Record<string, unknown>>
+
+export type OnBeforePluginActivateFn = (ctx: {
+  pluginId: string
+  router: unknown
+  pluginRecord: Readonly<Record<string, unknown>>
+}) => void | Promise<void>
+
+export type OnAfterPluginActivateFn = (ctx: {
+  pluginId: string
+  router: unknown
+  pluginRecord: Readonly<Record<string, unknown>>
+  hostApi: unknown
+}) => void | Promise<void>
+
+export type OnPluginActivateErrorFn = (ctx: {
+  pluginId: string
+  error: unknown
+  pluginRecord: Readonly<Record<string, unknown>>
+  hostApi: unknown
+}) => void | Promise<void>
+
 /** 宿主传入 `createHostApi` 的 `hostKit`（及 `resolveRuntimeOptions` 中同类字段） */
+/** {@link createVueCliAxiosQuickInstallOptions} / {@link installVueCliAxiosWebPlugins} 的宿主侧依赖 */
+export type VueCliAxiosQuickDeps = {
+  request: (config: Record<string, unknown>) => Promise<unknown>
+  hostLayoutComponent: unknown
+  store?: unknown
+  hostContext?: Record<string, unknown>
+}
+
 export type HostKitOptions = {
   /** `getBridge().request` 允许的URL路径前缀，须以 `/` 开头 */
   bridgeAllowedPathPrefixes?: string[]
@@ -57,6 +88,8 @@ export type HostKitOptions = {
   transformRoutes?: TransformRoutesFn
   interceptRegisterRoutes?: InterceptRegisterRoutesFn
   adaptRouteDeclarations?: AdaptRouteDeclarationsFn
+  /** 由引导流程浅冻结后传入各插件的 `hostApi.hostContext` */
+  hostContext?: HostContext
 }
 
 /** `resolveRuntimeOptions` 全量运行时选项（在默认字段基础上的扩展；未列字段见 README） */
@@ -64,7 +97,23 @@ export type WebExtendPluginRuntimeOptions = HostKitOptions &
   Record<string, unknown> & {
     manifestBase?: string
     manifestListPath?: string
+    /** 默认 `api`；`static` 时用 `staticManifestUrl` 拉取聚合 JSON，不请求 Java 清单接口 */
+    manifestMode?: 'api' | 'static'
+    /** 静态清单 URL（绝对或站点内路径），`manifestMode: 'static'` 时必填（或配置环境变量） */
+    staticManifestUrl?: string
+    /** `manifestMode=api` 且开发环境：API 失败或 `plugins` 为空时是否尝试 `devFallbackStaticManifestUrl`（默认 true） */
+    devManifestFallback?: boolean
+    /** 开发回退静态清单路径，默认 `/web-plugins/plugins.manifest.json` */
+    devFallbackStaticManifestUrl?: string
     manifestFetchCredentials?: RequestCredentials
+    /** 宿主 Layout，传入后自动注册 `pluginMountPath` 壳路由 */
+    hostLayoutComponent?: unknown
+    /** 插件 URL 前缀，默认 `/plugin` */
+    pluginMountPath?: string
+    /** 壳路由 meta */
+    pluginHostRouteMeta?: Record<string, unknown>
+    /** 为 true 时且配置了 `pluginRoutesParentName` + `hostLayoutComponent` 才自动注册壳路由；默认 false */
+    ensurePluginHostRoute?: boolean
     isDev?: boolean
     webPluginDevOrigin?: string
     webPluginDevIds?: string
@@ -77,19 +126,27 @@ export type WebExtendPluginRuntimeOptions = HostKitOptions &
     allowedScriptHosts?: string[]
     bootstrapSummary?: boolean
     fetchManifest?: ManifestFetchFn
+    /** 插件通过 `hostApi.hostContext` 只读访问（浅冻结拷贝）；如 `{ store, i18n }` */
+    hostContext?: Record<string, unknown>
+    /** 调用 `activator` 之前；抛出异常将跳过该插件并计入失败 */
+    onBeforePluginActivate?: OnBeforePluginActivateFn
+    /** `activator` 成功返回后 */
+    onAfterPluginActivate?: OnAfterPluginActivateFn
+    /** `activator` 抛错后；用于埋点/降级，不应再抛错（再抛仅记录 warn） */
+    onPluginActivateError?: OnPluginActivateErrorFn
   }
 
 /** 插件 `activator` 收到的宿主 API */
 export interface HostApi {
   /** 宿主实现的 Host API 协议版本，与清单 `hostPluginApiVersion` 对齐 */
   readonly hostPluginApiVersion: string
+  /** 宿主注入上下文（`resolveRuntimeOptions.hostContext` 的浅冻结快照）；无则 `{}` */
+  readonly hostContext: HostContext
   /**
    * 动态注册路由。含 PRD 时使用 `componentRef` 树；否则传入 `RouteConfig` 数组。
    * 流水线：`adaptRouteDeclarations` → `transformRoutes` → `interceptRegisterRoutes` 或默认注册。
    */
   registerRoutes(routes: VueRouteConfig[] | RouteDeclaration[]): void
-  /** 写入全局菜单注册表，按 `order` 升序 */
-  registerMenuItems(items: Record<string, unknown>[]): void
   registerSlotComponents(
     pointId: string,
     components: Array<{ component: unknown; priority?: number }>
@@ -124,6 +181,29 @@ export type ManifestFetchCacheOptions = {
   now?: () => number
 }
 
+/** 从路由 meta 推导的菜单节点（供宿主侧栏；与 `buildMenuDescriptorsFromRoutes` 配套） */
+export type PluginMenuDescriptor = {
+  path: string
+  name?: string | symbol
+  title: string
+  order: number
+  pluginId?: string
+  icon?: unknown
+  permission?: unknown
+  hidden?: boolean
+  external?: boolean
+  children?: PluginMenuDescriptor[]
+}
+
+/** 由插件 `RouteConfig` 树生成菜单描述（不含 component） */
+export function buildMenuDescriptorsFromRoutes(
+  routes: VueRouteConfig[],
+  pluginId?: string
+): PluginMenuDescriptor[]
+
+/** 调试：返回 `registerRoutes` 为该插件登记的顶层 route name */
+export function getRegisteredTopRouteNamesForPlugin(pluginId: string): string[]
+
 /** 命名空间聚合对象，按领域分组 */
 export const WebExtendPluginVue2: Readonly<{
   install: (Vue: unknown, router: unknown, options?: WebExtendPluginRuntimeOptions) => Promise<void>
@@ -135,6 +215,7 @@ export const WebExtendPluginVue2: Readonly<{
       runtimeOptions?: WebExtendPluginRuntimeOptions
     ) => Promise<void>
     resolveRuntimeOptions: (user?: WebExtendPluginRuntimeOptions) => WebExtendPluginRuntimeOptions
+    ensurePluginHostRoute: (router: unknown, opts: WebExtendPluginRuntimeOptions) => void
     defaultFetchWebPluginManifest: (ctx: {
       manifestUrl: string
       credentials: RequestCredentials
@@ -153,10 +234,17 @@ export const WebExtendPluginVue2: Readonly<{
       request: (path: string, init?: RequestInit) => Promise<Response>
     }
     registries: unknown
+    buildMenuDescriptorsFromRoutes: typeof buildMenuDescriptorsFromRoutes
+    getRegisteredTopRouteNamesForPlugin: typeof getRegisteredTopRouteNamesForPlugin
   }>
   config: Readonly<{
     defaultWebExtendPluginRuntime: Record<string, unknown>
     setWebExtendPluginEnv: (env: Record<string, unknown> | null | undefined) => void
+    webExtendPluginEnvKeys: Readonly<Record<string, string>>
+    defaultManifestFetchCache: Readonly<{ storageKeyPrefix: string; maxEntries: number }>
+    defaultManifestMode: string
+    routeSynthNamePrefix: string
+    peerMinimumVersions: Readonly<{ vue: string; vueRouter: string }>
   }>
   constants: Readonly<{ HOST_PLUGIN_API_VERSION: string; RUNTIME_CONSOLE_LABEL: string }>
   components: Readonly<{ ExtensionPoint: unknown }>
@@ -168,6 +256,12 @@ export const WebExtendPluginVue2: Readonly<{
         deps: { request: (config: Record<string, unknown>) => Promise<unknown> },
         extra?: Record<string, unknown>
       ) => Record<string, unknown>
+      createQuickInstallOptions: (
+        router: unknown,
+        deps: VueCliAxiosQuickDeps,
+        extra?: Record<string, unknown>
+      ) => Record<string, unknown>
+      defaultJavaManifestListPath: string
       manifestPathForApiBase: (manifestUrl: string, apiBase?: string) => string
       unwrapManifestBody: (body: unknown) => object | null
     }>
@@ -176,6 +270,19 @@ export const WebExtendPluginVue2: Readonly<{
 
 export const defaultWebExtendPluginRuntime: Record<string, unknown>
 
+/** 与 `resolveRuntimeOptions` / `build-env` 读取逻辑一致的环境变量键（文档与宿主检索用） */
+export const webExtendPluginEnvKeys: Readonly<Record<string, string>>
+
+export const defaultManifestFetchCache: Readonly<{ storageKeyPrefix: string; maxEntries: number }>
+
+export const defaultManifestMode: 'api'
+
+/** 无 name 的路由由 `createHostApi` 合成的名称前缀 */
+export const routeSynthNamePrefix: string
+
+/** 与 package.json peer 下限一致，供 CI / `test:peer-min` 对齐 */
+export const peerMinimumVersions: Readonly<{ vue: string; vueRouter: string }>
+
 /** 拉取清单并依次激活插件；浏览器环境执行 */
 export function bootstrapPlugins(
   router: unknown,
@@ -186,6 +293,8 @@ export function bootstrapPlugins(
 /** 合并默认配置、环境变量与显式传入字段 */
 export function resolveRuntimeOptions(user?: WebExtendPluginRuntimeOptions): WebExtendPluginRuntimeOptions
 
+export function ensurePluginHostRoute(router: unknown, opts: WebExtendPluginRuntimeOptions): void
+
 export function defaultFetchWebPluginManifest(ctx: {
   manifestUrl: string
   credentials: RequestCredentials
@@ -213,8 +322,25 @@ export function installWebExtendPluginVue2(
   options?: WebExtendPluginRuntimeOptions
 ): Promise<void>
 
+/** Vue CLI + axios 一键安装；默认 `exposeGlobalVue: true` 写入 `window.Vue` */
+export function installVueCliAxiosWebPlugins(
+  Vue: unknown,
+  router: unknown,
+  deps: VueCliAxiosQuickDeps,
+  extra?: WebExtendPluginRuntimeOptions & { exposeGlobalVue?: boolean }
+): Promise<void>
+
 export const ExtensionPoint: unknown
 
+/** 常见 Java 清单路径段，与 `manifestBase` 拼接 */
+export const defaultVueCliJavaManifestListPath: string
+
+export function createVueCliAxiosQuickInstallOptions(
+  router: unknown,
+  deps: VueCliAxiosQuickDeps,
+  extra?: Record<string, unknown>
+): Record<string, unknown>
+
 export function createVueCliAxiosInstallOptions(
   deps: { request: (config: Record<string, unknown>) => Promise<unknown> },
   extra?: Record<string, unknown>
@@ -227,6 +353,8 @@ export const presetVueCliAxios: Readonly<{
   id: string
   description: string
   createInstallOptions: typeof createVueCliAxiosInstallOptions
+  createQuickInstallOptions: typeof createVueCliAxiosQuickInstallOptions
+  defaultJavaManifestListPath: typeof defaultVueCliJavaManifestListPath
   manifestPathForApiBase: typeof resolveManifestPathUnderApiBase
   unwrapManifestBody: typeof unwrapNestedManifestBody
 }>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-extend-plugin-vue2",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -22,7 +22,7 @@
   ],
   "peerDependencies": {
     "vue": ">=2.6.14 <3.0.0",
-    "vue-router": ">=3.2.0 <4.0.0"
+    "vue-router": ">=3.5.0 <4.0.0"
   },
   "dependencies": {
     "semver": "^7.6.3"
@@ -30,12 +30,19 @@
   "devDependencies": {
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/node": "^22.10.2",
     "rollup": "^4.28.0",
-    "vitest": "^2.1.9"
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9",
+    "vue": "^2.7.16",
+    "vue-router": "^3.6.5"
   },
   "scripts": {
     "build": "rollup -c rollup.config.mjs",
     "test": "vitest run",
+    "test:peer-min": "npm install --no-save vue@2.6.14 vue-router@3.5.4 && npm run build && npm test && npm install",
     "prepublishOnly": "npm run build && npm run test"
   },
   "license": "Apache-2.0",