uview-pro 0.6.10 → 0.6.11

package/changelog.md

@@ -1,14 +1,24 @@
-## 0.6.10（2026-07-23）
+## 0.6.11（2026-07-24）
 
-### ♻️ Code Refactoring | 代码重构
+### ✨ Features | 新功能
 
-- **u-config-provider:** 优化暗黑模式和主题初始化逻辑 ([0c010db](https://github.com/anyup/uView-Pro/commit/0c010db5b83bf9514b856cba95a7ba8d9aa56dbf))
-- **theme:** 简化初始化主题和多语言相关逻辑 ([ec5d64b](https://github.com/anyup/uView-Pro/commit/ec5d64b0c8e0b494ab21c8c4bf278cf1e2559317))
+- **vite-plugin-uni-root:** 新增内置的 root vite 插件，实现全局根组件自动注入，无需自行引入第三方插件实现 ([f5359a9](https://github.com/anyup/uView-Pro/commit/f5359a92d93150a064f6814a8700cacf272d3556))
 
 ### 👥 Contributors
 
 <a href="https://github.com/anyup"><img src="https://github.com/anyup.png?size=40" width="40" height="40" alt="anyup" title="anyup"/></a> 
 
+## 0.6.10（2026-07-23）
+
+### ♻️ Code Refactoring | 代码重构
+
+- **u-config-provider:** 优化暗黑模式和主题初始化逻辑 ([0c010db](https://github.com/anyup/uView-Pro/commit/0c010db5b83bf9514b856cba95a7ba8d9aa56dbf))
+- **theme:** 简化初始化主题和多语言相关逻辑 ([ec5d64b](https://github.com/anyup/uView-Pro/commit/ec5d64b0c8e0b494ab21c8c4bf278cf1e2559317))
+
+### 👥 Contributors
+
+<a href="https://github.com/anyup"><img src="https://github.com/anyup.png?size=40" width="40" height="40" alt="anyup" title="anyup"/></a> 
+
 ## 0.6.9（2026-07-15）
 
 ### 🐛 Bug Fixes | Bug 修复

package/package.json

@@ -2,7 +2,7 @@
     "id": "uview-pro",
     "name": "uview-pro",
     "displayName": "【支持鸿蒙】uView Pro｜基于Vue3+TS的高质量UI组件库，支持多主题、暗黑模式、多语言",
-    "version": "0.6.10",
+    "version": "0.6.11",
     "description": "uView Pro是基于Vue3+TS的多平台UI框架，提供80+高质量组件、便捷工具和常用模板，支持多主题、暗黑模式、多语言，支持H5/APP/鸿蒙/小程序多端开发。已在鸿蒙应用商店上架，欢迎体验！",
     "main": "index.ts",
     "module": "index.ts",

package/plugins/index.ts

@@ -0,0 +1 @@
+export * from './root';

package/plugins/root/README.md

@@ -0,0 +1,161 @@
+# vite-plugin-uni-root
+
+UniApp 虚拟根组件 Vite 插件，零额外依赖，纯字符串操作实现。
+
+## 解决的问题
+
+UniApp 不支持原生的根组件包裹机制，无法在全局统一注入 `u-config-provider`、`u-toast`、`u-modal` 等需要在每个页面根部存在的组件。传统方案需要在每个页面手动添加，维护成本高。
+
+本插件通过 Vite 构建时注入，自动为每个页面包裹 `<global-root-view>` 根组件，无需修改任何页面代码本身。
+
+## 技术方案
+
+### 架构
+
+```
+App.root.vue（源码）        → 在 main.ts 中导入并注册为全局组件 global-root-view
+                              → 页面模板被包裹 <global-root-view> 页面内容 </global-root-view>
+                              → 渲染时页面内容填入 <slot />
+```
+
+### 工作流程
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
+│ main.ts     │ →   │ 注入 import  │ →   │ 全局注册组件     │
+│             │     │ + 注册代码    │     │ global-root-view │
+└─────────────┘     └──────────────┘     └─────────────────┘
+                                                 │
+┌─────────────┐     ┌──────────────┐            │
+│ page.vue    │ →   │ 包裹模板     │            │
+│             │     │ <global-...> │ ←─────────┘
+└─────────────┘     └──────────────┘
+                            │
+┌─────────────┐            │
+│ App.root.vue│ →  <slot /> 接收页面内容
+└─────────────┘
+```
+
+### 三步实现
+
+1. **main.ts 注入**（`root.ts -> registerRootApp`）
+   - 在 main.ts 中注入 `import GlobalRootView from "./App.root.vue"`
+   - 注入 `app.component("global-root-view", GlobalRootView)` 注册为全局组件
+   - 注：`GlobalRootView` 仅为局部变量名，实际组件就是 `App.root.vue`
+
+2. **页面模板包裹**（`page.ts -> transformPage`）
+   - 解析 SFC，定位 `<template>` 标签的起止位置
+   - 提取 PageMeta 节点（如有则放到包裹层外部）
+   - 将模板内容包裹在 `<global-root-view>...</global-root-view>` 中
+
+3. **App.root.vue 加载**（`index.ts -> load`）
+   - 拦截 `App.root.vue` 的模块请求，从文件读取并返回
+   - 模板中的 `<slot />` 接收并渲染页面内容
+
+### 跨端兼容
+
+插件是纯 Vite 构建时插件，在 UniApp 编译之前完成源代码转换，不依赖任何平台特定 API，所有 UniApp 支持的平台均可正常工作：
+
+| 平台 | 支持 |
+|------|------|
+| H5 | ✅ |
+| 微信小程序 | ✅ |
+| 支付宝小程序 | ✅ |
+| 头条/抖音小程序 | ✅ |
+| Android App | ✅ |
+| iOS App | ✅ |
+| 鸿蒙 App | ✅ |
+
+## 使用方式
+
+### 1. 创建 App.root.vue
+
+在 `src/` 目录下创建 `App.root.vue` 文件：
+
+```vue
+<script setup lang="ts">
+import { onLoad } from '@dcloudio/uni-app';
+import { useTheme, useLocale } from 'uview-pro';
+
+const { darkMode, themes, currentTheme } = useTheme();
+const { currentLocale } = useLocale();
+
+onLoad(() => {
+    console.log('darkMode->', darkMode.value);
+    console.log('theme->', currentTheme.value?.name);
+    console.log('locale->', currentLocale.value?.name);
+});
+</script>
+
+<template>
+    <u-config-provider
+        :dark-mode="darkMode"
+        :themes="themes"
+        :current-theme="currentTheme?.name"
+        :current-locale="currentLocale?.name"
+    >
+        <slot />
+        <u-toast global></u-toast>
+        <u-modal global></u-modal>
+    </u-config-provider>
+</template>
+```
+
+关键点：`<slot />` 是页面内容的渲染位置，必须保留。
+
+### 2. 配置 vite.config.ts
+
+```ts
+// npm 安装
+import { UniRoot } from 'uview-pro/plugins';
+
+// uni_modules 安装
+import { UniRoot } from './src/uni_modules/uview-pro/plugins';
+
+export default defineConfig({
+    plugins: [
+        UniRoot(), // 放在其他插件之前
+        // ...其他插件
+    ],
+});
+```
+
+### 3. 运行
+
+```bash
+npm run dev
+```
+
+不需要修改任何页面代码，所有页面自动被 `<global-root-view>` 包裹。
+
+## 文件结构
+
+```
+src/uni_modules/uview-pro/plugins/root/
+├── index.ts     # 插件入口，Vite 插件生命周期
+├── root.ts      # main.ts 注入 + App.root.vue 处理
+├── page.ts      # 页面模板包裹转换
+└── utils.ts     # 工具函数（SFC 解析、pages.json 加载、AST 查找等）
+```
+
+## 配置项
+
+```ts
+UniRoot({
+    rootFileName: 'App.root', // 根组件文件名（不含扩展名），默认 App.root
+})
+```
+
+## HMR 支持
+
+修改 `pages.json` 后自动重载页面列表，无需手动重启开发服务器。
+
+## 注意事项
+
+- Vue 版本需 >= 3.2.13（使用 `vue/compiler-sfc` 的 `parse` API）
+- 页面模板中如有 `<page-meta>` 组件，会被提取到包裹层外部，确保微信小程序兼容
+- 页面模板中如有嵌套 `<template #slot>` 具名插槽，不影响根模板的正确识别
+
+## 致谢
+
+本插件的实现参考了 [@uni-ku/root](https://github.com/uni-ku/root)（MIT License，作者 skiyee），核心思路受其启发并进行了重新实现。

package/plugins/root/index.ts

@@ -0,0 +1,123 @@
+import type { Plugin } from 'vite';
+import { resolve, join } from 'node:path';
+import process from 'node:process';
+import { watch, readFileSync } from 'node:fs';
+import { normalizePath } from 'vite';
+import { registerRootApp, rebuildRootApp } from './root';
+import { transformPage } from './page';
+import { loadPagesJson, normalizePlatformPath, debounce } from './utils';
+
+interface UniRootOptions {
+    /** 根组件文件名（不含扩展名），默认 App.root */
+    rootFileName?: string;
+}
+
+/**
+ * 规范化模块 ID：统一路径分隔符，统一 Windows 盘符为小写
+ */
+function normalizeId(id: string) {
+    return normalizePath(id).replace(/^[A-Z]:/, match => match.toLowerCase());
+}
+
+/**
+ * UniApp 虚拟根组件 Vite 插件
+ *
+ * ## 解决的问题
+ * UniApp 不支持原生的根组件包裹机制，导致无法在全局统一注入
+ * u-config-provider、u-toast、u-modal 等组件。
+ *
+ * ## 工作原理
+ * 1. 在 main.ts 中注入 App.root.vue 的导入，并注册为全局组件 global-root-view
+ * 2. 在每个页面的 <template> 中包裹 <global-root-view> 标签
+ * 3. App.root.vue 中的 <slot /> 渲染页面内容
+ *
+ * ## 支持 HMR
+ * pages.json 变更时自动重载页面列表，无需手动重启
+ *
+ * ## 跨端兼容
+ * 纯 Vite 构建时插件，在所有 UniApp 支持的平台（H5、微信小程序、支付宝小程序、
+ * 头条小程序、Android App、iOS App、鸿蒙 App）均可正常工作
+ */
+export function UniRoot(options?: UniRootOptions): Plugin {
+    options = {
+        rootFileName: 'App.root',
+        ...options
+    };
+
+    const rootPath = process.env.UNI_INPUT_DIR || join(process.cwd(), 'src');
+    const appRootPath = resolve(rootPath, `${options.rootFileName}.vue`);
+    const pagesPath = resolve(rootPath, 'pages.json');
+
+    let pagesJson = loadPagesJson(pagesPath, rootPath);
+    let watcher: ReturnType<typeof watch> | null = null;
+    let hasPlatformPlugin = false;
+
+    const normalizedAppRoot = normalizeId(appRootPath);
+
+    return {
+        name: 'vite-plugin-uni-root',
+        enforce: 'pre', // 在其他插件之前执行，确保页面模板先被包裹
+
+        configResolved({ plugins }) {
+            // 检测是否有 uni-platform 插件，用于处理平台特定页面路径（如 .mp-weixin.vue）
+            hasPlatformPlugin = plugins.some(v => v.name === 'vite-plugin-uni-platform');
+        },
+
+        configureServer(server) {
+            // 监听 pages.json 变更，HMR 热重载页面列表
+            const reload = debounce(() => {
+                try {
+                    pagesJson = loadPagesJson(pagesPath, rootPath);
+                    server.ws.send({ type: 'full-reload' });
+                } catch (e) {
+                    console.error('[vite-plugin-uni-root] pages.json reload failed:', e);
+                }
+            }, 100);
+
+            watcher = watch(pagesPath, eventType => {
+                if (eventType === 'change') reload();
+            });
+        },
+
+        load(id) {
+            const normalizedId = normalizeId(id);
+            // 只拦截根 SFC 请求，不拦截 Vue 子模块请求（如 ?vue&type=script）
+            if (normalizedId === normalizedAppRoot) {
+                const code = readFileSync(appRootPath, 'utf-8');
+                return rebuildRootApp(code).code;
+            }
+        },
+
+        async transform(code, id) {
+            const normalizedId = normalizeId(id);
+            const normalizedRootPath = normalizeId(rootPath);
+
+            // 注入 App.root.vue 的导入，并注册为全局组件 global-root-view
+            if (normalizedId === `${normalizedRootPath}/main.ts` || normalizedId === `${normalizedRootPath}/main.js`) {
+                return registerRootApp(code, options.rootFileName);
+            }
+
+            // App.root.vue 兜底处理（已在 load 中处理，此处只处理根 SFC）
+            if (normalizedId === normalizedAppRoot) {
+                return rebuildRootApp(code);
+            }
+
+            // 页面模板包裹 <global-root-view>
+            const pageId = hasPlatformPlugin ? normalizePlatformPath(normalizedId) : normalizedId;
+            const isPage = pagesJson.some(p => pageId === p || pageId.startsWith(`${p}?`));
+            if (isPage) {
+                return transformPage(code);
+            }
+        },
+
+        buildEnd() {
+            if (watcher) {
+                watcher.close();
+                watcher = null;
+            }
+        }
+    };
+}
+
+export default UniRoot;
+export type { UniRootOptions };

package/plugins/root/page.ts

@@ -0,0 +1,54 @@
+import { parseSFC, findNode } from './utils';
+
+/**
+ * 页面模板转换：将页面内容包裹在 <global-root-view> 中
+ *
+ * <global-root-view> 是 App.root.vue 注册的全局组件，
+ * 其模板中包含 <slot />，页面内容通过插槽传入。
+ *
+ * 处理逻辑：
+ * 1. 解析 SFC，定位 <template> 标签的起止位置
+ * 2. 提取模板内容，查找 PageMeta 节点（如有则提取到包裹层外部）
+ * 3. 将剩余内容包裹在 <global-root-view>...</global-root-view> 中
+ */
+export async function transformPage(code: string) {
+    const sfc = await parseSFC(code);
+
+    if (!sfc.template) return null;
+
+    // 用正则定位 <template> 开头标签
+    const openMatch = code.match(/<template\b[^>]*>/);
+    if (!openMatch) return null;
+
+    // 使用 lastIndexOf 定位最后一个 </template>，即根 <template> 的闭合标签
+    // 避免匹配到模板内具名插槽 <template #slot> 的闭合标签
+    const closeTagStart = code.lastIndexOf('</template>');
+    if (closeTagStart === -1) return null;
+
+    const openTagEnd = openMatch.index! + openMatch[0].length;
+    const content = code.slice(openTagEnd, closeTagStart);
+
+    // 查找 page-meta 节点（如微信小程序原生的 page-meta 组件）
+    const pageMetaNode = findNode(sfc, 'PageMeta');
+    let pageMetaSource = '';
+    let newContent = content;
+
+    if (pageMetaNode) {
+        pageMetaSource = pageMetaNode.loc.source;
+        const metaStart = pageMetaNode.loc.start.offset;
+        const metaEnd = pageMetaNode.loc.end.offset;
+
+        // pageMetaNode.loc 的 offset 是相对于整个文件的，转换为相对于 content 的位置
+        const metaStartInContent = metaStart - openTagEnd;
+        const metaEndInContent = metaEnd - openTagEnd;
+
+        newContent = content.slice(0, metaStartInContent) + content.slice(metaEndInContent);
+    }
+
+    // page-meta 放在包裹层外部，内容包裹在 <global-root-view> 中
+    const wrappedContent = `\n${pageMetaSource}\n<global-root-view>${newContent}</global-root-view>\n`;
+
+    return {
+        code: code.slice(0, openTagEnd) + wrappedContent + code.slice(closeTagStart)
+    };
+}

package/plugins/root/root.ts

@@ -0,0 +1,35 @@
+/**
+ * 向 main.ts 注入 App.root.vue 的导入和全局注册
+ *
+ * 流程：
+ * 1. 在文件顶部插入 `import GlobalRootView from "./App.root.vue"`
+ * 2. 在 createSSRApp 之后插入 `app.component("global-root-view", GlobalRootView)`
+ *
+ * 注：GlobalRootView 仅为 main.ts 中的局部变量名，
+ *     实际组件就是 App.root.vue，页面通过 <global-root-view> 标签使用。
+ */
+export function registerRootApp(code: string, fileName: string = 'App.root') {
+    const importCode = `import GlobalRootView from "./${fileName}.vue";`;
+    const vueUseComponentCode = `app.component("global-root-view", GlobalRootView);`;
+
+    let newCode = importCode + '\n' + code;
+
+    // 在 createSSRApp 赋值语句之后插入组件注册代码
+    const ssrAppMatch = newCode.match(/(const\s+app\s*=\s*createSSRApp\([^)]+\);)/);
+    if (ssrAppMatch) {
+        newCode = newCode.replace(/(const\s+app\s*=\s*createSSRApp\([^)]+\);)/, `$1\n    ${vueUseComponentCode}`);
+    } else {
+        // 兜底：在 return { 之前插入
+        newCode = newCode.replace(/(createApp[\s\S]*?)(return\s*\{)/, `$1${vueUseComponentCode}\n    $2`);
+    }
+
+    return { code: newCode };
+}
+
+/**
+ * App.root.vue 模板中已使用 <slot /> 作为子内容插槽，
+ * 无需替换，直接透传。
+ */
+export function rebuildRootApp(code: string) {
+    return { code };
+}

package/plugins/root/utils.ts

@@ -0,0 +1,133 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { normalizePath } from 'vite';
+
+/**
+ * Parse Vue SFC file, return descriptor
+ */
+export async function parseSFC(code: string) {
+    try {
+        const { parse } = await import('vue/compiler-sfc');
+        return parse(code, { pad: 'space' }).descriptor;
+    } catch {
+        throw new Error('[vite-plugin-uni-root] Vue version must be 3.2.13 or higher.');
+    }
+}
+
+/**
+ * Strip JSON comments (single-line and multi-line)
+ */
+export function stripJsonComments(str: string): string {
+    return str.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+/**
+ * Convert pages.json path to absolute file path
+ */
+export function formatPagePath(root: string, path: string) {
+    return normalizePath(`${join(root, path)}.vue`).replace(/^[A-Z]:/, match => match.toLowerCase());
+}
+
+/**
+ * Load pages.json and resolve all page paths (main + subPackages)
+ */
+export function loadPagesJson(path: string, rootPath: string): string[] {
+    const raw = readFileSync(path, 'utf-8');
+    const { pages = [], subPackages = [] } = JSON.parse(stripJsonComments(raw));
+
+    return [
+        ...pages.map((page: any) => formatPagePath(rootPath, page.path)),
+        ...subPackages
+            .map(({ pages: subPages = [], root = '' }: any) => {
+                return subPages.map((page: any) => formatPagePath(join(rootPath, root), page.path));
+            })
+            .flat()
+    ];
+}
+
+/**
+ * camelCase to kebab-case: PageMeta -> page-meta
+ */
+export function toKebabCase(str: string) {
+    return str
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/[_\s]+/g, '-')
+        .toLowerCase();
+}
+
+/**
+ * kebab-case to PascalCase: page-meta -> PageMeta
+ */
+export function toPascalCase(str: string) {
+    return str.replace(/(^\w|-+\w)/g, match => match.toUpperCase().replace(/-/g, ''));
+}
+
+interface TagNode {
+    loc: {
+        source: string;
+        start: { offset: number };
+        end: { offset: number };
+    };
+}
+
+/**
+ * Find a tag node in SFC template AST by tag name
+ * Supports both kebab-case and PascalCase
+ */
+export function findNode(sfc: any, rawTagName: string): TagNode | undefined {
+    const templateSource = sfc.template?.content;
+    if (!templateSource) return;
+
+    let tagName = '';
+    if (templateSource.includes(`<${toKebabCase(rawTagName)}`)) {
+        tagName = toKebabCase(rawTagName);
+    } else if (templateSource.includes(`<${toPascalCase(rawTagName)}`)) {
+        tagName = toPascalCase(rawTagName);
+    }
+
+    if (!tagName) return;
+
+    const nodeAst = sfc.template?.ast;
+    if (!nodeAst) return;
+
+    // Recursively traverse AST to find the target node
+    const traverse = (nodes: any): TagNode | undefined => {
+        for (const node of nodes) {
+            if (node.type === 1) {
+                if (node.tag === tagName) return node;
+                if (node.children?.length) {
+                    const found = traverse(node.children);
+                    if (found) return found;
+                }
+            }
+        }
+        return undefined;
+    };
+
+    return traverse(nodeAst.children);
+}
+
+/**
+ * Normalize platform-specific page paths (.mp-weixin.vue -> .vue)
+ */
+export function normalizePlatformPath(id: string) {
+    const platform = process.env.UNI_PLATFORM;
+    if (!platform) return id;
+
+    const regex = new RegExp(`\\.${platform}\\.vue$`);
+    if (regex.test(id)) {
+        return id.replace(`.${platform}.`, '.');
+    }
+    return id;
+}
+
+/**
+ * Debounce utility
+ */
+export function debounce<T extends (...args: any[]) => void>(fn: T, delay: number) {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    return (...args: Parameters<T>) => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), delay);
+    };
+}

package/readme.md

@@ -229,11 +229,8 @@ export function createApp() {
 
 `uView Pro` 遵循[MIT](https://en.wikipedia.org/wiki/MIT_License)开源协议，意味着您无需支付任何费用，也无需授权，即可将 `uView Pro` 应用到您的产品中。
 
-## 鸣谢
+## 致谢
 
-再次感谢 `uView UI` 开发团队，以及所有为 `uView UI` 的贡献者，以及所有为 `uView Pro` 的贡献者。
+uView Pro 基于 [uView UI 1.8.8](https://github.com/umicro/uView) 进行 TypeScript 完全重构，在此向 uView UI 原作者及所有贡献者致以诚挚感谢。
 
-- [Github](https://github.com/anyup/uview-pro)
-- [Gitee](https://gitee.com/anyup/uview-pro)
-- [uView UI 1.0](https://github.com/umicro/uView)
-- [uView UI 2.0](https://github.com/umicro/uView2.0)
+同时感谢每一位为 uView Pro 提交 Issue、PR 和改进建议的社区开发者。