@meng-xi/vite-plugin 0.1.2 → 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.cjs

@@ -1,4 +1,4 @@
-"use strict";const factory_index=require("../../factory/index.cjs"),common_fs_index=require("../../common/fs/index.cjs"),common_format_index=require("../../common/format/index.cjs"),u=require("path"),s=require("fs");require("../../logger/index.cjs"),require("../../common/object/index.cjs"),require("../../shared/vite-plugin.Bcg6RW2N.cjs"),require("crypto");class R extends factory_index.BasePlugin{projectRoot=process.cwd();tabBarPages=new Set;watcher=null;getDefaultOptions(){return{pagesJsonPath:"src/pages.json",outputPath:"src/router.config.ts",outputFormat:"ts",nameStrategy:"camelCase",includeSubPackages:!0,watch:!0,exportTypes:!0,preserveRouteChanges:!0,metaMapping:{navigationBarTitleText:"title",requireAuth:"requireAuth"}}}validateOptions(){if(this.validator.field("pagesJsonPath").string().field("outputPath").string().field("outputFormat").enum(["ts","js"]).field("nameStrategy").enum(["path","camelCase","pascalCase","custom"]).validate(),this.options.nameStrategy==="custom"&&!this.options.customNameGenerator)throw new Error("\u5F53 nameStrategy \u4E3A custom \u65F6\uFF0C\u5FC5\u987B\u63D0\u4F9B customNameGenerator")}getPluginName(){return"generate-router"}generateRouteName(e){switch(this.options.nameStrategy){case"path":return e.replace(/\//g,"_").replace(/^_/,"");case"camelCase":return common_format_index.toCamelCase(e);case"pascalCase":return common_format_index.toPascalCase(e);case"custom":return this.options.customNameGenerator(e);default:return common_format_index.toCamelCase(e)}}extractMeta(e,a){const t={},r=e.style||{},o=this.options.metaMapping||{};for(const[n,i]of Object.entries(o))r[n]!==void 0&&(t[i]=r[n]);return this.tabBarPages.has(a)&&(t.isTab=!0),t}parsePageToRoute(e,a=""){const t=a?`/${a}/${e.path}`:`/${e.path}`,r=this.generateRouteName(t),o=this.extractMeta(e,t.replace(/^\//,"")),n={path:t,name:r};return Object.keys(o).length>0&&(n.meta=o),n}parsePagesJson(e){const a=[];if(!e.pages||!Array.isArray(e.pages)||e.pages.length===0)return this.logger.warn("pages.json \u4E2D\u6CA1\u6709\u6709\u6548\u7684\u9875\u9762\u914D\u7F6E"),a;if(this.tabBarPages.clear(),e.tabBar?.list)for(const t of e.tabBar.list)this.tabBarPages.add(t.pagePath);for(const t of e.pages)a.push(this.parsePageToRoute(t));if(this.options.includeSubPackages&&e.subPackages){for(const t of e.subPackages)if(t.pages&&Array.isArray(t.pages))for(const r of t.pages)a.push(this.parsePageToRoute(r,t.root))}return a}generateTypeDefinitions(){return!this.options.exportTypes||this.options.outputFormat==="js"?"":`
+"use strict";const factory_index=require("../../factory/index.cjs"),common_fs_index=require("../../common/fs/index.cjs"),common_format_index=require("../../common/format/index.cjs"),f=require("path"),s=require("fs");require("../../logger/index.cjs"),require("../../common/object/index.cjs"),require("../../shared/vite-plugin.Bcg6RW2N.cjs"),require("crypto"),require("node:path");class R extends factory_index.BasePlugin{projectRoot=process.cwd();tabBarPages=new Set;watcher=null;getDefaultOptions(){return{pagesJsonPath:"src/pages.json",outputPath:"src/router.config.ts",outputFormat:"ts",nameStrategy:"camelCase",includeSubPackages:!0,watch:!0,exportTypes:!0,preserveRouteChanges:!0,metaMapping:{navigationBarTitleText:"title",requireAuth:"requireAuth"}}}validateOptions(){if(this.validator.field("pagesJsonPath").string().field("outputPath").string().field("outputFormat").enum(["ts","js"]).field("nameStrategy").enum(["path","camelCase","pascalCase","custom"]).validate(),this.options.nameStrategy==="custom"&&!this.options.customNameGenerator)throw new Error("\u5F53 nameStrategy \u4E3A custom \u65F6\uFF0C\u5FC5\u987B\u63D0\u4F9B customNameGenerator")}getPluginName(){return"generate-router"}generateRouteName(e){switch(this.options.nameStrategy){case"path":return e.replace(/\//g,"_").replace(/^_/,"");case"camelCase":return common_format_index.toCamelCase(e);case"pascalCase":return common_format_index.toPascalCase(e);case"custom":return this.options.customNameGenerator(e);default:return common_format_index.toCamelCase(e)}}extractMeta(e,u){const t={},a=e.style||{},r=this.options.metaMapping||{};for(const[o,n]of Object.entries(r))a[o]!==void 0&&(t[n]=a[o]);return this.tabBarPages.has(u)&&(t.isTab=!0),t}parsePageToRoute(e,u=""){const t=u?`/${u}/${e.path}`:`/${e.path}`,a=this.generateRouteName(t),r=this.extractMeta(e,t.replace(/^\//,"")),o={path:t,name:a};return Object.keys(r).length>0&&(o.meta=r),o}parsePagesJson(e){const u=[];if(!e.pages||!Array.isArray(e.pages)||e.pages.length===0)return this.logger.warn("pages.json \u4E2D\u6CA1\u6709\u6709\u6548\u7684\u9875\u9762\u914D\u7F6E"),u;if(this.tabBarPages.clear(),e.tabBar?.list)for(const t of e.tabBar.list)this.tabBarPages.add(t.pagePath);for(const t of e.pages)u.push(this.parsePageToRoute(t));if(this.options.includeSubPackages&&e.subPackages){for(const t of e.subPackages)if(t.pages&&Array.isArray(t.pages))for(const a of t.pages)u.push(this.parsePageToRoute(a,t.root))}return u}generateTypeDefinitions(){return!this.options.exportTypes||this.options.outputFormat==="js"?"":`
 /**
  * \u8DEF\u7531\u5143\u4FE1\u606F
  */
@@ -24,12 +24,12 @@ export interface RouteConfig {
 	/** \u8DEF\u7531\u5143\u4FE1\u606F */
 	meta?: RouteMeta
 }
-`}generateFileContent(e){const a=this.generateTypeDefinitions(),t=this.options.outputFormat==="ts",r=JSON.stringify(e,null,"	").replace(/"(\w+)":/g,"$1:").replace(/: "([^"]+)"/g,": '$1'");return`${a}
+`}generateFileContent(e){const u=this.generateTypeDefinitions(),t=this.options.outputFormat==="ts",a=JSON.stringify(e,null,"	").replace(/"(\w+)":/g,"$1:").replace(/: "([^"]+)"/g,": '$1'");return`${u}
 /**
  * \u8DEF\u7531\u914D\u7F6E\u5217\u8868
  * @description \u7531 pages.json \u81EA\u52A8\u751F\u6210
  */
-export const routes${t?": RouteConfig[]":""} = ${r}
+export const routes${t?": RouteConfig[]":""} = ${a}
 
 export default routes
-`}async readPagesJson(){const e=u.resolve(this.projectRoot,this.options.pagesJsonPath);if(!s.existsSync(e))return this.logger.warn(`pages.json \u6587\u4EF6\u4E0D\u5B58\u5728: ${e}`),null;try{const a=await common_fs_index.readFileContent(e),t=common_format_index.stripJsonComments(a);return JSON.parse(t)}catch(a){return this.logger.error(`\u89E3\u6790 pages.json \u5931\u8D25: ${a.message}`),null}}extractExistingRoutes(e){const a=new Map,t=e.match(/export const routes[^=]*=\s*(\[[\s\S]*?\](?=\s*\n|\s*$|\s*\/\/))/);if(!t)return a;try{let r=t[1].replace(/(\w+)(?=\s*:)/g,'"$1"').replace(/'([^']*)'/g,'"$1"').replace(/,\s*([\]\}])/g,"$1");const o=JSON.parse(r);for(const n of o)n.path&&a.set(n.path,n)}catch{this.logger.warn("\u89E3\u6790\u73B0\u6709 routes \u914D\u7F6E\u5931\u8D25\uFF0C\u5C06\u5B8C\u5168\u91CD\u65B0\u751F\u6210")}return a}mergeRoutes(e,a){return e.map(t=>{const r=a.get(t.path);if(!r)return t;const o={};return t.meta&&Object.assign(o,t.meta),r.meta&&Object.assign(o,r.meta),{...r,path:t.path,meta:Object.keys(o).length>0?o:void 0}})}async generateRouterConfig(){const e=await this.readPagesJson();if(!e)return;let a=this.parsePagesJson(e);const t=u.resolve(this.projectRoot,this.options.outputPath);if(this.options.preserveRouteChanges&&s.existsSync(t))try{const o=await common_fs_index.readFileContent(t),n=this.extractExistingRoutes(o);n.size>0&&(a=this.mergeRoutes(a,n),this.logger.info("\u5DF2\u5408\u5E76\u7528\u6237\u5BF9\u8DEF\u7531\u914D\u7F6E\u7684\u4FEE\u6539"))}catch{}const r=this.generateFileContent(a);await common_fs_index.writeFileContent(t,r),this.logger.success(`\u8DEF\u7531\u914D\u7F6E\u6587\u4EF6\u5DF2\u751F\u6210: ${t}`),this.logger.info(`\u5171\u751F\u6210 ${a.length} \u6761\u8DEF\u7531\u914D\u7F6E`)}startWatching(){if(!this.options.watch)return;const e=u.resolve(this.projectRoot,this.options.pagesJsonPath);s.existsSync(e)&&(this.watcher=s.watch(e,async a=>{a==="change"&&(this.logger.info("\u68C0\u6D4B\u5230 pages.json \u53D8\u5316\uFF0C\u91CD\u65B0\u751F\u6210\u8DEF\u7531\u914D\u7F6E..."),await this.safeExecute(()=>this.generateRouterConfig(),"\u91CD\u65B0\u751F\u6210\u8DEF\u7531\u914D\u7F6E"))}),this.logger.info(`\u6B63\u5728\u76D1\u542C pages.json \u53D8\u5316: ${e}`))}stopWatching(){this.watcher&&(this.watcher.close(),this.watcher=null)}addPluginHooks(e){e.configResolved=async a=>{this.projectRoot=a.root,await this.safeExecute(()=>this.generateRouterConfig(),"\u751F\u6210\u8DEF\u7531\u914D\u7F6E"),a.command==="serve"&&this.startWatching()}}destroy(){super.destroy(),this.stopWatching()}}const generateRouter=factory_index.createPluginFactory(R);exports.generateRouter=generateRouter;
+`}async readPagesJson(){const e=f.resolve(this.projectRoot,this.options.pagesJsonPath);if(!s.existsSync(e))return this.logger.warn(`pages.json \u6587\u4EF6\u4E0D\u5B58\u5728: ${e}`),null;try{const u=await common_fs_index.readFileContent(e),t=common_format_index.stripJsonComments(u);return JSON.parse(t)}catch(u){return this.logger.error(`\u89E3\u6790 pages.json \u5931\u8D25: ${u.message}`),null}}extractExistingRoutes(e){const u=new Map,t=e.match(/export const routes[^=]*=\s*(\[[\s\S]*?\](?=\s*\n|\s*$|\s*\/\/))/);if(!t)return u;try{let a=t[1].replace(/(\w+)(?=\s*:)/g,'"$1"').replace(/'([^']*)'/g,'"$1"').replace(/,\s*([\]\}])/g,"$1");const r=JSON.parse(a);for(const o of r)o.path&&u.set(o.path,o)}catch{this.logger.warn("\u89E3\u6790\u73B0\u6709 routes \u914D\u7F6E\u5931\u8D25\uFF0C\u5C06\u5B8C\u5168\u91CD\u65B0\u751F\u6210")}return u}mergeRoutes(e,u){return e.map(t=>{const a=u.get(t.path);if(!a)return t;const r={};return t.meta&&Object.assign(r,t.meta),a.meta&&Object.assign(r,a.meta),{...a,path:t.path,meta:Object.keys(r).length>0?r:void 0}})}async generateRouterConfig(){const e=await this.readPagesJson();if(!e)return;let u=this.parsePagesJson(e);const t=f.resolve(this.projectRoot,this.options.outputPath);if(this.options.preserveRouteChanges&&s.existsSync(t))try{const r=await common_fs_index.readFileContent(t),o=this.extractExistingRoutes(r);o.size>0&&(u=this.mergeRoutes(u,o),this.logger.info("\u5DF2\u5408\u5E76\u7528\u6237\u5BF9\u8DEF\u7531\u914D\u7F6E\u7684\u4FEE\u6539"))}catch{}const a=this.generateFileContent(u);await common_fs_index.writeFileContent(t,a),this.logger.success(`\u8DEF\u7531\u914D\u7F6E\u6587\u4EF6\u5DF2\u751F\u6210: ${t}`),this.logger.info(`\u5171\u751F\u6210 ${u.length} \u6761\u8DEF\u7531\u914D\u7F6E`)}startWatching(){if(!this.options.watch)return;const e=f.resolve(this.projectRoot,this.options.pagesJsonPath);s.existsSync(e)&&(this.watcher=s.watch(e,async u=>{u==="change"&&(this.logger.info("\u68C0\u6D4B\u5230 pages.json \u53D8\u5316\uFF0C\u91CD\u65B0\u751F\u6210\u8DEF\u7531\u914D\u7F6E..."),await this.safeExecute(()=>this.generateRouterConfig(),"\u91CD\u65B0\u751F\u6210\u8DEF\u7531\u914D\u7F6E"))}),this.logger.info(`\u6B63\u5728\u76D1\u542C pages.json \u53D8\u5316: ${e}`))}stopWatching(){this.watcher&&(this.watcher.close(),this.watcher=null)}addPluginHooks(e){e.configResolved=async u=>{this.projectRoot=u.root,await this.safeExecute(()=>this.generateRouterConfig(),"\u751F\u6210\u8DEF\u7531\u914D\u7F6E"),u.command==="serve"&&this.startWatching()}}destroy(){super.destroy(),this.stopWatching()}}const generateRouter=factory_index.createPluginFactory(R);exports.generateRouter=generateRouter;

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 {
     /**