feat: 新增 asVuePlugin 函数用于代替 createVueRouterPlugin 的作用

l246804 · l246804 · commit 6c0a4c600d42 · 2025-07-06T22:15:30.000+08:00
- 新增 `asVuePlugin` 函数，用于将 RouterPlugin 转换为 Vue 插件
- 标记 `createVueRouterPlugin` 为弃用 API，并推荐使用 `asVuePlugin` 代替
- 更新了 README 和相关文档，明确了两种插件模式的使用方法
diff --git a/README.md b/README.md
@@ -8,11 +8,11 @@ A lightweight solution providing standardized plugin system for Vue Router.
 
 ## 🌟 Core Features
 
-| Feature                                | Description                                                                    |
-| -------------------------------------- | ------------------------------------------------------------------------------ |
-| 🧱 **Standardized Plugin Interface**   | Unified plugin development specification with auto-registration/uninstallation |
-| 🔁 **Reactive Side-effect Management** | Automatic tracking/cleanup of plugin's reactive side-effects                   |
-| ⚖️ **Dual-mode Compatibility**         | Support both Vue Router plugin system and Vue plugin system                    |
+| Feature                                | Description                                                                      |
+| -------------------------------------- | -------------------------------------------------------------------------------- |
+| 🧱 **Standardized Plugin Interface**   | Unified plugin development specification with auto-registration/uninstallation   |
+| 🔁 **Reactive Side-effect Management** | Automatic tracking/cleanup of plugin's reactive side-effects                     |
+| ⚖️ **Dual-mode Compatibility**         | Supports both Vue Router plugin system and Vue plugin system compatibility modes |
 
 ---
 
@@ -26,7 +26,7 @@ npm install vue-router-plugin-system
 
 ## 🚀 Getting Started
 
-### Mode 1: Vue Router Plugin (Recommended)
+### Mode 1: Vue Router Plugin Mode (Recommended)
 
 **1. Plugin Development**
 
@@ -70,37 +70,39 @@ const router = createRouter({
 router.isNavigating.value
 ```
 
-### Mode 2: Vue Plugin (Compatibility)
+### Mode 2: Vue Plugin Mode (Compatibility)
 
-**1. Create Vue Plugin**
+**1. Plugin Development**
 
 ```ts
-import { createVueRouterPlugin } from 'vue-router-plugin-system'
+import type { RouterPlugin } from 'vue-router-plugin-system'
+import { ref } from 'vue'
 
-export const NavigationStatePlugin = createVueRouterPlugin((ctx) => {
-  // Same implementation logic as above
-})
+export const NavigationStatePlugin: RouterPlugin = (ctx) => {
+  // Implementation logic remains the same
+}
 ```
 
 **2. Application Integration**
 
 ```ts
 // main.ts
+import { asVuePlugin } from 'vue-router-plugin-system'
+
 const app = createApp(App)
 app.use(router) // Mount router first
-app.use(NavigationStatePlugin) // Register plugin later
+app.use(asVuePlugin(NavigationStatePlugin)) // Register plugin later
 ```
 
 ---
 
 ## ⚠️ Mode Comparison
 
-| Feature                   | Vue Router Plugin                | Vue Plugin                      |
-| ------------------------- | -------------------------------- | ------------------------------- |
-| Initialization Order      | Prior to app logic               | Dependent on client usage order |
-| Navigation Guard Priority | Higher                           | Dependent on registration order |
-| Reactive Management       | Automatic cleanup                | Automatic cleanup               |
-| Dependency Requirement    | Requires this lib's createRouter | No dependency required          |
+| Feature              | Vue Router Plugin Mode     | Vue Plugin Mode               |
+| -------------------- | -------------------------- | ----------------------------- |
+| Initialization Order | Prioritized over app logic | Depends on client usage order |
+| Guard Priority       | Higher priority            | Depends on registration order |
+| Reactive Management  | Auto-cleanup               | Auto-cleanup                  |
 
 ---
 
@@ -113,11 +115,11 @@ interface RouterPluginContext {
    */
   router: Router
   /**
-   * Execute callback with vue app instance
+   * Execute callback with Vue app instance
    */
   runWithApp: (handler: RouterPluginRunWithAppHandler) => void
   /**
-   * Register uninstall callback (can be called multiple times)
+   * Register uninstallation callback (supports multiple calls)
    */
   onUninstall: (handler: RouterPluginUninstallHandler) => void
 }
@@ -128,24 +130,17 @@ interface RouterPlugin {
    */
   (ctx: RouterPluginContext): void
 }
-
-interface VueRouterPlugin extends RouterPlugin {
-  /**
-   * Vue plugin installation function
-   */
-  install: (app: App) => void
-}
 ```
 
 ---
 
-## 🤝 Contribution Guidelines
+## 🤝 Contribution Guide
 
-Contributions welcome! Please ensure:
+Contributions are welcome! Please ensure:
 
-1. Pass all unit tests
-2. Maintain TypeScript type integrity
-3. Add necessary documentation
+1. All unit tests pass
+2. TypeScript type integrity maintained
+3. Necessary documentation added
 
 ## License
 
diff --git a/README.zh_CN.md b/README.zh_CN.md
@@ -72,35 +72,37 @@ router.isNavigating.value
 
 ### 模式二：Vue 插件模式（兼容方案）
 
-**1. 创建 Vue 插件**
+**1. 开发插件**
 
 ```ts
-import { createVueRouterPlugin } from 'vue-router-plugin-system'
+import type { RouterPlugin } from 'vue-router-plugin-system'
+import { ref } from 'vue'
 
-export const NavigationStatePlugin = createVueRouterPlugin((ctx) => {
+export const NavigationStatePlugin: RouterPlugin = (ctx) => {
   // 插件实现逻辑同上
-})
+}
 ```
 
 **2. 应用集成**
 
 ```ts
 // main.ts
+import { asVuePlugin } from 'vue-router-plugin-system'
+
 const app = createApp(App)
 app.use(router) // 先挂载路由
-app.use(NavigationStatePlugin) // 后注册插件
+app.use(asVuePlugin(NavigationStatePlugin)) // 后注册插件
 ```
 
 ---
 
 ## ⚠️ 模式对比
 
-| 特性           | Vue Router 插件模式   | Vue 插件模式       |
-| -------------- | --------------------- | ------------------ |
-| 初始化顺序     | 优先于应用逻辑        | 依赖客户端使用顺序 |
-| 导航守卫优先级 | 更高                  | 依赖注册顺序       |
-| 响应式管理     | 自动清理              | 自动清理           |
-| 依赖要求       | 需要本库 createRouter | 无需本库           |
+| 特性           | Vue Router 插件模式 | Vue 插件模式       |
+| -------------- | ------------------- | ------------------ |
+| 初始化顺序     | 优先于应用逻辑      | 依赖客户端使用顺序 |
+| 导航守卫优先级 | 更高                | 依赖注册顺序       |
+| 响应式管理     | 自动清理            | 自动清理           |
 
 ---
 
@@ -128,13 +130,6 @@ interface RouterPlugin {
    */
   (ctx: RouterPluginContext): void
 }
-
-interface VueRouterPlugin extends RouterPlugin {
-  /**
-   * Vue 插件安装函数
-   */
-  install: (app: App) => void
-}
 ```
 
 ---
diff --git a/src/as-vue-plugin.ts b/src/as-vue-plugin.ts
@@ -0,0 +1,39 @@
+import type { App, ObjectPlugin } from 'vue'
+import type { RouterPlugin } from './plugin'
+import { prepareInstall } from './prepare-install'
+import { setupPlugin } from './setup-plugin'
+
+/**
+ * Convert a {@link RouterPlugin} to a {@link ObjectPlugin VuePlugin}.
+ *
+ * @description Wraps the plugin with an `install` method to adapt it to Vue's plugin registration mechanism.
+ *
+ * @param plugin {@link RouterPlugin}
+ *
+ * @returns Returns a {@link ObjectPlugin VuePlugin}.
+ *
+ * @example
+ * ```ts
+ * const SomePlugin: RouterPlugin = (ctx) => {
+ *   // plugin implementation
+ * }
+ *
+ * // must be installed after the router
+ * app.use(router).use(asVuePlugin(SomePlugin))
+ * ```
+ */
+export function asVuePlugin(plugin: RouterPlugin): RouterPlugin & ObjectPlugin {
+  return Object.assign(plugin, {
+    install(app: App) {
+      const router = app.config.globalProperties.$router
+      if (!router) {
+        throw new Error(
+          '[vue-router-plugin-system] Please install vue-router first.',
+        )
+      }
+
+      prepareInstall({ app, router })
+      setupPlugin({ router, plugin })
+    },
+  })
+}
diff --git a/src/create-vue-router-plugin.ts b/src/create-vue-router-plugin.ts
@@ -1,8 +1,10 @@
 import type { App } from 'vue'
 import type { RouterPlugin } from './plugin'
-import { prepareInstall } from './prepare-install'
-import { setupPlugin } from './setup-plugin'
+import { asVuePlugin } from './as-vue-plugin'
 
+/**
+ * @deprecated
+ */
 export interface VueRouterPlugin extends RouterPlugin {
   /**
    * Install the plugin.
@@ -13,6 +15,9 @@ export interface VueRouterPlugin extends RouterPlugin {
 
 /**
  * Create a {@link VueRouterPlugin} from a {@link RouterPlugin}.
+ *
+ * @deprecated Please use {@link asVuePlugin} instead.
+ *
  * @param plugin {@link RouterPlugin}
  * @returns Returns a {@link VueRouterPlugin}
  * @example
@@ -25,18 +30,5 @@ export interface VueRouterPlugin extends RouterPlugin {
  * app.use(router).use(SomePlugin)
  * ```
  */
-export function createVueRouterPlugin(plugin: RouterPlugin): VueRouterPlugin {
-  return Object.assign(plugin, {
-    install(app: App) {
-      const router = app.config.globalProperties.$router
-      if (!router) {
-        throw new Error(
-          '[vue-router-plugin-system] Please install vue-router first.',
-        )
-      }
-
-      prepareInstall({ app, router })
-      setupPlugin({ router, plugin })
-    },
-  })
-}
+export const createVueRouterPlugin: (plugin: RouterPlugin) => VueRouterPlugin =
+  asVuePlugin
diff --git a/src/index.ts b/src/index.ts
@@ -1,3 +1,4 @@
+export * from './as-vue-plugin'
 export * from './create-router'
 export * from './create-vue-router-plugin'
 export * from './plugin'
diff --git a/tests/index.test.ts b/tests/index.test.ts
@@ -2,7 +2,7 @@ import type { RouterPlugin } from '../src/plugin'
 import { describe, expect, it, vi } from 'vitest'
 import { computed, createApp, ref, watch } from 'vue'
 import { createMemoryHistory } from 'vue-router'
-import { createRouter, createVueRouterPlugin } from '../src/index'
+import { asVuePlugin, createRouter } from '../src/index'
 
 describe.concurrent('vue Router Plugin System', () => {
   // 测试插件基础功能
@@ -107,23 +107,23 @@ describe.concurrent('vue Router Plugin System', () => {
     expect(logSpy).toHaveBeenCalledTimes(2)
   })
 
-  // 测试从 vue app 进行安装并且功能正常
-  it('should install from vue app', () => {
+  // 测试 asVuePlugin
+  it('test asVuePlugin', () => {
     const counter = ref(0)
     const logSpy = vi.fn()
-    const mockPlugin = createVueRouterPlugin(() => {
+    const mockPlugin: RouterPlugin = () => {
       const doubled = computed(() => counter.value * 2)
       watch(doubled, logSpy, { immediate: true, flush: 'sync' })
       counter.value = 1
-    })
+    }
 
     const router = createRouter({
       history: createMemoryHistory(),
       routes: [],
     })
 
     const app = createApp(() => null)
-    app.use(router).use(mockPlugin)
+    app.use(router).use(asVuePlugin(mockPlugin))
     app.unmount()
 
     expect(logSpy).toHaveBeenCalledTimes(2)
