feat .calude

.claude/skills/uni-helper/references/plugin-pages.md

@@ -0,0 +1,186 @@
+---
+name: vite-plugin-uni-pages
+description: File-based routing system for Vite-powered uni-app projects with automatic page discovery and TypeScript support
+---
+
+# vite-plugin-uni-pages
+
+Provides file-based routing for uni-app projects using Vite. Automatically generates `pages.json` configuration from your file structure.
+
+## Installation
+
+```bash
+npm i -D @uni-helper/vite-plugin-uni-pages
+```
+
+## Basic Setup
+
+```ts
+// vite.config.ts
+import Uni from '@dcloudio/vite-plugin-uni'
+import UniPages from '@uni-helper/vite-plugin-uni-pages'
+import { defineConfig } from 'vite'
+
+// Place UniPages before Uni
+export default defineConfig({
+  plugins: [UniPages(), Uni()],
+})
+```
+
+## TypeScript Support
+
+Add types to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@uni-helper/vite-plugin-uni-pages"]
+  }
+}
+```
+
+## Global Configuration
+
+Create `pages.config.ts` (or .js/.json) for global settings:
+
+```ts
+// pages.config.ts
+import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'
+
+export default defineUniPages({
+  // Optional: manual pages have highest priority
+  pages: [],
+  globalStyle: {
+    navigationBarTextStyle: 'black',
+    navigationBarTitleText: '@uni-helper',
+  },
+})
+```
+
+## Virtual Module
+
+Access page metadata via virtual module:
+
+```ts
+/// <reference types="@uni-helper/vite-plugin-uni-pages/client" />
+import { pages } from 'virtual:uni-pages'
+
+console.log(pages)
+```
+
+## definePage Macro
+
+Define page configuration directly in SFC files:
+
+```vue
+<script setup lang="ts">
+// Object form
+definePage({
+  style: {
+    navigationBarTitleText: 'hello world',
+  },
+  middlewares: ['auth'],
+})
+
+// Function form (supports TypeScript, async)
+definePage(() => {
+  return {
+    style: {
+      navigationBarTitleText: 'dynamic title',
+    },
+  }
+})
+
+// Async form
+definePage(async () => {
+  const title = await fetchTitle()
+  return {
+    style: { navigationBarTitleText: title },
+  }
+})
+</script>
+```
+
+### Important Notes for definePage
+
+- Write inside `<script>` block
+- `definePage` runs in a different scope than SFC (no access to SFC variables)
+- Page path is auto-generated from file path
+- Only one `definePage` per file
+- Supports importing external libraries (pure JS only)
+- Supports TypeScript type imports (types are stripped)
+
+### Using with Condition Compile
+
+```vue
+<script setup>
+import { isH5 } from '@uni-helper/uni-env'
+
+definePage(() => {
+  const title = isH5 ? 'H5 Environment' : 'Other Platform'
+  return {
+    style: { navigationBarTitleText: title },
+  }
+})
+</script>
+```
+
+## Configuration Options
+
+```ts
+export interface Options {
+  /** Generate TypeScript declarations */
+  dts?: boolean | string  // default: true (outputs uni-pages.d.ts)
+
+  /** Config file pattern */
+  configSource: string    // default: 'pages.config.(ts|mts|cts|js|cjs|mjs|json)'
+
+  /** Default home page */
+  homePage: string        // default: 'pages/index' or 'pages/index/index'
+
+  /** Merge with existing pages.json */
+  mergePages: boolean     // default: true
+
+  /** Pages directory */
+  dir: string             // default: 'src/pages'
+
+  /** Sub-packages directories */
+  subPackages: string[]   // e.g., ['src/pages-sub']
+
+  /** Output directory for pages.json */
+  outDir: string          // default: 'src'
+
+  /** Exclude patterns */
+  exclude: string[]       // default: []
+
+  /** Route block language in SFC */
+  routeBlockLang: 'json5' | 'jsonc' | 'json' | 'yaml' | 'yml'  // default: 'json5'
+
+  // Lifecycle hooks
+  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
+}
+```
+
+## Usage with Layouts
+
+```vue
+<script setup>
+definePage({
+  layout: 'default',  // Specify layout
+  middlewares: ['auth'],
+})
+</script>
+```
+
+<!--
+Source references:
+- https://github.com/uni-helper/vite-plugin-uni-pages
+- https://uni-helper.js.org/vite-plugin-uni-pages
+-->