{"id":14380636,"url":"https://github.com/uni-ku/root","last_synced_at":"2026-01-26T03:37:55.730Z","repository":{"id":248499124,"uuid":"825706388","full_name":"uni-ku/root","owner":"uni-ku","description":"🦾 解决 Uniapp 无法使用根部组件问题","archived":false,"fork":false,"pushed_at":"2025-09-18T05:43:51.000Z","size":364,"stargazers_count":107,"open_issues_count":3,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-18T07:32:09.599Z","etag":null,"topics":["miniprogram","uni-app","uni-root","uniapp","vite-plugin","vue3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uni-ku.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-08T10:50:13.000Z","updated_at":"2025-09-18T05:43:55.000Z","dependencies_parsed_at":"2024-08-05T09:47:45.900Z","dependency_job_id":"bf02c258-defc-4a95-9b35-12bdc472a260","html_url":"https://github.com/uni-ku/root","commit_stats":null,"previous_names":["uni-ku/root"],"tags_count":20,"template":false,"template_full_name":"skiyee/quick-template","purl":"pkg:github/uni-ku/root","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Froot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Froot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Froot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Froot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uni-ku","download_url":"https://codeload.github.com/uni-ku/root/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Froot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28765962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T03:19:35.311Z","status":"ssl_error","status_checked_at":"2026-01-26T03:19:13.815Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["miniprogram","uni-app","uni-root","uniapp","vite-plugin","vue3"],"created_at":"2024-08-28T14:01:20.376Z","updated_at":"2026-01-26T03:37:55.723Z","avatar_url":"https://github.com/uni-ku.png","language":"TypeScript","funding_links":[],"categories":["打包器插件"],"sub_categories":[],"readme":"# Root\n\n借助 Vite 模拟出虚拟根组件(支持SFC的App.vue)，解决 uniapp 无法使用公共组件问题\n\n[![NPM version](https://img.shields.io/npm/v/@uni-ku/root?color=92DCD2\u0026labelColor=18181B\u0026label=npm)](https://www.npmjs.com/package/@uni-ku/root)\n[![NPM downloads](https://img.shields.io/npm/dm/@uni-ku/root?color=92DCD2\u0026labelColor=18181B\u0026label=downloads)](https://www.npmjs.com/package/@uni-ku/root)\n[![LICENSE](https://img.shields.io/github/license/uni-ku/root?style=flat\u0026color=92DCD2\u0026labelColor=18181B\u0026label=license)](https://www.npmjs.com/package/@uni-ku/root)\n\n\u003e [!Tip]\n\u003e 我们提供基于 Uniapp 技术支持服务及定制开发，详细需求可添加作者了解，联系QQ: 319619193\n\n\u003e [!Note]\n\u003e Root 支持 HBuilderX 或者 CLI 创建的 Uniapp Vue3 项目\n\u003e\n\u003e 新增可通过 useXXX() 组合式方法调用的例子，适用于各大由此方案实现的组件库，请往下拉至例子区域\n\n### 🎏 支持\n\n- 自定义虚拟根组件文件命名(App.ku.vue文件命名支持更换)\n- 更高灵活度的获取虚拟根组件实例(获取KuRootView的Ref)\n- 自动提取PageMeta到页面顶层(自动提升小程序PageMeta[用于阻止滚动穿透]组件)\n\n### 📦 安装\n\n```bash\npnpm add -D @uni-ku/root\n\nyarn add -D @uni-ku/root\n\nnpm install -D @uni-ku/root\n```\n\n### 🚀 使用\n\n#### 1. 引入 `@uni-ku/root`\n\n```ts\n// vite.config.(js|ts)\n\nimport Uni from '@dcloudio/vite-plugin-uni'\nimport UniKuRoot from '@uni-ku/root'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [\n    // 若存在改变 pages.json 的插件，请将 UniKuRoot 放置其后\n    UniKuRoot(),\n    Uni()\n  ]\n})\n```\n\n\u003e [!Note]\n\u003e **CLI**：`直接编写` 根目录下的 vite.config.(js|ts)\n\u003e\n\u003e **HBuilderX**：在根目录下 `创建`  vite.config.(js|ts) 并写入\n\n#### 2. 创建 `App.ku.vue`(可自定义此根组件名称，请下拉至功能参考设置)\n\n通过标签 `\u003cKuRootView /\u003e` 或 `\u003cku-root-view /\u003e` 指定视图存放位置，并且可以将该标签放置到 `template` 内任意位置，**但仅可有一个**\n\n```vue\n\u003c!-- src/App.ku.vue | App.ku.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { ref } from 'vue'\n\nconst helloKuRoot = ref('Hello AppKuVue')\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv\u003e{{ helloKuRoot }}\u003c/div\u003e\n  \u003c!-- 顶级 KuRootView --\u003e\n  \u003cKuRootView /\u003e\n\n  \u003c!-- 或内部 KuRootView，无论放置哪一个层级都被允许，但仅可有一个！ --\u003e\n  \u003cdiv\u003e\n    \u003cKuRootView /\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\n\u003e [!Note]\n\u003e **CLI**: 需要在 `src目录` 下创建下 App.ku.vue (或自定义名称)\n\u003e\n\u003e **HBuilderX**: 直接在 `根目录` 下创建 App.ku.vue (或自定义名称)\n\n\u003e [!Important]\n\u003e 该标签与 VueRouter 中的 RouterView 功能类似，但请注意，由于Uniapp-Vue的局限性，该功能并不完全等同于VueRouter的 RouterView\n\n### 🎉 功能\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n  \u003cstrong\u003e (点击展开) 功能一：自定义虚拟根组件名称(默认：App.ku.vue)\u003c/strong\u003e\n\u003c/summary\u003e\n\n#### 1. 通过设置 vite.config.(js|ts) 下插件的参数 `rootFileName` 来自定义虚拟根组件名称\n\n```ts\n// vite.config.(js|ts)\n\nimport Uni from '@dcloudio/vite-plugin-uni'\nimport UniKuRoot from '@uni-ku/root'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [\n    UniKuRoot({\n      // 默认含后缀 .vue，直接设置命名即可\n      rootFileName: 'KuRoot',\n    }),\n    // ...other plugins\n  ]\n})\n```\n\n#### 2. 创建/修改虚拟根组件为 `KuRoot.vue`，即可实现自定义，其余功能不变\n\n```ts\n// App.ku.vue 文件重命名为 KuRoot.vue\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n  \u003cstrong\u003e (点击展开) 功能二：使用虚拟根组件实例(即：App.ku.vue)\u003c/strong\u003e\n\u003c/summary\u003e\n\u003cbr/\u003e\n\n\u003e 有两种启用方式，局部或全部启用\n\n#### 一、 局部启用\n\n#### 1. 暴露出 App.ku.vue 里所要被使用的变量或方法\n\n```vue\n\u003c!-- src/App.ku.vue | App.ku.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { ref } from 'vue'\n\nconst helloKuRoot = ref('Hello AppKuVue')\n\nconst exposeRef = ref('this is form app.Ku.vue')\n\ndefineExpose({\n  exposeRef,\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv\u003e\n    \u003cdiv\u003e{{ helloKuRoot }}\u003c/div\u003e\n    \u003cKuRootView /\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\n#### 2. 在 template 内编写 root=\"uniKuRoot\"，并通过 const uniKuRoot = ref() 获取模板引用\n\n\u003e uniKuRoot 仅是一个变量，你可以根据你习惯重新命名\n\n```vue\n\u003c!-- src/pages/*.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { ref } from 'vue'\n\nconst uniKuRoot = ref()\n\u003c/script\u003e\n\n\u003ctemplate root=\"uniKuRoot\"\u003e\n  \u003cview\u003e\n    Hello UniKuRoot\n  \u003c/view\u003e\n\u003c/template\u003e\n```\n\n#### 二、全局启用\n\n#### 1. 通过配置 `enabledGlobalRef` 开启全局自动注入 App.ku 实例\n\n```ts\n// vite.config.(js|ts)\n\nimport Uni from '@dcloudio/vite-plugin-uni'\nimport UniKuRoot from '@uni-ku/root'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [\n    UniKuRoot({\n      enabledGlobalRef: true\n    }),\n    Uni()\n  ]\n})\n```\n\n#### 2. 暴露出 App.ku 里所要被使用的变量或方法\n\n```vue\n\u003c!-- src/App.ku.vue | App.ku.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { ref } from 'vue'\n\nconst helloKuRoot = ref('Hello UniKuRoot')\n\nconst exposeRef = ref('this is from App.ku.vue')\n\ndefineExpose({\n  exposeRef,\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv\u003e\n    \u003cdiv\u003e{{ helloKuRoot }}\u003c/div\u003e\n    \u003cKuRootView /\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\n#### 3. 通过特有内置方法 `getCurrentPages()` 获取暴露的数据\n\n```vue\n\u003c!-- src/pages/*.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { onMounted, ref } from 'vue'\n\nconst pagesStack = getCurrentPages()\nconst uniKuRoot = ref()\n\nonMounted(() =\u003e {\n  uniKuRoot.value = pagesStack[pagesStack.length - 1].$vm.$refs.uniKuRoot\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cview\u003e\n    Hello UniKuRoot\n  \u003c/view\u003e\n\u003c/template\u003e\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n  \u003cstrong\u003e(点击展开) 功能三：过滤掉不需要根组件的页面\u003c/strong\u003e\n\u003c/summary\u003e\n\u003cbr /\u003e\n\n如果遇到一些不需要根组件的页面，可以设置 `excludePages` 选项来过滤\n\n\u003e `excludePages` 选项支持采用 glob 模式进行编写\n\n```ts\n// vite.config.(js|ts)\n\nimport Uni from '@dcloudio/vite-plugin-uni'\nimport UniKuRoot from '@uni-ku/root'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [\n    UniKuRoot({\n      excludePages: [\n        'pages/exclude.vue',\n        'pages/exclude/**/*.vue'\n      ],\n    }),\n    Uni()\n  ]\n})\n```\n\n\u003c/details\u003e\n\n### ✨ 例子\n\n\u003e [!TIP]\n\u003e 以下例子均以 **CLI** 创建项目为例, **HBuilderX** 项目设置同理, 只要注意是否需要包含 **src目录** 即可\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n  \u003cstrong\u003e(点击展开) 示例一：全局共享组件例子：Toast\u003c/strong\u003e\n\u003c/summary\u003e\n\u003cbr /\u003e\n\n\u003e 不仅是 Toast 组件，还可以是 Message、LoginPopup 等等\n\n- 🔗 [查看以下完整项目例子](https://github.com/uni-ku/root/tree/main/examples)\n\n1. 编写 Toast 组件\n\n```vue\n\u003c!-- src/components/GlobalToast.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { useToast } from '@/composables/useToast'\n\nconst { globalToastState, hideToast } = useToast()\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv v-if=\"globalToastState\" class=\"toast-wrapper\" @click=\"hideToast\"\u003e\n    \u003cdiv class=\"toast-box\"\u003e\n      welcome to use @uni-ku/root\n    \u003c/div\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cstyle scoped\u003e\n.toast-wrapper{\n  position: fixed;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 100%;\n  background-color: rgba(0, 0, 0, 0.5);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n\n.toast-box{\n  background: white;\n  color: black;\n}\n\u003c/style\u003e\n```\n\n2. 实现 Toast 组合式API\n\n```ts\n// src/composables/useToast\n\nimport { ref } from 'vue'\n\nconst globalToastState = ref(false)\n\nexport function useToast() {\n  function showToast() {\n    globalToastState.value = true\n  }\n\n  function hideToast() {\n    globalToastState.value = false\n  }\n\n  return {\n    globalToastState,\n    showToast,\n    hideToast,\n  }\n}\n```\n\n3. 挂载至 App.ku.vue\n\n```vue\n\u003c!-- src/App.ku.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport GlobalToast from '@/components/GlobalToast.vue'\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cKuRootView /\u003e\n  \u003cGlobalToast /\u003e\n\u003c/template\u003e\n```\n\n4. 视图内部触发全局 Toast 组件\n\n```vue\n\u003c!-- src/pages/*.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { useToast } from '@/composables/useToast'\n\nconst { showToast } = useToast()\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cview\u003e\n    Hello UniKuRoot\n  \u003c/view\u003e\n  \u003cbutton @click=\"showToast\"\u003e\n    视图内触发展示Toast\n  \u003c/button\u003e\n\u003c/template\u003e\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n  \u003cstrong\u003e(点击展开) 示例二：全局共享布局例子：ConfigProvider\u003c/strong\u003e\n\u003c/summary\u003e\n\u003cbr /\u003e\n\n\u003e 不仅仅只有ConfigProvider，还能是Layout、NavBar、TabBar等等！\n\n如果你正在使用wot组件，那么可以直接从这里获取到相关使用文档[点击查看](https://wot-design-uni.cn/component/config-provider.html#%E5%85%A8%E5%B1%80%E5%85%B1%E4%BA%AB)\n\n1. 以 Wot 组件库中 WdConfigProvider 为例子\n\n```vue\n\u003c!-- src/App.ku.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { useTheme } from './composables/useTheme'\n\nconst { theme, themeVars } = useTheme({\n  buttonPrimaryBgColor: '#07c160',\n  buttonPrimaryColor: '#07c160'\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv\u003eHello AppKuVue\u003c/div\u003e\n  \u003c!-- 假设已注册 WdConfigProvider 组件 --\u003e\n  \u003cWdConfigProvider :theme=\"theme\" :theme-vars=\"themeVars\"\u003e\n    \u003cKuRootView /\u003e\n  \u003c/WdConfigProvider\u003e\n\u003c/template\u003e\n```\n\n2. 编写主题相关组合式API\n\n```ts\n// src/composables/useTheme.ts\n\nimport type { ConfigProviderThemeVars } from 'wot-design-uni'\nimport { ref } from 'vue'\n\nconst theme = ref\u003c'light' | 'dark'\u003e(false)\nconst themeVars = ref\u003cConfigProviderThemeVars\u003e()\n\nexport function useTheme(vars?: ConfigProviderThemeVars) {\n  vars \u0026\u0026 (themeVars.value = vars)\n\n  function toggleTheme(mode?: 'light' | 'dark') {\n    theme.value = mode || (theme.value === 'light' ? 'dark' : 'light')\n  }\n\n  return {\n    theme,\n    themeVars,\n    toggleTheme,\n  }\n}\n```\n\n3. 切换主题模式\n\n```vue\n\u003c!-- src/pages/*.vue --\u003e\n\n\u003cscript setup lang=\"ts\"\u003e\nimport { useTheme } from '@/composables/useTheme'\n\nconst { theme, toggleTheme } = useTheme()\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cbutton @click=\"toggleTheme\"\u003e\n    切换主题，当前模式：{{ theme }}\n  \u003c/button\u003e\n\u003c/template\u003e\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n  \u003cstrong\u003e(点击展开) 示例三：Wot的 Toast、Notify 组件的调用方式\u003c/strong\u003e\n\u003c/summary\u003e\n\u003cbr /\u003e\n\n\u003e 以下示例以 Toast 为例子\n\n1. 挂载组件\n\n```vue\n\u003c!-- src/App.ku.vue | App.ku.vue --\u003e\n\u003ctemplate\u003e\n  \u003cKuRootView /\u003e\n  \u003c!-- 注意：需要先注册 WdToast 组件才可使用 --\u003e\n  \u003cWdToast /\u003e\n\u003c/template\u003e\n```\n\n2. 调用组件\n\n```vue\n\u003c!-- src/pages/*.vue --\u003e\n\u003cscript setup lang=\"ts\"\u003e\nimport { useToast } from '@/uni_modules/wot-design-uni'\n\nconst toast = useToast()\n\nfunction showToast() {\n  toast.show('Hey there, this is @uni-ku/root')\n}\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cview\u003e这是在任意页面才可见\u003c/view\u003e\n  \u003cWdButton @click=\"showToast\"\u003e\n    展示Toast信息\n  \u003c/WdButton\u003e\n\u003c/template\u003e\n```\n\n\u003c/details\u003e\n\n### 📝 待办\n\n- [x] 支持热更新\n- [x] 支持VueSFC\n- [x] 支持小程序PageMeta\n- [ ] 支持 App.ku.vue 内直接编写控制逻辑\n- [ ] 补全单元测试\n\n### 🤔 与uni-helper-layouts的区别\n\n\u003e [!Important]\n\u003e root的核心理念就是尽可能的靠近Vue中的App.vue，layouts 则是类nuxt的布局系统\n\n- root 是 layouts 之上，提供更多的自由度，能够实现layouts的效果，更加容易控制布局组件\n- root 能够使用PageMeta，自动提取到页面顶层节点\n- root 拥有不同的方式使用模板引用\n\n\u003e [github: uni-helper-layouts](https://github.com/uni-helper/vite-plugin-uni-layouts)\n\n### 📣 社区\n\n- QQ 交流群 ([976866565](https://qm.qq.com/q/FyHN1X5qwK))\n\n### 🏝 周边\n\n| 项目                                                                | 描述                                                  |\n|---------------------------------------------------------------------|-------------------------------------------------------|\n| [Wot Design Uni](https://github.com/Moonofweisheng/wot-design-uni/) | 一个基于Vue3+TS开发的uni-app组件库，提供70+高质量组件 |\n| [Create Uni](https://github.com/uni-helper/create-uni)              | 一个用于快速创建 uni-app 项目的轻量脚手架工具         |\n| [Uni Best](https://github.com/unibest-tech/unibest)                 | 最好用的 uniapp 开发框架                              |\n\n### 💖 赞赏\n\n如果我的工作帮助到了您，可以请我吃辣条，使我能量满满 ⚡\n\n\u003e 请留下您的Github用户名，感谢 ❤\n\n#### 爱发电赞赏\n\n[https://afdian.com/a/skiyee](https://afdian.com/a/skiyee)\n\n#### 微信赞赏\n\n\u003cimg src=\"https://cdn.jsdelivr.net/gh/Skiyee/sponsors@main/assets/wechat-pay.png\" alt=\"wechat-pay\" width=\"320\" /\u003e\n\n#### 赞赏榜单\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Skiyee/sponsors\"\u003e\n    \u003cimg alt=\"sponsors\" src=\"https://cdn.jsdelivr.net/gh/Skiyee/Skiyee@main/sponsors.svg\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funi-ku%2Froot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funi-ku%2Froot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funi-ku%2Froot/lists"}