@meng-xi/vite-plugin 0.1.3 → 0.1.4

package/dist/plugins/faviconManager/index.d.mts

@@ -7,22 +7,36 @@ import '../../shared/vite-plugin.DRRlWY8P.mjs';
  * 图标配置项接口
  *
  * @interface Icon
+ * @description 定义单个网站图标的属性，对应 HTML `<link>` 标签的各个属性。
  */
 interface Icon {
     /**
-     * 图标关系类型
+     * 图标关系类型，对应 `<link>` 标签的 `rel` 属性
+     *
+     * @example 'icon'
+     * @example 'apple-touch-icon'
+     * @example 'manifest'
      */
     rel: string;
     /**
-     * 图标 URL
+     * 图标 URL，对应 `<link>` 标签的 `href` 属性
+     *
+     * @example '/favicon.ico'
+     * @example '/apple-touch-icon.png'
      */
     href: string;
     /**
-     * 图标尺寸
+     * 图标尺寸，对应 `<link>` 标签的 `sizes` 属性
+     *
+     * @example '32x32'
+     * @example '180x180'
      */
     sizes?: string;
     /**
-     * 图标 MIME 类型
+     * 图标 MIME 类型，对应 `<link>` 标签的 `type` 属性
+     *
+     * @example 'image/png'
+     * @example 'image/svg+xml'
      */
     type?: string;
 }
@@ -30,6 +44,8 @@ interface Icon {
  * 图标文件复制配置选项接口
  *
  * @interface CopyOptions
+ * @description 配置图标文件从源目录到构建输出目录的复制行为，
+ * 仅当此对象存在时才开启图标文件复制功能。
  */
 interface CopyOptions {
     /**
@@ -51,7 +67,7 @@ interface CopyOptions {
      */
     overwrite?: boolean;
     /**
-     * 是否支持递归复制
+     * 是否支持递归复制子目录
      *
      * @default true
      */
@@ -61,6 +77,28 @@ interface CopyOptions {
  * 网站图标管理插件的配置选项接口
  *
  * @interface FaviconManagerOptions
+ * @extends {BasePluginOptions}
+ *
+ * @description 支持三种图标配置方式（优先级从高到低）：
+ * 1. `link` - 自定义完整的 `<link>` 标签 HTML
+ * 2. `url` - 完整的图标 URL
+ * 3. `base` + 默认 favicon.ico - 基础路径拼接
+ * 此外还支持通过 `icons` 数组配置多个图标，以及通过 `copyOptions` 复制图标文件。
+ *
+ * @example
+ * ```typescript
+ * faviconManager({
+ *   base: '/assets',
+ *   icons: [
+ *     { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },
+ *     { rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }
+ *   ],
+ *   copyOptions: {
+ *     sourceDir: 'src/assets/icons',
+ *     targetDir: 'dist/assets/icons'
+ *   }
+ * })
+ * ```
  */
 interface FaviconManagerOptions extends BasePluginOptions {
     /**

package/dist/plugins/faviconManager/index.d.ts

@@ -7,22 +7,36 @@ import '../../shared/vite-plugin.DRRlWY8P.js';
  * 图标配置项接口
  *
  * @interface Icon
+ * @description 定义单个网站图标的属性，对应 HTML `<link>` 标签的各个属性。
  */
 interface Icon {
     /**
-     * 图标关系类型
+     * 图标关系类型，对应 `<link>` 标签的 `rel` 属性
+     *
+     * @example 'icon'
+     * @example 'apple-touch-icon'
+     * @example 'manifest'
      */
     rel: string;
     /**
-     * 图标 URL
+     * 图标 URL，对应 `<link>` 标签的 `href` 属性
+     *
+     * @example '/favicon.ico'
+     * @example '/apple-touch-icon.png'
      */
     href: string;
     /**
-     * 图标尺寸
+     * 图标尺寸，对应 `<link>` 标签的 `sizes` 属性
+     *
+     * @example '32x32'
+     * @example '180x180'
      */
     sizes?: string;
     /**
-     * 图标 MIME 类型
+     * 图标 MIME 类型，对应 `<link>` 标签的 `type` 属性
+     *
+     * @example 'image/png'
+     * @example 'image/svg+xml'
      */
     type?: string;
 }
@@ -30,6 +44,8 @@ interface Icon {
  * 图标文件复制配置选项接口
  *
  * @interface CopyOptions
+ * @description 配置图标文件从源目录到构建输出目录的复制行为，
+ * 仅当此对象存在时才开启图标文件复制功能。
  */
 interface CopyOptions {
     /**
@@ -51,7 +67,7 @@ interface CopyOptions {
      */
     overwrite?: boolean;
     /**
-     * 是否支持递归复制
+     * 是否支持递归复制子目录
      *
      * @default true
      */
@@ -61,6 +77,28 @@ interface CopyOptions {
  * 网站图标管理插件的配置选项接口
  *
  * @interface FaviconManagerOptions
+ * @extends {BasePluginOptions}
+ *
+ * @description 支持三种图标配置方式（优先级从高到低）：
+ * 1. `link` - 自定义完整的 `<link>` 标签 HTML
+ * 2. `url` - 完整的图标 URL
+ * 3. `base` + 默认 favicon.ico - 基础路径拼接
+ * 此外还支持通过 `icons` 数组配置多个图标，以及通过 `copyOptions` 复制图标文件。
+ *
+ * @example
+ * ```typescript
+ * faviconManager({
+ *   base: '/assets',
+ *   icons: [
+ *     { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },
+ *     { rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }
+ *   ],
+ *   copyOptions: {
+ *     sourceDir: 'src/assets/icons',
+ *     targetDir: 'dist/assets/icons'
+ *   }
+ * })
+ * ```
  */
 interface FaviconManagerOptions extends BasePluginOptions {
     /**

package/dist/plugins/faviconManager/index.mjs

@@ -1 +1 @@
-import{createPluginFactory as n,BasePlugin as a}from"../../factory/index.mjs";import{checkSourceExists as c,copySourceToTarget as l}from"../../common/fs/index.mjs";import{V as g}from"../../shared/vite-plugin.DcExl6jd.mjs";import{injectBeforeTag as p}from"../../common/html/index.mjs";import"../../logger/index.mjs";import"../../common/object/index.mjs";import"fs";import"path";function F(u){const i=[];if(u.link)return[];if(u.icons&&u.icons.length>0)for(const e of u.icons){const t={rel:e.rel,href:e.href};e.sizes&&(t.sizes=e.sizes),e.type&&(t.type=e.type),i.push({tag:"link",attrs:t,injectTo:"head"})}else if(u.url)i.push({tag:"link",attrs:{rel:"icon",href:u.url},injectTo:"head"});else{const e=u.base||"/",t=e.endsWith("/")?`${e}favicon.ico`:`${e}/favicon.ico`;i.push({tag:"link",attrs:{rel:"icon",href:t},injectTo:"head"})}return i}class h extends a{getDefaultOptions(){return{base:"/"}}validateOptions(){this.validator.field("base").string().field("url").string().field("link").string().field("icons").array(),this.options?.copyOptions&&(this.validator.field("copyOptions").object(),new g(this.options.copyOptions).field("sourceDir").required().string().field("targetDir").required().string().field("overwrite").boolean().field("recursive").boolean().validate()),this.validator.validate()}getPluginName(){return"favicon-manager"}getIconTagDescriptors(){if(!this.options.enabled)return this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),[];const i=F(this.options);return i.length>0&&this.logger.success(`\u6210\u529F\u6CE8\u5165 ${i.length} \u4E2A\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6`),i}injectCustomLinkTag(i){if(!this.options.enabled||!this.options.link)return i;const e=this.options.link,t=p(i,"</head>",e);return t.injected?(this.logger.success("\u6210\u529F\u6CE8\u5165\u81EA\u5B9A\u4E49\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6"),this.logger.info(`  - ${e}`),t.html):(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),i)}async copyFiles(){if(!this.options.enabled){this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u6587\u4EF6\u590D\u5236");return}const{copyOptions:i}=this.options;if(!i)return;const{sourceDir:e,targetDir:t,overwrite:s=!0,recursive:o=!0}=i;await c(e);const r=await l(e,t,{recursive:o,overwrite:s,incremental:!0});this.logger.success(`\u56FE\u6807\u6587\u4EF6\u590D\u5236\u6210\u529F\uFF1A\u4ECE ${e} \u5230 ${t}`,`\u590D\u5236\u4E86 ${r.copiedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u4E86 ${r.skippedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8017\u65F6 ${r.executionTime}ms`)}addPluginHooks(i){i.transformIndexHtml={order:"pre",handler:e=>{if(this.options.link)return this.injectCustomLinkTag(e);const t=this.getIconTagDescriptors();return t.length>0?{html:e,tags:t}:e}},i.writeBundle=async()=>{await this.safeExecute(()=>this.copyFiles(),"\u56FE\u6807\u6587\u4EF6\u590D\u5236")}}}const f=n(h,u=>typeof u=="string"?{base:u}:u||{});export{f as faviconManager};
+import{createPluginFactory as n,BasePlugin as a}from"../../factory/index.mjs";import{checkSourceExists as c,copySourceToTarget as l}from"../../common/fs/index.mjs";import{V as g}from"../../shared/vite-plugin.DcExl6jd.mjs";import{injectBeforeTag as p}from"../../common/html/index.mjs";import"../../logger/index.mjs";import"../../common/object/index.mjs";import"fs";import"path";import"../../shared/vite-plugin.BCuhU1au.mjs";import"../../common/script/index.mjs";function F(u){const i=[];if(u.link)return[];if(u.icons&&u.icons.length>0)for(const e of u.icons){const t={rel:e.rel,href:e.href};e.sizes&&(t.sizes=e.sizes),e.type&&(t.type=e.type),i.push({tag:"link",attrs:t,injectTo:"head"})}else if(u.url)i.push({tag:"link",attrs:{rel:"icon",href:u.url},injectTo:"head"});else{const e=u.base||"/",t=e.endsWith("/")?`${e}favicon.ico`:`${e}/favicon.ico`;i.push({tag:"link",attrs:{rel:"icon",href:t},injectTo:"head"})}return i}class h extends a{getDefaultOptions(){return{base:"/"}}validateOptions(){this.validator.field("base").string().field("url").string().field("link").string().field("icons").array(),this.options?.copyOptions&&(this.validator.field("copyOptions").object(),new g(this.options.copyOptions).field("sourceDir").required().string().field("targetDir").required().string().field("overwrite").boolean().field("recursive").boolean().validate()),this.validator.validate()}getPluginName(){return"favicon-manager"}getIconTagDescriptors(){if(!this.options.enabled)return this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),[];const i=F(this.options);return i.length>0&&this.logger.success(`\u6210\u529F\u6CE8\u5165 ${i.length} \u4E2A\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6`),i}injectCustomLinkTag(i){if(!this.options.enabled||!this.options.link)return i;const e=this.options.link,t=p(i,"</head>",e);return t.injected?(this.logger.success("\u6210\u529F\u6CE8\u5165\u81EA\u5B9A\u4E49\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6"),this.logger.info(`  - ${e}`),t.html):(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),i)}async copyFiles(){if(!this.options.enabled){this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u6587\u4EF6\u590D\u5236");return}const{copyOptions:i}=this.options;if(!i)return;const{sourceDir:e,targetDir:t,overwrite:o=!0,recursive:s=!0}=i;await c(e);const r=await l(e,t,{recursive:s,overwrite:o,incremental:!0});this.logger.success(`\u56FE\u6807\u6587\u4EF6\u590D\u5236\u6210\u529F\uFF1A\u4ECE ${e} \u5230 ${t}`,`\u590D\u5236\u4E86 ${r.copiedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u4E86 ${r.skippedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8017\u65F6 ${r.executionTime}ms`)}addPluginHooks(i){i.transformIndexHtml={order:"pre",handler:e=>{if(this.options.link)return this.injectCustomLinkTag(e);const t=this.getIconTagDescriptors();return t.length>0?{html:e,tags:t}:e}},i.writeBundle=async()=>{await this.safeExecute(()=>this.copyFiles(),"\u56FE\u6807\u6587\u4EF6\u590D\u5236")}}}const f=n(h,u=>typeof u=="string"?{base:u}:u||{});export{f as faviconManager};

package/dist/plugins/generateRouter/index.d.cts

@@ -5,37 +5,47 @@ import '../../shared/vite-plugin.DRRlWY8P.cjs';
 
 /**
  * 路由元信息
+ *
+ * @interface RouteMeta
+ * @description 路由附加的元数据，用于页面导航守卫、标题设置等场景。
+ * 支持通过索引签名扩展自定义字段。
  */
 interface RouteMeta {
-    /** 页面标题 */
+    /** 页面标题，对应 pages.json 中的 navigationBarTitleText */
     title?: string;
-    /** 是否为TabBar页面 */
+    /** 是否为 TabBar 页面，由插件自动从 tabBar 配置推断 */
     isTab?: boolean;
-    /** 是否需要登录 */
+    /** 是否需要登录才能访问 */
     requireAuth?: boolean;
     /** 自定义扩展字段 */
     [key: string]: unknown;
 }
 /**
  * 路由配置项
+ *
+ * @interface RouteConfig
+ * @description 单条路由的完整配置，包含路径、名称和元信息。
  */
 interface RouteConfig {
-    /** 路由路径 */
+    /** 路由路径，以 `/` 开头 */
     path: string;
-    /** 路由名称（用于命名路由导航） */
+    /** 路由名称（用于命名路由导航），根据 nameStrategy 自动生成 */
     name?: string;
     /** 路由元信息 */
     meta?: RouteMeta;
 }
 /**
  * uni-app pages.json 中的页面配置项
+ *
+ * @interface UniAppPageConfig
+ * @description 对应 pages.json 中 `pages` 数组里的单个页面对象。
  */
 interface UniAppPageConfig {
-    /** 页面路径 */
+    /** 页面路径，相对于 pages.json 所在目录 */
     path: string;
-    /** 页面样式 */
+    /** 页面样式配置 */
     style?: {
-        /** 导航栏标题 */
+        /** 导航栏标题文本 */
         navigationBarTitleText?: string;
         /** 是否需要登录 */
         requireAuth?: boolean;
@@ -47,15 +57,18 @@ interface UniAppPageConfig {
 }
 /**
  * uni-app pages.json 中的 tabBar 配置
+ *
+ * @interface UniAppTabBarConfig
+ * @description 对应 pages.json 中的 `tabBar` 字段，定义底部标签栏的页面列表和图标。
  */
 interface UniAppTabBarConfig {
-    /** tabBar 列表 */
+    /** tabBar 页面列表 */
     list?: Array<{
         /** 页面路径 */
         pagePath: string;
-        /** 文字 */
+        /** 标签文字 */
         text?: string;
-        /** 图标路径 */
+        /** 未选中图标路径 */
         iconPath?: string;
         /** 选中图标路径 */
         selectedIconPath?: string;
@@ -65,32 +78,66 @@ interface UniAppTabBarConfig {
 }
 /**
  * uni-app pages.json 结构
+ *
+ * @interface UniAppPagesJson
+ * @description 完整的 pages.json 文件结构，包含主包页面、子包、tabBar 和全局样式。
  */
 interface UniAppPagesJson {
-    /** 页面列表 */
+    /** 主包页面列表 */
     pages: UniAppPageConfig[];
-    /** 子包 */
+    /** 子包（分包）配置列表 */
     subPackages?: Array<{
+        /** 子包根路径 */
         root: string;
+        /** 子包页面列表 */
         pages: UniAppPageConfig[];
     }>;
     /** tabBar 配置 */
     tabBar?: UniAppTabBarConfig;
-    /** 全局样式 */
+    /** 全局样式配置 */
     globalStyle?: Record<string, unknown>;
     /** 其他属性 */
     [key: string]: unknown;
 }
 /**
  * 输出文件格式类型
+ *
+ * @description 支持的输出文件格式：
+ * - `ts`: TypeScript 文件
+ * - `js`: JavaScript 文件
  */
 type OutputFormat = 'ts' | 'js';
 /**
  * 路由名称生成策略
+ *
+ * @description 定义路由名称的生成方式：
+ * - `path`: 使用原始路径（斜杠替换为下划线）
+ * - `camelCase`: 驼峰命名（默认）
+ * - `pascalCase`: 帕斯卡命名
+ * - `custom`: 自定义生成函数
  */
 type NameStrategy = 'path' | 'camelCase' | 'pascalCase' | 'custom';
 /**
  * 生成路由配置插件选项
+ *
+ * @interface GenerateRouterOptions
+ * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * generateRouter({
+ *   pagesJsonPath: 'src/pages.json',
+ *   outputPath: 'src/router.config.ts',
+ *   outputFormat: 'ts',
+ *   nameStrategy: 'camelCase',
+ *   includeSubPackages: true,
+ *   watch: true,
+ *   metaMapping: {
+ *     navigationBarTitleText: 'title',
+ *     requireAuth: 'requireAuth'
+ *   }
+ * })
+ * ```
  */
 interface GenerateRouterOptions extends BasePluginOptions {
     /**

package/dist/plugins/generateRouter/index.d.mts

@@ -5,37 +5,47 @@ import '../../shared/vite-plugin.DRRlWY8P.mjs';
 
 /**
  * 路由元信息
+ *
+ * @interface RouteMeta
+ * @description 路由附加的元数据，用于页面导航守卫、标题设置等场景。
+ * 支持通过索引签名扩展自定义字段。
  */
 interface RouteMeta {
-    /** 页面标题 */
+    /** 页面标题，对应 pages.json 中的 navigationBarTitleText */
     title?: string;
-    /** 是否为TabBar页面 */
+    /** 是否为 TabBar 页面，由插件自动从 tabBar 配置推断 */
     isTab?: boolean;
-    /** 是否需要登录 */
+    /** 是否需要登录才能访问 */
     requireAuth?: boolean;
     /** 自定义扩展字段 */
     [key: string]: unknown;
 }
 /**
  * 路由配置项
+ *
+ * @interface RouteConfig
+ * @description 单条路由的完整配置，包含路径、名称和元信息。
  */
 interface RouteConfig {
-    /** 路由路径 */
+    /** 路由路径，以 `/` 开头 */
     path: string;
-    /** 路由名称（用于命名路由导航） */
+    /** 路由名称（用于命名路由导航），根据 nameStrategy 自动生成 */
     name?: string;
     /** 路由元信息 */
     meta?: RouteMeta;
 }
 /**
  * uni-app pages.json 中的页面配置项
+ *
+ * @interface UniAppPageConfig
+ * @description 对应 pages.json 中 `pages` 数组里的单个页面对象。
  */
 interface UniAppPageConfig {
-    /** 页面路径 */
+    /** 页面路径，相对于 pages.json 所在目录 */
     path: string;
-    /** 页面样式 */
+    /** 页面样式配置 */
     style?: {
-        /** 导航栏标题 */
+        /** 导航栏标题文本 */
         navigationBarTitleText?: string;
         /** 是否需要登录 */
         requireAuth?: boolean;
@@ -47,15 +57,18 @@ interface UniAppPageConfig {
 }
 /**
  * uni-app pages.json 中的 tabBar 配置
+ *
+ * @interface UniAppTabBarConfig
+ * @description 对应 pages.json 中的 `tabBar` 字段，定义底部标签栏的页面列表和图标。
  */
 interface UniAppTabBarConfig {
-    /** tabBar 列表 */
+    /** tabBar 页面列表 */
     list?: Array<{
         /** 页面路径 */
         pagePath: string;
-        /** 文字 */
+        /** 标签文字 */
         text?: string;
-        /** 图标路径 */
+        /** 未选中图标路径 */
         iconPath?: string;
         /** 选中图标路径 */
         selectedIconPath?: string;
@@ -65,32 +78,66 @@ interface UniAppTabBarConfig {
 }
 /**
  * uni-app pages.json 结构
+ *
+ * @interface UniAppPagesJson
+ * @description 完整的 pages.json 文件结构，包含主包页面、子包、tabBar 和全局样式。
  */
 interface UniAppPagesJson {
-    /** 页面列表 */
+    /** 主包页面列表 */
     pages: UniAppPageConfig[];
-    /** 子包 */
+    /** 子包（分包）配置列表 */
     subPackages?: Array<{
+        /** 子包根路径 */
         root: string;
+        /** 子包页面列表 */
         pages: UniAppPageConfig[];
     }>;
     /** tabBar 配置 */
     tabBar?: UniAppTabBarConfig;
-    /** 全局样式 */
+    /** 全局样式配置 */
     globalStyle?: Record<string, unknown>;
     /** 其他属性 */
     [key: string]: unknown;
 }
 /**
  * 输出文件格式类型
+ *
+ * @description 支持的输出文件格式：
+ * - `ts`: TypeScript 文件
+ * - `js`: JavaScript 文件
  */
 type OutputFormat = 'ts' | 'js';
 /**
  * 路由名称生成策略
+ *
+ * @description 定义路由名称的生成方式：
+ * - `path`: 使用原始路径（斜杠替换为下划线）
+ * - `camelCase`: 驼峰命名（默认）
+ * - `pascalCase`: 帕斯卡命名
+ * - `custom`: 自定义生成函数
  */
 type NameStrategy = 'path' | 'camelCase' | 'pascalCase' | 'custom';
 /**
  * 生成路由配置插件选项
+ *
+ * @interface GenerateRouterOptions
+ * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * generateRouter({
+ *   pagesJsonPath: 'src/pages.json',
+ *   outputPath: 'src/router.config.ts',
+ *   outputFormat: 'ts',
+ *   nameStrategy: 'camelCase',
+ *   includeSubPackages: true,
+ *   watch: true,
+ *   metaMapping: {
+ *     navigationBarTitleText: 'title',
+ *     requireAuth: 'requireAuth'
+ *   }
+ * })
+ * ```
  */
 interface GenerateRouterOptions extends BasePluginOptions {
     /**

package/dist/plugins/generateRouter/index.d.ts

@@ -5,37 +5,47 @@ import '../../shared/vite-plugin.DRRlWY8P.js';
 
 /**
  * 路由元信息
+ *
+ * @interface RouteMeta
+ * @description 路由附加的元数据，用于页面导航守卫、标题设置等场景。
+ * 支持通过索引签名扩展自定义字段。
  */
 interface RouteMeta {
-    /** 页面标题 */
+    /** 页面标题，对应 pages.json 中的 navigationBarTitleText */
     title?: string;
-    /** 是否为TabBar页面 */
+    /** 是否为 TabBar 页面，由插件自动从 tabBar 配置推断 */
     isTab?: boolean;
-    /** 是否需要登录 */
+    /** 是否需要登录才能访问 */
     requireAuth?: boolean;
     /** 自定义扩展字段 */
     [key: string]: unknown;
 }
 /**
  * 路由配置项
+ *
+ * @interface RouteConfig
+ * @description 单条路由的完整配置，包含路径、名称和元信息。
  */
 interface RouteConfig {
-    /** 路由路径 */
+    /** 路由路径，以 `/` 开头 */
     path: string;
-    /** 路由名称（用于命名路由导航） */
+    /** 路由名称（用于命名路由导航），根据 nameStrategy 自动生成 */
     name?: string;
     /** 路由元信息 */
     meta?: RouteMeta;
 }
 /**
  * uni-app pages.json 中的页面配置项
+ *
+ * @interface UniAppPageConfig
+ * @description 对应 pages.json 中 `pages` 数组里的单个页面对象。
  */
 interface UniAppPageConfig {
-    /** 页面路径 */
+    /** 页面路径，相对于 pages.json 所在目录 */
     path: string;
-    /** 页面样式 */
+    /** 页面样式配置 */
     style?: {
-        /** 导航栏标题 */
+        /** 导航栏标题文本 */
         navigationBarTitleText?: string;
         /** 是否需要登录 */
         requireAuth?: boolean;
@@ -47,15 +57,18 @@ interface UniAppPageConfig {
 }
 /**
  * uni-app pages.json 中的 tabBar 配置
+ *
+ * @interface UniAppTabBarConfig
+ * @description 对应 pages.json 中的 `tabBar` 字段，定义底部标签栏的页面列表和图标。
  */
 interface UniAppTabBarConfig {
-    /** tabBar 列表 */
+    /** tabBar 页面列表 */
     list?: Array<{
         /** 页面路径 */
         pagePath: string;
-        /** 文字 */
+        /** 标签文字 */
         text?: string;
-        /** 图标路径 */
+        /** 未选中图标路径 */
         iconPath?: string;
         /** 选中图标路径 */
         selectedIconPath?: string;
@@ -65,32 +78,66 @@ interface UniAppTabBarConfig {
 }
 /**
  * uni-app pages.json 结构
+ *
+ * @interface UniAppPagesJson
+ * @description 完整的 pages.json 文件结构，包含主包页面、子包、tabBar 和全局样式。
  */
 interface UniAppPagesJson {
-    /** 页面列表 */
+    /** 主包页面列表 */
     pages: UniAppPageConfig[];
-    /** 子包 */
+    /** 子包（分包）配置列表 */
     subPackages?: Array<{
+        /** 子包根路径 */
         root: string;
+        /** 子包页面列表 */
         pages: UniAppPageConfig[];
     }>;
     /** tabBar 配置 */
     tabBar?: UniAppTabBarConfig;
-    /** 全局样式 */
+    /** 全局样式配置 */
     globalStyle?: Record<string, unknown>;
     /** 其他属性 */
     [key: string]: unknown;
 }
 /**
  * 输出文件格式类型
+ *
+ * @description 支持的输出文件格式：
+ * - `ts`: TypeScript 文件
+ * - `js`: JavaScript 文件
  */
 type OutputFormat = 'ts' | 'js';
 /**
  * 路由名称生成策略
+ *
+ * @description 定义路由名称的生成方式：
+ * - `path`: 使用原始路径（斜杠替换为下划线）
+ * - `camelCase`: 驼峰命名（默认）
+ * - `pascalCase`: 帕斯卡命名
+ * - `custom`: 自定义生成函数
  */
 type NameStrategy = 'path' | 'camelCase' | 'pascalCase' | 'custom';
 /**
  * 生成路由配置插件选项
+ *
+ * @interface GenerateRouterOptions
+ * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * generateRouter({
+ *   pagesJsonPath: 'src/pages.json',
+ *   outputPath: 'src/router.config.ts',
+ *   outputFormat: 'ts',
+ *   nameStrategy: 'camelCase',
+ *   includeSubPackages: true,
+ *   watch: true,
+ *   metaMapping: {
+ *     navigationBarTitleText: 'title',
+ *     requireAuth: 'requireAuth'
+ *   }
+ * })
+ * ```
  */
 interface GenerateRouterOptions extends BasePluginOptions {
     /**

package/dist/plugins/generateVersion/index.d.cts

@@ -46,6 +46,18 @@ interface VersionInfo {
  * 自动生成版本号插件的配置选项接口
  *
  * @interface GenerateVersionOptions
+ * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * generateVersion({
+ *   format: 'semver',
+ *   semverBase: '2.0.0',
+ *   outputType: 'both',
+ *   prefix: 'v',
+ *   extra: { environment: 'production' }
+ * })
+ * ```
  */
 interface GenerateVersionOptions extends BasePluginOptions {
     /**

package/dist/plugins/generateVersion/index.d.mts

@@ -46,6 +46,18 @@ interface VersionInfo {
  * 自动生成版本号插件的配置选项接口
  *
  * @interface GenerateVersionOptions
+ * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * generateVersion({
+ *   format: 'semver',
+ *   semverBase: '2.0.0',
+ *   outputType: 'both',
+ *   prefix: 'v',
+ *   extra: { environment: 'production' }
+ * })
+ * ```
  */
 interface GenerateVersionOptions extends BasePluginOptions {
     /**