@uni-helper/vite-plugin-uni-pages 0.3.23 → 0.4.0

package/README.md

@@ -1,23 +1,23 @@
 # @uni-helper/vite-plugin-uni-pages
 
-File system-based routing for uni-app applications using Vite.
-
 <a href="https://www.npmjs.com/package/@uni-helper/vite-plugin-uni-pages"><img src="https://img.shields.io/npm/v/@uni-helper/vite-plugin-uni-pages" alt="NPM version"></a></p>
 
-English | [简体中文](./README.Zh-CN.md)
+使用 TypeScript 编写 `uni-app` 的 `pages.json`。支持约定式路由。
+
+不想看文档？直接问 AI 🤖 <a href="https://deepwiki.com/uni-helper/vite-plugin-uni-pages"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a> <a href="https://zread.ai/uni-helper/vite-plugin-uni-pages" target="_blank"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="zread"/></a>
 
-## Installation
+## 安装
 
 ```bash
 pnpm i -D @uni-helper/vite-plugin-uni-pages
 ```
 
-## Usage
+## 使用
 
 ```ts
+// vite.config.ts
 import Uni from '@dcloudio/vite-plugin-uni'
 import UniPages from '@uni-helper/vite-plugin-uni-pages'
-// vite.config.ts
 import { defineConfig } from 'vite'
 
 // It is recommended to put it in front of Uni
@@ -26,15 +26,20 @@ export default defineConfig({
 })
 ```
 
-Define global properties in `pages.config.(ts|mts|cts|js|cjs|mjs|json)`, You can use like `#ifdef H5` in the file.
+创建 `pages.config.(ts|mts|cts|js|cjs|mjs|json)`，然后用 TypeScript 编写你的 `pages.json`。你可以在创建的文件里使用 `#ifdef H5` 等条件编译语句。
 
 ```ts
 // pages.config.ts
 import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'
 
 export default defineUniPages({
-  // You can also define pages fields, which have the highest priority.priority.
-  pages: [],
+  // 你可以手动指定 pages，这种做法具有最高优先级，插件会使用你指定的 pages 生成 pages.json。
+  // 如果不手动指定 pages，插件会自动扫描页面并生成 pages.json。
+  // pages: [],
+
+  // 其它属性参考 pages.json，理论上一比一对齐
+  // 如果发现没有对齐，请提交 issue，谢谢 🙏
+  // https://uniapp.dcloud.net.cn/collocation/pages.html
   globalStyle: {
     navigationBarTextStyle: 'black',
     navigationBarTitleText: '@uni-helper',
@@ -42,36 +47,7 @@ export default defineUniPages({
 })
 ```
 
-Now all pages will be found automatically!
-
-### SFC custom block for Route Data
-
-Add route meta to the route by adding a `<route>` block to the SFC. This will be
-directly added to the route after it is generated, and will override it.
-
-You can specify a parser to use using `<route lang="yaml">`, or set a default
-parser using `routeBlockLang` option.
-
-- **Supported parser:** JSON, JSON5, YAML
-- **Default:** JSON5
-
-```html
-<!-- index.vue -->
-<!-- use type to set index -->
-<route type="home">
-{
-  "style": { "navigationBarTitleText": "@uni-helper" }
-}
-</route>
-
-<!-- other.vue -->
-<route lang="yaml">
-style:
-  navigationBarTitleText: "@uni-helper"
-</route>
-```
-
-Import the virtual module to access the metadata of all pages
+你也可以导入 [虚拟模块](https://v5.vite.dev/guide/api-plugin.html#virtual-modules-convention) 来访问所有页面的元数据。
 
 ```ts
 /// <reference types="@uni-helper/vite-plugin-uni-pages/client" />
@@ -80,51 +56,155 @@ import { pages } from 'virtual:uni-pages'
 console.log(pages)
 ```
 
-## Configuration
+在 [这里](../../playground/pages.config.ts)，你可以找到 `uni-app` 默认的 Vite-TS 模版的 `pages.json` 是如何用 TypeScript 编写的。
+
+## 插件配置
 
 ```ts
-export interface Options {
+interface UserOptions {
   /**
-   * Whether to scan and merge pages in pages.json
+   * 生成页面路径的 TypeScript 类型声明
+   * 为 true 时在项目根目录生成 uni-pages.d.ts
+   * 为 string 时作为自定义输出路径（相对于项目根目录）
    * @default true
    */
-  mergePages: boolean
+  dts?: boolean | string
 
   /**
-   * Paths to the directory to search for page components.
-   * @default 'src/pages'
+   * 页面配置文件的加载源
+   * 基于 unconfig，支持多配置源合并
+   * 默认为 pages.config，支持 ts/mts/cts/js/cjs/mjs/json 等后缀
+   * @default 'pages.config'
+   */
+  configSource?: ConfigSource
+
+  /**
+   * 默认应用入口页面（首页）
+   * 当没有页面通过 definePage({ type: 'home' }) 标记为首页时使用
+   * 支持多个路径样式以兼容不同的目录结构
+   * @default 'pages/index' 或 'pages/index/index'
+   */
+  homePage?: string
+
+  /**
+   * 是否自动扫描目录并合并页面配置到 pages.json
+   * 关闭后仅加载用户配置文件，不扫描文件系统
+   * @default true
    */
-  dir: string
+  mergePages?: boolean
 
   /**
-   * pages.json dir
-   * @default "src"
+   * 主包页面的搜索目录
+   * 支持 glob 模式，如 'src/{pages,views}'
+   * 最终结果由 tinyglobby 解析为匹配的目录列表
+   * @default 'src/pages'
    */
-  outDir: string
+  dir?: string
 
   /**
-   * exclude page
+   * 分包页面目录的根目录列表
+   * 用于 uni-app 的分包加载功能
    * @default []
    */
-  exclude: string[]
+  subPackages?: string[]
+
+  /**
+   * pages.json 所在目录
+   * 相对于项目根目录，也是计算页面相对路径的基准
+   * @default 'src'
+   */
+  outDir?: string
+
+  /**
+   * 排除的文件/目录模式
+   * 基于 tinyglobby 的 ignore 选项
+   * @default ['node_modules', '.git', '**/__*__/**']
+   */
+  exclude?: string[]
+
+  /**
+   * 是否压缩生成的 pages.json
+   * @default false
+   */
+  minify?: boolean
 
   /**
-   * Set the default route block parser, or use `<route lang="xxx">` in SFC route block
-   * @default 'json5'
+   * 启用调试日志
+   * 为 true 时启用所有分类；为字符串时仅启用特定分类
+   * 可选分类：hmr | options | pages | subPages | error | cache | declaration | definePage
+   * 也可通过环境变量 DEBUG=vite-plugin-uni-pages:* 控制
+   * @default false
    */
-  routeBlockLang: 'json5' | 'jsonc' | 'json' | 'yaml' | 'yml'
-
-  onBeforeLoadUserConfig: (ctx: PageContext) => void
-  onAfterLoadUserConfig: (ctx: PageContext) => void
-  onBeforeScanPages: (ctx: PageContext) => void
-  onAfterScanPages: (ctx: PageContext) => void
-  onBeforeMergePageMetaData: (ctx: PageContext) => void
-  onAfterMergePageMetaData: (ctx: PageContext) => void
-  onBeforeWriteFile: (ctx: PageContext) => void
-  onAfterWriteFile: (ctx: PageContext) => void
+  debug?: boolean | debugType
+
+  // 生命周期钩子，在每个阶段完成后触发，接收 PageContext 实例
+  onBeforeLoadUserConfig?: (ctx: PageContext) => void
+  onAfterLoadUserConfig?: (ctx: PageContext) => void
+  onBeforeScanPages?: (ctx: PageContext) => void
+  onAfterScanPages?: (ctx: PageContext) => void
+  onBeforeMergePageMetaData?: (ctx: PageContext) => void
+  onAfterMergePageMetaData?: (ctx: PageContext) => void
+  onBeforeWriteFile?: (ctx: PageContext) => void
+  onAfterWriteFile?: (ctx: PageContext) => void
 }
 ```
 
-## Acknowledgement
+### 流程说明
+
+插件内部按以下顺序执行生命周期，每个阶段对应一个生命周期钩子：
+
+```
+加载用户配置 → 扫描页面文件 → 合并页面元数据 → 生成并写入 pages.json
+```
+
+- **加载用户配置**：通过 `unconfig` 加载 `pages.config.ts` 等配置文件，获取手动指定的页面元数据（`pages`、`subPackages`、`globalStyle` 等）
+- **扫描页面文件**（仅在 `mergePages: true` 时）：根据 `dir` 和 `subPackages` 扫描文件系统，为每个页面文件创建 `Page` 实例
+- **合并页面元数据**：将扫描到的页面与用户配置中的页面元数据合并
+- **生成并写入**：序列化为 `pages.json`，写入到 `outDir` 目录，并生成 TypeScript 类型声明
+
+### 配置示例
+
+```ts
+// vite.config.ts
+import UniPages from '@uni-helper/vite-plugin-uni-pages'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    UniPages({
+      dts: 'src/typings/uni-pages.d.ts', // 自定义类型声明路径
+      dir: 'src/{pages,views}', // 多目录扫描
+      subPackages: ['src/sub-package-a', 'src/sub-package-b'],
+      exclude: ['node_modules', '.git', '**/__*__/**', '**/components/**'],
+      minify: true,
+      debug: true, // 或 debug: 'pages'
+      onAfterScanPages(ctx) {
+        console.log(`扫描到 ${ctx.pages.size} 个主包页面`)
+      },
+    }),
+  ],
+})
+```
+
+### 完整类型定义
+
+请查看 [types.ts](./src/types.ts) 获取完整定义。
+
+## FAQ
+
+### 这个插件写入配置晚于 uni-app 读取配置
+
+请使用 [@uni-helper/unh](https://uni-helper.cn/unh/auto-generate)，或自行编写脚本处理。
+
+### 支持 JSX/TSX 吗？
+
+不支持，只支持 vue/nvue/uvue 文件
+
+### 文件名有限制吗？
+
+文件名内不能带有额外的 `.` 分隔符，如 `index.v1.vue` 不合法。这是小程序的限制，并非本插件的限制。
+
+## 感谢
 
-- [vite-plugin-pages](https://github.com/hannoeru/vite-plugin-pages.git)
+- [hannoeru/vite-plugin-pages](https://github.com/hannoeru/vite-plugin-pages)
+- [uni-ku/pages-json](https://github.com/uni-ku/pages-json)

package/client.d.ts

@@ -1,7 +1,7 @@
 /// <reference path="./global.d.ts" />
 
 declare module 'virtual:uni-pages' {
-  import type { SubPackage } from './src/config/types/index'
+  import type { SubPackage } from './src/config/index'
   import type { PageMetaDatum } from './src/types'
 
   export const pages: PageMetaDatum[]

package/dist/chunk-B4FMCO8f.mjs

@@ -0,0 +1,28 @@
+import "node:module";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+//#endregion
+export { __reExport as n, __exportAll as t };