@univa/core 0.0.8 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +441 -435
- package/THIRD-PARTY-NOTICES +216 -0
- package/dist/global.d.ts +5 -4
- package/dist/index.cjs +143 -14
- package/dist/index.d.cts +24 -6
- package/dist/index.d.ts +24 -6
- package/dist/index.js +146 -16
- package/package.json +16 -14
package/README.md
CHANGED
|
@@ -1,435 +1,441 @@
|
|
|
1
|
-
# @univa/core
|
|
2
|
-
|
|
3
|
-
> 🚀 开箱即用的 uni-app Vite 插件集，以「约定优于配置」理念整合 uni-app 生态最佳实践。
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@univa/core)
|
|
6
|
-
[](./LICENSE)
|
|
7
|
-
|
|
8
|
-
## 为什么选择 Univa？
|
|
9
|
-
|
|
10
|
-
在 uni-app + Vite 生态中，一个完整项目通常需要集成 5~7 个插件：`@dcloudio/vite-plugin-uni`、`unplugin-auto-import`、`@uni-helper/vite-plugin-uni-components`、`@uni-helper/vite-plugin-uni-pages`、`@uni-helper/vite-plugin-uni-layouts`、`@uni-ku/root`、`unocss/vite`……每个插件都有自己的配置项，分散在 `vite.config.ts` 中，维护成本高、心智负担重。
|
|
11
|
-
|
|
12
|
-
Univa 将这些插件整合为**单一入口** `Univa()`，通过一份 `univa.config.ts` 声明工程约定，其余全部自动装配。
|
|
13
|
-
|
|
14
|
-
### 核心特性
|
|
15
|
-
|
|
16
|
-
- **零参数入口**：`vite.config.ts` 只需 `plugins: [...Univa()]`，无需传任何配置
|
|
17
|
-
- **约定式目录**：`pages/`、`layouts/`、`components/` 等目录自动识别
|
|
18
|
-
- **统一自动导入**：`imports.apis` 一个字段同时管理预设导入与目录扫描
|
|
19
|
-
- **应用级配置**：`pages.json` 的 `globalStyle`/`tabBar` 等直接写在 `univa.config.ts`
|
|
20
|
-
- **逃生口设计**：`overrides` 字段可直接覆盖任意底层插件选项
|
|
21
|
-
- **自动产物集中**：所有生成文件统一输出到 `.univa/` 目录，便于 `.gitignore`
|
|
22
|
-
|
|
23
|
-
## 安装
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
# pnpm
|
|
27
|
-
pnpm add -D @univa/core
|
|
28
|
-
|
|
29
|
-
# yarn
|
|
30
|
-
yarn add -D @univa/core
|
|
31
|
-
|
|
32
|
-
# npm
|
|
33
|
-
npm install -D @univa/core
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
> 前置依赖：项目需已安装 `vite` 与 `@dcloudio/uni-app` 相关依赖。
|
|
37
|
-
|
|
38
|
-
## 快速开始
|
|
39
|
-
|
|
40
|
-
### 1. 配置 `vite.config.ts`
|
|
41
|
-
|
|
42
|
-
```ts
|
|
43
|
-
// vite.config.ts
|
|
44
|
-
import { Univa } from '@univa/core'
|
|
45
|
-
import { defineConfig } from 'vite'
|
|
46
|
-
|
|
47
|
-
export default defineConfig({
|
|
48
|
-
plugins: [
|
|
49
|
-
// 零参数，所有约定走 univa.config.ts
|
|
50
|
-
...Univa(),
|
|
51
|
-
],
|
|
52
|
-
})
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
### 2. 创建 `univa.config.ts`
|
|
56
|
-
|
|
57
|
-
在项目根目录创建 `univa.config.ts`（或 `univa.config.mts`）：
|
|
58
|
-
|
|
59
|
-
```ts
|
|
60
|
-
// univa.config.ts
|
|
61
|
-
import { defineConfig } from '@univa/core'
|
|
62
|
-
|
|
63
|
-
export default defineConfig({
|
|
64
|
-
// 应用级 pages.json 配置
|
|
65
|
-
pages: {
|
|
66
|
-
globalStyle: {
|
|
67
|
-
navigationBarTitleText: '我的应用',
|
|
68
|
-
},
|
|
69
|
-
},
|
|
70
|
-
})
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
### 3. 开始开发
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
pnpm dev
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
Univa 会自动：
|
|
80
|
-
- 扫描 `src/pages/` 生成 `pages.json`
|
|
81
|
-
- 扫描 `src/pages-sub/*/` 生成分包配置
|
|
82
|
-
- 自动导入 `vue`、`uni-app` 及 `src/composables/`、`src/hooks/`、`src/stores/` 等目录的导出
|
|
83
|
-
- 自动注册 `src/components/` 下的组件
|
|
84
|
-
- 生成虚拟根组件 `src/App.ku.vue`（若不存在）
|
|
85
|
-
- 输出类型声明到 `.univa/` 目录
|
|
86
|
-
|
|
87
|
-
## 目录约定
|
|
88
|
-
|
|
89
|
-
默认目录结构（均相对 `srcDir`，默认 `src`）：
|
|
90
|
-
|
|
91
|
-
```
|
|
92
|
-
src/
|
|
93
|
-
├── pages/ # 主包页面（自动扫描）
|
|
94
|
-
├── pages-sub/ # 分包根目录（默认扫描 pages-sub/* 下第一层）
|
|
95
|
-
│ └── demo/
|
|
96
|
-
├── layouts/ # 布局组件
|
|
97
|
-
├── components/ # 全局组件（自动注册）
|
|
98
|
-
├── components-biz/ # 业务组件（自动注册）
|
|
99
|
-
├── composables/ # 组合式 API（自动导入）
|
|
100
|
-
├── hooks/ # 自定义 Hooks（自动导入）
|
|
101
|
-
├── stores/ # 状态管理（自动导入）
|
|
102
|
-
├── constants/ # 常量（自动导入）
|
|
103
|
-
└── App.ku.vue # 虚拟根组件（自动生成）
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
自定义目录约定：
|
|
107
|
-
|
|
108
|
-
```ts
|
|
109
|
-
// univa.config.ts
|
|
110
|
-
import { defineConfig } from '@univa/core'
|
|
111
|
-
|
|
112
|
-
export default defineConfig({
|
|
113
|
-
dirs: {
|
|
114
|
-
pages: 'views', // 主包页面目录
|
|
115
|
-
subPackages: ['subpkgs/*'], // 分包目录
|
|
116
|
-
layouts: 'layouts', // 布局目录
|
|
117
|
-
},
|
|
118
|
-
})
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
## 自动导入
|
|
122
|
-
|
|
123
|
-
### `imports.apis` 统一字段
|
|
124
|
-
|
|
125
|
-
`apis` 支持三种形式，Univa 内部自动区分：
|
|
126
|
-
|
|
127
|
-
| 形式 | 示例 | 说明 |
|
|
128
|
-
|------|------|------|
|
|
129
|
-
| 预设名 | `'vue'`、`'uni-app'`、`'pinia'` | 识别为 unplugin-auto-import 预设 |
|
|
130
|
-
| 目录 glob | `'composables/**'`、`'hooks/**'` | 识别为目录扫描（相对 srcDir） |
|
|
131
|
-
| inline preset | `{ from: 'wot-design-uni', imports: ['useToast'] }` | 直接传给 unplugin-auto-import |
|
|
132
|
-
|
|
133
|
-
**识别规则**：含 glob 字符（`*?[{}]`）或路径分隔符（`/`）的字符串 → 目录扫描；否则 → 预设名。scope 包名（如 `@vueuse/core`）也算预设名。
|
|
134
|
-
|
|
135
|
-
默认值：
|
|
136
|
-
|
|
137
|
-
```ts
|
|
138
|
-
apis: ['vue', 'uni-app', 'composables/**', 'stores/**', 'hooks/**', 'constants/**']
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
自定义示例：
|
|
142
|
-
|
|
143
|
-
```ts
|
|
144
|
-
// univa.config.ts
|
|
145
|
-
import { defineConfig } from '@univa/core'
|
|
146
|
-
|
|
147
|
-
export default defineConfig({
|
|
148
|
-
imports: {
|
|
149
|
-
apis: [
|
|
150
|
-
// 预设名
|
|
151
|
-
'vue',
|
|
152
|
-
'uni-app',
|
|
153
|
-
'pinia',
|
|
154
|
-
'@vueuse/core',
|
|
155
|
-
// 目录扫描（相对 srcDir）
|
|
156
|
-
'composables/**',
|
|
157
|
-
'stores/**',
|
|
158
|
-
// negation 排除
|
|
159
|
-
'!hooks/**/_internal/**',
|
|
160
|
-
// inline preset
|
|
161
|
-
{ from: 'wot-design-uni', imports: ['useToast', 'useMessage'] },
|
|
162
|
-
// 命名导入映射
|
|
163
|
-
{ '@fun-design/use': ['useState', 'useVModel'] },
|
|
164
|
-
],
|
|
165
|
-
// 组件自动注册目录（glob，相对 srcDir）
|
|
166
|
-
components: ['components/**', 'components-biz/**'],
|
|
167
|
-
},
|
|
168
|
-
})
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
### 类型声明
|
|
172
|
-
|
|
173
|
-
类型声明文件自动生成到 `.univa/` 目录：
|
|
174
|
-
|
|
175
|
-
- `.univa/auto-imports.d.ts` — API 自动导入类型
|
|
176
|
-
- `.univa/components.d.ts` — 组件自动注册类型
|
|
177
|
-
- `.univa/uni-pages.d.ts` — 页面路由类型
|
|
178
|
-
|
|
179
|
-
在 `tsconfig.json` 中引入：
|
|
180
|
-
|
|
181
|
-
```json
|
|
182
|
-
{
|
|
183
|
-
"include": [".univa/**/*.d.ts"]
|
|
184
|
-
}
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
## 应用级配置（pages）
|
|
188
|
-
|
|
189
|
-
`pages.json` 的应用级内容（`globalStyle`、`tabBar`、`easycom` 等）可直接写在 `univa.config.ts`：
|
|
190
|
-
|
|
191
|
-
```ts
|
|
192
|
-
// univa.config.ts
|
|
193
|
-
import { defineConfig } from '@univa/core'
|
|
194
|
-
|
|
195
|
-
export default defineConfig({
|
|
196
|
-
pages: {
|
|
197
|
-
globalStyle: {
|
|
198
|
-
navigationBarTextStyle: 'black',
|
|
199
|
-
navigationBarTitleText: '我的应用',
|
|
200
|
-
navigationBarBackgroundColor: '#FFFFFF',
|
|
201
|
-
backgroundColor: '#F8F8F8',
|
|
202
|
-
},
|
|
203
|
-
tabBar: {
|
|
204
|
-
color: '#7A7E83',
|
|
205
|
-
selectedColor: '#3CC51F',
|
|
206
|
-
backgroundColor: '#FFFFFF',
|
|
207
|
-
list: [
|
|
208
|
-
{ pagePath: 'pages/index/index', text: '首页' },
|
|
209
|
-
{ pagePath: 'pages/user/index', text: '我的' },
|
|
210
|
-
],
|
|
211
|
-
},
|
|
212
|
-
},
|
|
213
|
-
})
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
Univa 会读取 `pages` 字段，自动生成 `.univa/pages-config.ts`，供 `@uni-helper/vite-plugin-uni-pages` 消费。
|
|
217
|
-
|
|
218
|
-
> **注意**：`pages`（页面列表）和 `subPackages`（分包列表）由目录扫描自动填充，请勿在配置中手写。
|
|
219
|
-
|
|
220
|
-
### 页面内配置（definePage）
|
|
221
|
-
|
|
222
|
-
在页面文件中使用 `definePage` 宏声明页面级配置：
|
|
223
|
-
|
|
224
|
-
```vue
|
|
225
|
-
<!-- src/pages/about.vue -->
|
|
226
|
-
<script setup lang="ts">
|
|
227
|
-
definePage({
|
|
228
|
-
style: {
|
|
229
|
-
navigationBarTitleText: '关于',
|
|
230
|
-
},
|
|
231
|
-
})
|
|
232
|
-
</script>
|
|
233
|
-
|
|
234
|
-
<template>
|
|
235
|
-
<view>About</view>
|
|
236
|
-
</template>
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
## 虚拟根组件（App.ku.vue）
|
|
240
|
-
|
|
241
|
-
Univa 集成了 `@uni-ku/root` 插件，提供全局共享组件能力（如全局 Toast、ConfigProvider 等）。
|
|
242
|
-
|
|
243
|
-
若 `src/App.ku.vue` 不存在，Univa 会在首次启动时自动生成最小模板：
|
|
244
|
-
|
|
245
|
-
```vue
|
|
246
|
-
<!-- Auto-generated by @univa/core -->
|
|
247
|
-
<!-- UniKuRoot 虚拟根组件，可在此添加全局组件（如 Toast、ConfigProvider 等） -->
|
|
248
|
-
<template>
|
|
249
|
-
<KuRootView />
|
|
250
|
-
</template>
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
你可以在此基础上添加全局组件：
|
|
254
|
-
|
|
255
|
-
```vue
|
|
256
|
-
<!-- src/App.ku.vue -->
|
|
257
|
-
<script setup lang="ts">
|
|
258
|
-
import GlobalToast from '@/components/GlobalToast.vue'
|
|
259
|
-
</script>
|
|
260
|
-
|
|
261
|
-
<template>
|
|
262
|
-
<KuRootView />
|
|
263
|
-
<GlobalToast />
|
|
264
|
-
</template>
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
自定义根组件文件名（通过 `overrides.root.rootFileName`）：
|
|
268
|
-
|
|
269
|
-
```ts
|
|
270
|
-
// univa.config.ts
|
|
271
|
-
import { defineConfig } from '@univa/core'
|
|
272
|
-
|
|
273
|
-
export default defineConfig({
|
|
274
|
-
overrides: {
|
|
275
|
-
root: {
|
|
276
|
-
rootFileName: 'KuRoot.vue', // 默认 App.ku.vue
|
|
277
|
-
},
|
|
278
|
-
},
|
|
279
|
-
})
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
## overrides 逃生口
|
|
283
|
-
|
|
284
|
-
对于 90% 的场景，使用上层约定（`dirs`、`imports`、`pages`）即可。当需要覆盖底层插件选项时，使用 `overrides`：
|
|
285
|
-
|
|
286
|
-
```ts
|
|
287
|
-
// univa.config.ts
|
|
288
|
-
import { defineConfig } from '@univa/core'
|
|
289
|
-
|
|
290
|
-
export default defineConfig({
|
|
291
|
-
overrides: {
|
|
292
|
-
// 覆盖 @uni-helper/vite-plugin-uni-pages 选项
|
|
293
|
-
pages: {
|
|
294
|
-
exclude: ['**/components/**/*.*'],
|
|
295
|
-
},
|
|
296
|
-
// 覆盖 @uni-helper/vite-plugin-uni-components 选项
|
|
297
|
-
components: {
|
|
298
|
-
globalNamespaces: ['components', 'common'],
|
|
299
|
-
directoryAsNamespace: true,
|
|
300
|
-
},
|
|
301
|
-
// 覆盖 unplugin-auto-import 选项
|
|
302
|
-
autoImport: {
|
|
303
|
-
eslintrc: { enabled: true },
|
|
304
|
-
},
|
|
305
|
-
// 覆盖 @uni-ku/root 选项
|
|
306
|
-
root: {
|
|
307
|
-
enabledGlobalRef: true,
|
|
308
|
-
excludePages: ['components-async/**/*.*'],
|
|
309
|
-
},
|
|
310
|
-
// 覆盖 @uni-helper/vite-plugin-uni-layouts 选项
|
|
311
|
-
layouts: {
|
|
312
|
-
layoutDir: 'src/layouts',
|
|
313
|
-
},
|
|
314
|
-
// 覆盖 unocss/vite 选项
|
|
315
|
-
unocss: {
|
|
316
|
-
presets: [],
|
|
317
|
-
},
|
|
318
|
-
},
|
|
319
|
-
})
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
`overrides` 的优先级最高，会与上层约定合并后传给底层插件。
|
|
323
|
-
|
|
324
|
-
## 自动生成的文件
|
|
325
|
-
|
|
326
|
-
所有自动生成的文件统一输出到 `.univa/` 目录：
|
|
327
|
-
|
|
328
|
-
```
|
|
329
|
-
.univa/
|
|
330
|
-
├── pages-config.ts # 应用级 pages 配置（来源：univa.config.ts 的 pages 字段）
|
|
331
|
-
├── auto-imports.d.ts # API 自动导入类型声明
|
|
332
|
-
├── components.d.ts # 组件自动注册类型声明
|
|
333
|
-
└── uni-pages.d.ts # 页面路由类型声明
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
建议在 `.gitignore` 中忽略：
|
|
337
|
-
|
|
338
|
-
```gitignore
|
|
339
|
-
.univa/
|
|
340
|
-
```
|
|
341
|
-
|
|
342
|
-
`pages.json` 仍由 `@uni-helper/vite-plugin-uni-pages` 输出到默认位置（`src/pages.json`），保持 uni-app 标准结构。
|
|
343
|
-
|
|
344
|
-
## 配置文件支持
|
|
345
|
-
|
|
346
|
-
`univa.config.ts` 支持以下扩展名（自动识别）：
|
|
347
|
-
|
|
348
|
-
- `univa.config.ts`
|
|
349
|
-
- `univa.config.mts`
|
|
350
|
-
- `univa.config.js`
|
|
351
|
-
- `univa.config.mjs`
|
|
352
|
-
- `univa.config.cjs`
|
|
353
|
-
- `univa.config.json`
|
|
354
|
-
|
|
355
|
-
配置文件不存在时使用默认配置。
|
|
356
|
-
|
|
357
|
-
## 完整配置示例
|
|
358
|
-
|
|
359
|
-
```ts
|
|
360
|
-
// univa.config.ts
|
|
361
|
-
import { defineConfig } from '@univa/core'
|
|
362
|
-
|
|
363
|
-
export default defineConfig({
|
|
364
|
-
// 源码目录，相对 Vite root，默认 'src'
|
|
365
|
-
srcDir: 'src',
|
|
366
|
-
|
|
367
|
-
// 目录约定
|
|
368
|
-
dirs: {
|
|
369
|
-
pages: 'pages',
|
|
370
|
-
subPackages: ['pages-sub/*'],
|
|
371
|
-
layouts: 'layouts',
|
|
372
|
-
},
|
|
373
|
-
|
|
374
|
-
// 自动导入
|
|
375
|
-
imports: {
|
|
376
|
-
apis: [
|
|
377
|
-
'vue',
|
|
378
|
-
'uni-app',
|
|
379
|
-
'pinia',
|
|
380
|
-
'@vueuse/core',
|
|
381
|
-
'composables/**',
|
|
382
|
-
'stores/**',
|
|
383
|
-
'hooks/**',
|
|
384
|
-
'constants/**',
|
|
385
|
-
{ from: 'wot-design-uni', imports: ['useToast'] },
|
|
386
|
-
],
|
|
387
|
-
components: ['components/**', 'components-biz/**'],
|
|
388
|
-
},
|
|
389
|
-
|
|
390
|
-
// 应用级 pages.json 配置
|
|
391
|
-
pages: {
|
|
392
|
-
globalStyle: {
|
|
393
|
-
navigationBarTitleText: '我的应用',
|
|
394
|
-
navigationBarBackgroundColor: '#FFFFFF',
|
|
395
|
-
},
|
|
396
|
-
tabBar: {
|
|
397
|
-
list: [
|
|
398
|
-
{ pagePath: 'pages/index/index', text: '首页' },
|
|
399
|
-
],
|
|
400
|
-
},
|
|
401
|
-
},
|
|
402
|
-
|
|
403
|
-
// 底层插件逃生口（可选）
|
|
404
|
-
overrides: {
|
|
405
|
-
root: {
|
|
406
|
-
enabledGlobalRef: true,
|
|
407
|
-
},
|
|
408
|
-
},
|
|
409
|
-
})
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
## 集成的插件
|
|
413
|
-
|
|
414
|
-
| 插件 | 说明 | overrides 键 |
|
|
415
|
-
|------|------|-------------|
|
|
416
|
-
| `@dcloudio/vite-plugin-uni` | uni-app 核心 | — |
|
|
417
|
-
| `@uni-helper/vite-plugin-uni-pages` | 文件式路由 | `pages` |
|
|
418
|
-
| `@uni-helper/vite-plugin-uni-layouts` | 布局系统 | `layouts` |
|
|
419
|
-
| `@uni-helper/vite-plugin-uni-components` | 组件自动注册 | `components` |
|
|
420
|
-
| `@uni-ku/root` | 虚拟根组件 | `root` |
|
|
421
|
-
| `unplugin-auto-import` | API 自动导入 | `autoImport` |
|
|
422
|
-
| `unocss/vite` | 原子化 CSS | `unocss` |
|
|
423
|
-
|
|
424
|
-
## 设计哲学
|
|
425
|
-
|
|
426
|
-
Univa 采用**融合约定 + 逃生口**的分层设计：
|
|
427
|
-
|
|
428
|
-
- **高层字段**（`dirs`/`imports`/`pages`）：面向 90% 用户，降低心智成本，一个字段替代多个底层配置
|
|
429
|
-
- **逃生口**（`overrides`）：面向 10% 高级用户，可下沉到底层插件选项，优先级最高
|
|
430
|
-
|
|
431
|
-
这不是简单的插件包装，而是将底层插件的配置项重新组织为符合工程直觉的高层概念。
|
|
432
|
-
|
|
433
|
-
##
|
|
434
|
-
|
|
435
|
-
|
|
1
|
+
# @univa/core
|
|
2
|
+
|
|
3
|
+
> 🚀 开箱即用的 uni-app Vite 插件集，以「约定优于配置」理念整合 uni-app 生态最佳实践。
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@univa/core)
|
|
6
|
+
[](./LICENSE)
|
|
7
|
+
|
|
8
|
+
## 为什么选择 Univa？
|
|
9
|
+
|
|
10
|
+
在 uni-app + Vite 生态中，一个完整项目通常需要集成 5~7 个插件：`@dcloudio/vite-plugin-uni`、`unplugin-auto-import`、`@uni-helper/vite-plugin-uni-components`、`@uni-helper/vite-plugin-uni-pages`、`@uni-helper/vite-plugin-uni-layouts`、`@uni-ku/root`、`unocss/vite`……每个插件都有自己的配置项，分散在 `vite.config.ts` 中，维护成本高、心智负担重。
|
|
11
|
+
|
|
12
|
+
Univa 将这些插件整合为**单一入口** `Univa()`，通过一份 `univa.config.ts` 声明工程约定，其余全部自动装配。
|
|
13
|
+
|
|
14
|
+
### 核心特性
|
|
15
|
+
|
|
16
|
+
- **零参数入口**：`vite.config.ts` 只需 `plugins: [...Univa()]`，无需传任何配置
|
|
17
|
+
- **约定式目录**：`pages/`、`layouts/`、`components/` 等目录自动识别
|
|
18
|
+
- **统一自动导入**：`imports.apis` 一个字段同时管理预设导入与目录扫描
|
|
19
|
+
- **应用级配置**：`pages.json` 的 `globalStyle`/`tabBar` 等直接写在 `univa.config.ts`
|
|
20
|
+
- **逃生口设计**：`overrides` 字段可直接覆盖任意底层插件选项
|
|
21
|
+
- **自动产物集中**：所有生成文件统一输出到 `.univa/` 目录，便于 `.gitignore`
|
|
22
|
+
|
|
23
|
+
## 安装
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# pnpm
|
|
27
|
+
pnpm add -D @univa/core
|
|
28
|
+
|
|
29
|
+
# yarn
|
|
30
|
+
yarn add -D @univa/core
|
|
31
|
+
|
|
32
|
+
# npm
|
|
33
|
+
npm install -D @univa/core
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
> 前置依赖：项目需已安装 `vite` 与 `@dcloudio/uni-app` 相关依赖。
|
|
37
|
+
|
|
38
|
+
## 快速开始
|
|
39
|
+
|
|
40
|
+
### 1. 配置 `vite.config.ts`
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
// vite.config.ts
|
|
44
|
+
import { Univa } from '@univa/core'
|
|
45
|
+
import { defineConfig } from 'vite'
|
|
46
|
+
|
|
47
|
+
export default defineConfig({
|
|
48
|
+
plugins: [
|
|
49
|
+
// 零参数，所有约定走 univa.config.ts
|
|
50
|
+
...Univa(),
|
|
51
|
+
],
|
|
52
|
+
})
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### 2. 创建 `univa.config.ts`
|
|
56
|
+
|
|
57
|
+
在项目根目录创建 `univa.config.ts`（或 `univa.config.mts`）：
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
// univa.config.ts
|
|
61
|
+
import { defineConfig } from '@univa/core'
|
|
62
|
+
|
|
63
|
+
export default defineConfig({
|
|
64
|
+
// 应用级 pages.json 配置
|
|
65
|
+
pages: {
|
|
66
|
+
globalStyle: {
|
|
67
|
+
navigationBarTitleText: '我的应用',
|
|
68
|
+
},
|
|
69
|
+
},
|
|
70
|
+
})
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 3. 开始开发
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pnpm dev
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Univa 会自动：
|
|
80
|
+
- 扫描 `src/pages/` 生成 `pages.json`
|
|
81
|
+
- 扫描 `src/pages-sub/*/` 生成分包配置
|
|
82
|
+
- 自动导入 `vue`、`uni-app` 及 `src/composables/`、`src/hooks/`、`src/stores/` 等目录的导出
|
|
83
|
+
- 自动注册 `src/components/` 下的组件
|
|
84
|
+
- 生成虚拟根组件 `src/App.ku.vue`（若不存在）
|
|
85
|
+
- 输出类型声明到 `.univa/` 目录
|
|
86
|
+
|
|
87
|
+
## 目录约定
|
|
88
|
+
|
|
89
|
+
默认目录结构（均相对 `srcDir`，默认 `src`）：
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
src/
|
|
93
|
+
├── pages/ # 主包页面（自动扫描）
|
|
94
|
+
├── pages-sub/ # 分包根目录（默认扫描 pages-sub/* 下第一层）
|
|
95
|
+
│ └── demo/
|
|
96
|
+
├── layouts/ # 布局组件
|
|
97
|
+
├── components/ # 全局组件（自动注册）
|
|
98
|
+
├── components-biz/ # 业务组件（自动注册）
|
|
99
|
+
├── composables/ # 组合式 API（自动导入）
|
|
100
|
+
├── hooks/ # 自定义 Hooks（自动导入）
|
|
101
|
+
├── stores/ # 状态管理（自动导入）
|
|
102
|
+
├── constants/ # 常量（自动导入）
|
|
103
|
+
└── App.ku.vue # 虚拟根组件（自动生成）
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
自定义目录约定：
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
// univa.config.ts
|
|
110
|
+
import { defineConfig } from '@univa/core'
|
|
111
|
+
|
|
112
|
+
export default defineConfig({
|
|
113
|
+
dirs: {
|
|
114
|
+
pages: 'views', // 主包页面目录
|
|
115
|
+
subPackages: ['subpkgs/*'], // 分包目录
|
|
116
|
+
layouts: 'layouts', // 布局目录
|
|
117
|
+
},
|
|
118
|
+
})
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## 自动导入
|
|
122
|
+
|
|
123
|
+
### `imports.apis` 统一字段
|
|
124
|
+
|
|
125
|
+
`apis` 支持三种形式，Univa 内部自动区分：
|
|
126
|
+
|
|
127
|
+
| 形式 | 示例 | 说明 |
|
|
128
|
+
|------|------|------|
|
|
129
|
+
| 预设名 | `'vue'`、`'uni-app'`、`'pinia'` | 识别为 unplugin-auto-import 预设 |
|
|
130
|
+
| 目录 glob | `'composables/**'`、`'hooks/**'` | 识别为目录扫描（相对 srcDir） |
|
|
131
|
+
| inline preset | `{ from: 'wot-design-uni', imports: ['useToast'] }` | 直接传给 unplugin-auto-import |
|
|
132
|
+
|
|
133
|
+
**识别规则**：含 glob 字符（`*?[{}]`）或路径分隔符（`/`）的字符串 → 目录扫描；否则 → 预设名。scope 包名（如 `@vueuse/core`）也算预设名。
|
|
134
|
+
|
|
135
|
+
默认值：
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
apis: ['vue', 'uni-app', 'composables/**', 'stores/**', 'hooks/**', 'constants/**']
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
自定义示例：
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
// univa.config.ts
|
|
145
|
+
import { defineConfig } from '@univa/core'
|
|
146
|
+
|
|
147
|
+
export default defineConfig({
|
|
148
|
+
imports: {
|
|
149
|
+
apis: [
|
|
150
|
+
// 预设名
|
|
151
|
+
'vue',
|
|
152
|
+
'uni-app',
|
|
153
|
+
'pinia',
|
|
154
|
+
'@vueuse/core',
|
|
155
|
+
// 目录扫描（相对 srcDir）
|
|
156
|
+
'composables/**',
|
|
157
|
+
'stores/**',
|
|
158
|
+
// negation 排除
|
|
159
|
+
'!hooks/**/_internal/**',
|
|
160
|
+
// inline preset
|
|
161
|
+
{ from: 'wot-design-uni', imports: ['useToast', 'useMessage'] },
|
|
162
|
+
// 命名导入映射
|
|
163
|
+
{ '@fun-design/use': ['useState', 'useVModel'] },
|
|
164
|
+
],
|
|
165
|
+
// 组件自动注册目录（glob，相对 srcDir）
|
|
166
|
+
components: ['components/**', 'components-biz/**'],
|
|
167
|
+
},
|
|
168
|
+
})
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### 类型声明
|
|
172
|
+
|
|
173
|
+
类型声明文件自动生成到 `.univa/` 目录：
|
|
174
|
+
|
|
175
|
+
- `.univa/auto-imports.d.ts` — API 自动导入类型
|
|
176
|
+
- `.univa/components.d.ts` — 组件自动注册类型
|
|
177
|
+
- `.univa/uni-pages.d.ts` — 页面路由类型
|
|
178
|
+
|
|
179
|
+
在 `tsconfig.json` 中引入：
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{
|
|
183
|
+
"include": [".univa/**/*.d.ts"]
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## 应用级配置（pages）
|
|
188
|
+
|
|
189
|
+
`pages.json` 的应用级内容（`globalStyle`、`tabBar`、`easycom` 等）可直接写在 `univa.config.ts`：
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
// univa.config.ts
|
|
193
|
+
import { defineConfig } from '@univa/core'
|
|
194
|
+
|
|
195
|
+
export default defineConfig({
|
|
196
|
+
pages: {
|
|
197
|
+
globalStyle: {
|
|
198
|
+
navigationBarTextStyle: 'black',
|
|
199
|
+
navigationBarTitleText: '我的应用',
|
|
200
|
+
navigationBarBackgroundColor: '#FFFFFF',
|
|
201
|
+
backgroundColor: '#F8F8F8',
|
|
202
|
+
},
|
|
203
|
+
tabBar: {
|
|
204
|
+
color: '#7A7E83',
|
|
205
|
+
selectedColor: '#3CC51F',
|
|
206
|
+
backgroundColor: '#FFFFFF',
|
|
207
|
+
list: [
|
|
208
|
+
{ pagePath: 'pages/index/index', text: '首页' },
|
|
209
|
+
{ pagePath: 'pages/user/index', text: '我的' },
|
|
210
|
+
],
|
|
211
|
+
},
|
|
212
|
+
},
|
|
213
|
+
})
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Univa 会读取 `pages` 字段，自动生成 `.univa/pages-config.ts`，供 `@uni-helper/vite-plugin-uni-pages` 消费。
|
|
217
|
+
|
|
218
|
+
> **注意**：`pages`（页面列表）和 `subPackages`（分包列表）由目录扫描自动填充，请勿在配置中手写。
|
|
219
|
+
|
|
220
|
+
### 页面内配置（definePage）
|
|
221
|
+
|
|
222
|
+
在页面文件中使用 `definePage` 宏声明页面级配置：
|
|
223
|
+
|
|
224
|
+
```vue
|
|
225
|
+
<!-- src/pages/about.vue -->
|
|
226
|
+
<script setup lang="ts">
|
|
227
|
+
definePage({
|
|
228
|
+
style: {
|
|
229
|
+
navigationBarTitleText: '关于',
|
|
230
|
+
},
|
|
231
|
+
})
|
|
232
|
+
</script>
|
|
233
|
+
|
|
234
|
+
<template>
|
|
235
|
+
<view>About</view>
|
|
236
|
+
</template>
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## 虚拟根组件（App.ku.vue）
|
|
240
|
+
|
|
241
|
+
Univa 集成了 `@uni-ku/root` 插件，提供全局共享组件能力（如全局 Toast、ConfigProvider 等）。
|
|
242
|
+
|
|
243
|
+
若 `src/App.ku.vue` 不存在，Univa 会在首次启动时自动生成最小模板：
|
|
244
|
+
|
|
245
|
+
```vue
|
|
246
|
+
<!-- Auto-generated by @univa/core -->
|
|
247
|
+
<!-- UniKuRoot 虚拟根组件，可在此添加全局组件（如 Toast、ConfigProvider 等） -->
|
|
248
|
+
<template>
|
|
249
|
+
<KuRootView />
|
|
250
|
+
</template>
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
你可以在此基础上添加全局组件：
|
|
254
|
+
|
|
255
|
+
```vue
|
|
256
|
+
<!-- src/App.ku.vue -->
|
|
257
|
+
<script setup lang="ts">
|
|
258
|
+
import GlobalToast from '@/components/GlobalToast.vue'
|
|
259
|
+
</script>
|
|
260
|
+
|
|
261
|
+
<template>
|
|
262
|
+
<KuRootView />
|
|
263
|
+
<GlobalToast />
|
|
264
|
+
</template>
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
自定义根组件文件名（通过 `overrides.root.rootFileName`）：
|
|
268
|
+
|
|
269
|
+
```ts
|
|
270
|
+
// univa.config.ts
|
|
271
|
+
import { defineConfig } from '@univa/core'
|
|
272
|
+
|
|
273
|
+
export default defineConfig({
|
|
274
|
+
overrides: {
|
|
275
|
+
root: {
|
|
276
|
+
rootFileName: 'KuRoot.vue', // 默认 App.ku.vue
|
|
277
|
+
},
|
|
278
|
+
},
|
|
279
|
+
})
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
## overrides 逃生口
|
|
283
|
+
|
|
284
|
+
对于 90% 的场景，使用上层约定（`dirs`、`imports`、`pages`）即可。当需要覆盖底层插件选项时，使用 `overrides`：
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
// univa.config.ts
|
|
288
|
+
import { defineConfig } from '@univa/core'
|
|
289
|
+
|
|
290
|
+
export default defineConfig({
|
|
291
|
+
overrides: {
|
|
292
|
+
// 覆盖 @uni-helper/vite-plugin-uni-pages 选项
|
|
293
|
+
pages: {
|
|
294
|
+
exclude: ['**/components/**/*.*'],
|
|
295
|
+
},
|
|
296
|
+
// 覆盖 @uni-helper/vite-plugin-uni-components 选项
|
|
297
|
+
components: {
|
|
298
|
+
globalNamespaces: ['components', 'common'],
|
|
299
|
+
directoryAsNamespace: true,
|
|
300
|
+
},
|
|
301
|
+
// 覆盖 unplugin-auto-import 选项
|
|
302
|
+
autoImport: {
|
|
303
|
+
eslintrc: { enabled: true },
|
|
304
|
+
},
|
|
305
|
+
// 覆盖 @uni-ku/root 选项
|
|
306
|
+
root: {
|
|
307
|
+
enabledGlobalRef: true,
|
|
308
|
+
excludePages: ['components-async/**/*.*'],
|
|
309
|
+
},
|
|
310
|
+
// 覆盖 @uni-helper/vite-plugin-uni-layouts 选项
|
|
311
|
+
layouts: {
|
|
312
|
+
layoutDir: 'src/layouts',
|
|
313
|
+
},
|
|
314
|
+
// 覆盖 unocss/vite 选项
|
|
315
|
+
unocss: {
|
|
316
|
+
presets: [],
|
|
317
|
+
},
|
|
318
|
+
},
|
|
319
|
+
})
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
`overrides` 的优先级最高，会与上层约定合并后传给底层插件。
|
|
323
|
+
|
|
324
|
+
## 自动生成的文件
|
|
325
|
+
|
|
326
|
+
所有自动生成的文件统一输出到 `.univa/` 目录：
|
|
327
|
+
|
|
328
|
+
```
|
|
329
|
+
.univa/
|
|
330
|
+
├── pages-config.ts # 应用级 pages 配置（来源：univa.config.ts 的 pages 字段）
|
|
331
|
+
├── auto-imports.d.ts # API 自动导入类型声明
|
|
332
|
+
├── components.d.ts # 组件自动注册类型声明
|
|
333
|
+
└── uni-pages.d.ts # 页面路由类型声明
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
建议在 `.gitignore` 中忽略：
|
|
337
|
+
|
|
338
|
+
```gitignore
|
|
339
|
+
.univa/
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
`pages.json` 仍由 `@uni-helper/vite-plugin-uni-pages` 输出到默认位置（`src/pages.json`），保持 uni-app 标准结构。
|
|
343
|
+
|
|
344
|
+
## 配置文件支持
|
|
345
|
+
|
|
346
|
+
`univa.config.ts` 支持以下扩展名（自动识别）：
|
|
347
|
+
|
|
348
|
+
- `univa.config.ts`
|
|
349
|
+
- `univa.config.mts`
|
|
350
|
+
- `univa.config.js`
|
|
351
|
+
- `univa.config.mjs`
|
|
352
|
+
- `univa.config.cjs`
|
|
353
|
+
- `univa.config.json`
|
|
354
|
+
|
|
355
|
+
配置文件不存在时使用默认配置。
|
|
356
|
+
|
|
357
|
+
## 完整配置示例
|
|
358
|
+
|
|
359
|
+
```ts
|
|
360
|
+
// univa.config.ts
|
|
361
|
+
import { defineConfig } from '@univa/core'
|
|
362
|
+
|
|
363
|
+
export default defineConfig({
|
|
364
|
+
// 源码目录，相对 Vite root，默认 'src'
|
|
365
|
+
srcDir: 'src',
|
|
366
|
+
|
|
367
|
+
// 目录约定
|
|
368
|
+
dirs: {
|
|
369
|
+
pages: 'pages',
|
|
370
|
+
subPackages: ['pages-sub/*'],
|
|
371
|
+
layouts: 'layouts',
|
|
372
|
+
},
|
|
373
|
+
|
|
374
|
+
// 自动导入
|
|
375
|
+
imports: {
|
|
376
|
+
apis: [
|
|
377
|
+
'vue',
|
|
378
|
+
'uni-app',
|
|
379
|
+
'pinia',
|
|
380
|
+
'@vueuse/core',
|
|
381
|
+
'composables/**',
|
|
382
|
+
'stores/**',
|
|
383
|
+
'hooks/**',
|
|
384
|
+
'constants/**',
|
|
385
|
+
{ from: 'wot-design-uni', imports: ['useToast'] },
|
|
386
|
+
],
|
|
387
|
+
components: ['components/**', 'components-biz/**'],
|
|
388
|
+
},
|
|
389
|
+
|
|
390
|
+
// 应用级 pages.json 配置
|
|
391
|
+
pages: {
|
|
392
|
+
globalStyle: {
|
|
393
|
+
navigationBarTitleText: '我的应用',
|
|
394
|
+
navigationBarBackgroundColor: '#FFFFFF',
|
|
395
|
+
},
|
|
396
|
+
tabBar: {
|
|
397
|
+
list: [
|
|
398
|
+
{ pagePath: 'pages/index/index', text: '首页' },
|
|
399
|
+
],
|
|
400
|
+
},
|
|
401
|
+
},
|
|
402
|
+
|
|
403
|
+
// 底层插件逃生口（可选）
|
|
404
|
+
overrides: {
|
|
405
|
+
root: {
|
|
406
|
+
enabledGlobalRef: true,
|
|
407
|
+
},
|
|
408
|
+
},
|
|
409
|
+
})
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
## 集成的插件
|
|
413
|
+
|
|
414
|
+
| 插件 | 说明 | overrides 键 |
|
|
415
|
+
|------|------|-------------|
|
|
416
|
+
| `@dcloudio/vite-plugin-uni` | uni-app 核心 | — |
|
|
417
|
+
| `@uni-helper/vite-plugin-uni-pages` | 文件式路由 | `pages` |
|
|
418
|
+
| `@uni-helper/vite-plugin-uni-layouts` | 布局系统 | `layouts` |
|
|
419
|
+
| `@uni-helper/vite-plugin-uni-components` | 组件自动注册 | `components` |
|
|
420
|
+
| `@uni-ku/root` | 虚拟根组件 | `root` |
|
|
421
|
+
| `unplugin-auto-import` | API 自动导入 | `autoImport` |
|
|
422
|
+
| `unocss/vite` | 原子化 CSS | `unocss` |
|
|
423
|
+
|
|
424
|
+
## 设计哲学
|
|
425
|
+
|
|
426
|
+
Univa 采用**融合约定 + 逃生口**的分层设计：
|
|
427
|
+
|
|
428
|
+
- **高层字段**（`dirs`/`imports`/`pages`）：面向 90% 用户，降低心智成本，一个字段替代多个底层配置
|
|
429
|
+
- **逃生口**（`overrides`）：面向 10% 高级用户，可下沉到底层插件选项，优先级最高
|
|
430
|
+
|
|
431
|
+
这不是简单的插件包装，而是将底层插件的配置项重新组织为符合工程直觉的高层概念。
|
|
432
|
+
|
|
433
|
+
## 致谢
|
|
434
|
+
|
|
435
|
+
本项目基于众多优秀的开源项目构建，感谢所有开源贡献者！
|
|
436
|
+
|
|
437
|
+
详细的开源软件声明请查看 [THIRD-PARTY-NOTICES](./THIRD-PARTY-NOTICES)。
|
|
438
|
+
|
|
439
|
+
## License
|
|
440
|
+
|
|
441
|
+
[MIT](./LICENSE)
|