https://github.com/uni-ku/root
🦾 解决 Uniapp 无法使用公共组件问题
https://github.com/uni-ku/root
miniprogram uni-app uni-root uniapp vite-plugin vue3
Last synced: 4 months ago
JSON representation
🦾 解决 Uniapp 无法使用公共组件问题
- Host: GitHub
- URL: https://github.com/uni-ku/root
- Owner: uni-ku
- License: mit
- Created: 2024-07-08T10:50:13.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-08-22T14:46:02.000Z (8 months ago)
- Last Synced: 2024-08-28T07:18:01.954Z (8 months ago)
- Topics: miniprogram, uni-app, uni-root, uniapp, vite-plugin, vue3
- Language: TypeScript
- Homepage:
- Size: 796 KB
- Stars: 19
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-uni-app - vite - ku/root) - 一个模拟 App.vue 原有能力的根组件插件 (打包器插件)
README
# Root
借助 Vite 模拟出虚拟根组件(支持SFC的App.vue)，解决 uniapp 无法使用公共组件问题
[](https://www.npmjs.com/package/@uni-ku/root)
[](https://www.npmjs.com/package/@uni-ku/root)
[](https://www.npmjs.com/package/@uni-ku/root)
> [!TIP]
> 从 v0.2.0 开始, 已支持 HBuilderX 创建的 Vue3 项目
### 🎏 支持
- Uniapp-CLI 或 HBuilderX 创建的 Vue3 项目
- 自定义虚拟根组件文件命名
- 更高灵活度的获取虚拟根组件实例
### 📦 安装
```bash
pnpm add -D @uni-ku/root
yarn add -D @uni-ku/root
npm install -D @uni-ku/root
```
### 🚀 使用
#### 1. 引入 `@uni-ku/root`
> [!Note]
> **CLI**：`直接编写` 根目录下的 vite.config.(js|ts)
>
> **HBuilderX**：在根目录下 `创建` vite.config.(js|ts) 并写入
```ts
// vite.config.(js|ts)
import { defineConfig } from 'vite'
import UniKuRoot from '@uni-ku/root'
import Uni from '@dcloudio/vite-plugin-uni'
export default defineConfig({
plugins: [
// 若存在改变 pages.json 的插件，请将 UniKuRoot 放置其后
UniKuRoot(),
Uni()
]
})
```
#### 2. 创建 `App.ku.vue`(可自定义此根组件名称，请下拉至功能参考设置)
> [!Note]
> **CLI**: 需要在 `src目录` 下创建下 App.ku.vue (或自定义名称)
>
> **HBuilderX**: 直接在 `根目录` 下创建 App.ku.vue (或自定义名称)
通过标签 `` 或 `` 指定视图存放位置，并且可以将该标签放置到 `template` 内任意位置，**但仅可有一个**
```ts
import { ref } from 'vue'
const helloKuRoot = ref('Hello AppKuVue')
{{ helloKuRoot }}
```
> [!Important]
> 该标签与 VueRouter 中的 RouterView 功能类似，但请注意，由于Uniapp-Vue的局限性，该功能并不完全等同于VueRouter的 RouterView
### 🎉 功能
(点击展开) 功能一：自定义虚拟根组件名称(默认：App.ku.vue)
#### 1. 通过设置 vite.config.(js|ts) 下插件的参数 `rootFileName` 来自定义虚拟根组件名称
```ts
// vite.config.(js|ts)
import { defineConfig } from 'vite'
import UniKuRoot from '@uni-ku/root'
import Uni from '@dcloudio/vite-plugin-uni'
export default defineConfig({
plugins: [
UniKuRoot({
// 默认含后缀 .vue，直接设置命名即可
rootFileName: 'KuRoot',
}),
// ...other plugins
]
})
```
2. 创建/修改虚拟根组件为 `KuRoot.vue`，即可实现自定义，其余功能不变
(点击展开) 功能二：使用虚拟根组件实例(即：App.ku.vue)
> [!TIP]
> 有两种启用方式，局部或全部启用
#### 一、 局部启用
#### 1. 暴露出 App.ku.vue 里所要被使用的变量或方法
```ts
import { ref } from 'vue'
const helloKuRoot = ref('Hello AppKuVue')
const exposeRef = ref('this is form app.Ku.vue')
defineExpose({
exposeRef,
})
{{ helloKuRoot }}
```
#### 2. 在 template 内编写 root="uniKuRoot"，并通过 const uniKuRoot = ref() 获取模板引用
> [!TIP]
> uniKuRoot 是同一个变量，你可以根据你命名相关命名
```ts
import { ref } from 'vue'
const uniKuRoot = ref()
Hello UniKuRoot
```
#### 二、全局启用
#### 1. 通过配置 `enabledGlobalRef` 开启全局自动注入 App.ku 实例
```ts
// vite.config.(js|ts)
import { defineConfig } from 'vite'
import UniKuRoot from '@uni-ku/root'
import Uni from '@dcloudio/vite-plugin-uni'
export default defineConfig({
plugins: [
UniKuRoot({
enabledGlobalRef: true
}),
Uni()
]
})
```
#### 2. 暴露出 App.ku 里所要被使用的变量或方法
```ts
import { ref } from 'vue'
const helloKuRoot = ref('Hello UniKuRoot')
const exposeRef = ref('this is from App.ku.vue')
defineExpose({
exposeRef,
})
{{ helloKuRoot }}
```
#### 3. 通过特有内置方法 `getCurrentPages()` 获取暴露的数据
```ts
import { onMounted, ref } from 'vue'
const pagesStack = getCurrentPages()
const uniKuRoot = ref()
onMounted(() => {
uniKuRoot.value = pagesStack[pagesStack.length - 1].$vm.$refs.uniKuRoot
})
Hello UniKuRoot
```
### ✨ 例子
> [!TIP]
> 以下例子均以 **CLI** 创建项目为例, **HBuilderX** 项目设置同理, 只要注意是否需要包含 **src目录** 即可
(点击展开) 示例一：全局共享组件例子：Toast
> 不仅是 Toast 组件，还可以是 Message、LoginPopup 等等
- 🔗 [查看以下完整项目例子](https://github.com/uni-ku/root/tree/main/examples)
1. 编写 Toast 组件
```ts
import { useToast } from '@/composables/useToast'
const { globalToastState, hideToast } = useToast()
welcome to use @uni-ku/root
.toast-wrapper{
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
background-color: rgba(0, 0, 0, 0.5);
display: flex;
align-items: center;
justify-content: center;
}
.toast-box{
background: white;
color: black;
}
```
2. 实现 Toast 组合式API
```ts
// src/composables/useToast
import { ref } from 'vue'
const globalToastState = ref(false)
export function useToast() {
function showToast() {
globalToastState.value = true
}
function hideToast() {
globalToastState.value = false
}
return {
globalToastState,
showToast,
hideToast,
}
}
```
3. 挂载至 App.ku.vue
```ts
import GlobalToast from '@/components/GlobalToast.vue'
```
4. 视图内部触发全局 Toast 组件
```ts
import { useToast } from '@/composables/useToast'
const { showToast } = useToast()
Hello UniKuRoot
视图内触发展示Toast
```
(点击展开) 示例二：全局共享布局例子：ConfigProvider
> 不仅仅只有ConfigProvider，还能是Layout、NavBar、TabBar等等！
1. 以 Wot 组件库中 WdConfigProvider 为例子，[了解更多Wot点这里](https://github.com/Moonofweisheng/wot-design-uni)
```ts
import { useTheme } from './composables/useTheme'
const { theme, themeVars } = useTheme({
buttonPrimaryBgColor: '#07c160',
buttonPrimaryColor: '#07c160'
})
Hello AppKuVue
```
2. 编写主题相关组合式API
```ts
// src/composables/useTheme.ts
import type { ConfigProviderThemeVars } from 'wot-design-uni'
import { ref } from 'vue'
const theme = ref<'light' | 'dark'>(false)
const themeVars = ref()
export function useTheme(vars?: ConfigProviderThemeVars) {
vars && (themeVars.value = vars)
function toggleTheme(mode?: 'light' | 'dark') {
theme.value = mode || (theme.value === 'light' ? 'dark' : 'light')
}
return {
theme,
themeVars,
toggleTheme,
}
}
```
3. 切换主题模式
```ts
import { useTheme } from '@/composables/useTheme'
const { theme, toggleTheme } = useTheme()
切换主题，当前模式：{{ theme }}
```
### 📝 待办
- [x] 支持热更新
- [x] 支持VueSFC
- [x] 支持小程序PageMeta
- [ ] 支持 App.ku.vue 内直接编写控制逻辑
- [ ] 补全单元测试
### 💬 社区
- QQ 交流群 ([897784703](https://qm.qq.com/q/hX1smd93MI))
### 🏝 周边
|项目|描述|
|---|---|
|[Wot Design Uni](https://github.com/Moonofweisheng/wot-design-uni/)|一个基于Vue3+TS开发的uni-app组件库，提供70+高质量组件|
|[Create Uni](https://github.com/uni-helper/create-uni)|一个用于快速创建 uni-app 项目的轻量脚手架工具|
### 💖 赞赏
如果我的工作帮助到了您，可以请我吃辣条，使我能量满满 ⚡
> 请留下您的Github用户名，感谢 ❤
#### 微信赞赏
#### 赞赏榜单
