@univa/core 0.0.5 → 0.0.7

package/README.md

@@ -1,320 +1,435 @@
 # @univa/core
 
-> 🚀 开箱即用的 uni-app Vite 插件集，提供完整的开发体验
+> 🚀 开箱即用的 uni-app Vite 插件集，以「约定优于配置」理念整合 uni-app 生态最佳实践。
 
-## 特性
+[![NPM version](https://img.shields.io/npm/v/@univa/core?color=92DCD2&labelColor=18181B&label=npm)](https://www.npmjs.com/package/@univa/core)
+[![License](https://img.shields.io/github/license/libre1103/univa?color=92DCD2&labelColor=18181B&label=license)](./LICENSE)
 
-- 📦 **开箱即用** - 零配置即可开始开发
-- 🎯 **自动导入** - 自动导入 Vue、uni-app API
-- 🧩 **组件自动注册** - 自动注册组件，无需手动 import
-- 📄 **页面管理** - 增强的页面配置和管理
-- 🎨 **布局系统** - 灵活的布局系统
-- 🎭 **UnoCSS** - 即时按需原子化 CSS 引擎
-- 📱 **自定义 TabBar** - 支持自定义 tabBar 配置
-- 🌳 **根组件** - 自动创建和管理根组件
+## 为什么选择 Univa？
+
+在 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` 中，维护成本高、心智负担重。
+
+Univa 将这些插件整合为**单一入口** `Univa()`，通过一份 `univa.config.ts` 声明工程约定，其余全部自动装配。
+
+### 核心特性
+
+- **零参数入口**：`vite.config.ts` 只需 `plugins: [...Univa()]`，无需传任何配置
+- **约定式目录**：`pages/`、`layouts/`、`components/` 等目录自动识别
+- **统一自动导入**：`imports.apis` 一个字段同时管理预设导入与目录扫描
+- **应用级配置**：`pages.json` 的 `globalStyle`/`tabBar` 等直接写在 `univa.config.ts`
+- **逃生口设计**：`overrides` 字段可直接覆盖任意底层插件选项
+- **自动产物集中**：所有生成文件统一输出到 `.univa/` 目录，便于 `.gitignore`
 
 ## 安装
 
 ```bash
-# npm
-npm install @univa/core
-
 # pnpm
-pnpm add @univa/core
+pnpm add -D @univa/core
 
 # yarn
-yarn add @univa/core
+yarn add -D @univa/core
+
+# npm
+npm install -D @univa/core
 ```
 
-## 快速开始
+> 前置依赖：项目需已安装 `vite` 与 `@dcloudio/uni-app` 相关依赖。
 
-### 1. 配置 Vite
+## 快速开始
 
-在 `vite.config.ts` 中使用：
+### 1. 配置 `vite.config.ts`
 
-```typescript
+```ts
+// vite.config.ts
 import { Univa } from '@univa/core'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
   plugins: [
-    Univa(),
+    // 零参数，所有约定走 univa.config.ts
+    ...Univa(),
   ],
 })
 ```
 
-### 2. 配置 TypeScript
+### 2. 创建 `univa.config.ts`
 
-在 `tsconfig.json` 中添加类型支持：
+在项目根目录创建 `univa.config.ts`（或 `univa.config.mts`）：
 
-```json
-{
-  "compilerOptions": {
-    "types": [
-      "@univa/core/client"
-    ]
-  }
-}
-```
+```ts
+// univa.config.ts
+import { defineConfig } from '@univa/core'
 
-<br />
-
-## 功能详解
-
-### 自动导入
+export default defineConfig({
+  // 应用级 pages.json 配置
+  pages: {
+    globalStyle: {
+      navigationBarTitleText: '我的应用',
+    },
+  },
+})
+```
 
-自动导入 Vue、Pinia、uni-app 等 API，无需手动 import：
+### 3. 开始开发
 
-```typescript
-// 无需 import，直接使用
-const count = ref(0)
-const router = useRouter()
-const store = useStore()
+```bash
+pnpm dev
 ```
 
-**自动扫描目录**：
-- `src/hooks/**` - 自动导入 hooks
-- `src/store/**` - 自动导入 store
-- `src/constants/**` - 自动导入常量
+Univa 会自动：
+- 扫描 `src/pages/` 生成 `pages.json`
+- 扫描 `src/pages-sub/*/` 生成分包配置
+- 自动导入 `vue`、`uni-app` 及 `src/composables/`、`src/hooks/`、`src/stores/` 等目录的导出
+- 自动注册 `src/components/` 下的组件
+- 生成虚拟根组件 `src/App.ku.vue`（若不存在）
+- 输出类型声明到 `.univa/` 目录
 
-### 组件自动注册
+## 目录约定
 
-自动注册 `components` 目录下的组件，无需手动 import：
+默认目录结构（均相对 `srcDir`，默认 `src`）：
 
 ```
 src/
-├── components/
-│   ├── MyButton.vue
-│   └── common/
-│       └── Icon.vue
-└── components-biz/
-    └── Card.vue
+├── pages/              # 主包页面（自动扫描）
+├── pages-sub/          # 分包根目录（默认扫描 pages-sub/* 下第一层）
+│   └── demo/
+├── layouts/            # 布局组件
+├── components/         # 全局组件（自动注册）
+├── components-biz/      # 业务组件（自动注册）
+├── composables/        # 组合式 API（自动导入）
+├── hooks/              # 自定义 Hooks（自动导入）
+├── stores/             # 状态管理（自动导入）
+├── constants/          # 常量（自动导入）
+└── App.ku.vue          # 虚拟根组件（自动生成）
 ```
 
-在页面中直接使用：
+自定义目录约定：
 
-```vue
-<template>
-  <MyButton />
-  <Icon />
-  <BizCard />
-</template>
+```ts
+// univa.config.ts
+import { defineConfig } from '@univa/core'
+
+export default defineConfig({
+  dirs: {
+    pages: 'views',                    // 主包页面目录
+    subPackages: ['subpkgs/*'],        // 分包目录
+    layouts: 'layouts',                // 布局目录
+  },
+})
 ```
 
-**特性**：
-- `components/` 和 `common/` 是全局命名空间，不添加前缀
-- `components-biz/` 会自动添加 `Biz` 命名空间前缀
-- 自动生成类型声明文件
+## 自动导入
 
-### 页面管理
+### `imports.apis` 统一字段
 
-#### 定义页面配置
+`apis` 支持三种形式，Univa 内部自动区分：
 
-**方式 1：在 pages.config.ts 中定义**
+| 形式 | 示例 | 说明 |
+|------|------|------|
+| 预设名 | `'vue'`、`'uni-app'`、`'pinia'` | 识别为 unplugin-auto-import 预设 |
+| 目录 glob | `'composables/**'`、`'hooks/**'` | 识别为目录扫描（相对 srcDir） |
+| inline preset | `{ from: 'wot-design-uni', imports: ['useToast'] }` | 直接传给 unplugin-auto-import |
 
-```typescript
-// pages.config.ts
-import { definePagesConfig } from '@univa/core'
+**识别规则**：含 glob 字符（`*?[{}]`）或路径分隔符（`/`）的字符串 → 目录扫描；否则 → 预设名。scope 包名（如 `@vueuse/core`）也算预设名。
 
-export default definePagesConfig({
-  tabBarMode: 'CUSTOM', // 'NONE' | 'NATIVE' | 'CUSTOM'
-  tabBar: {
-    list: [
-      {
-        pagePath: 'pages/index',
-        text: '首页',
-        iconPath: 'images/tabbar/home.png',
-        selectedIconPath: 'images/tabbar/home_selected.png',
-      },
-    ],
-  },
-})
+默认值：
+
+```ts
+apis: ['vue', 'uni-app', 'composables/**', 'stores/**', 'hooks/**', 'constants/**']
 ```
 
-**方式 2：在 vite.config.ts 中直接定义**
+自定义示例：
 
-```typescript
-// vite.config.ts
-import { Univa } from '@univa/core'
-import { defineConfig } from 'vite'
+```ts
+// univa.config.ts
+import { defineConfig } from '@univa/core'
 
 export default defineConfig({
-  plugins: [
-    Univa({
-      pages: {
-        config: {
-          tabBarMode: 'CUSTOM',
-          tabBar: {
-            list: [...],
-          },
-        },
-      },
-    }),
-  ],
+  imports: {
+    apis: [
+      // 预设名
+      'vue',
+      'uni-app',
+      'pinia',
+      '@vueuse/core',
+      // 目录扫描（相对 srcDir）
+      'composables/**',
+      'stores/**',
+      // negation 排除
+      '!hooks/**/_internal/**',
+      // inline preset
+      { from: 'wot-design-uni', imports: ['useToast', 'useMessage'] },
+      // 命名导入映射
+      { '@fun-design/use': ['useState', 'useVModel'] },
+    ],
+    // 组件自动注册目录（glob，相对 srcDir）
+    components: ['components/**', 'components-biz/**'],
+  },
 })
 ```
 
-#### 获取 TabBar 配置
+### 类型声明
+
+类型声明文件自动生成到 `.univa/` 目录：
 
-在组件中获取 tabBar 配置：
+- `.univa/auto-imports.d.ts` — API 自动导入类型
+- `.univa/components.d.ts` — 组件自动注册类型
+- `.univa/uni-pages.d.ts` — 页面路由类型
 
-```typescript
-import tabBar from 'virtual:univa-tabbar'
+在 `tsconfig.json` 中引入：
 
-if (tabBar) {
-  console.log(tabBar.list) // TabBar 列表
+```json
+{
+  "include": [".univa/**/*.d.ts"]
 }
 ```
 
-### UnoCSS 预设
+## 应用级配置（pages）
 
-内置 UnoCSS 预设，提供开箱即用的原子化 CSS：
+`pages.json` 的应用级内容（`globalStyle`、`tabBar`、`easycom` 等）可直接写在 `univa.config.ts`：
 
-**内置预设**：
-- `presetUni()` - uni-app 专属预设
-- `presetIcons()` - 图标预设（scale: 1.2）
-- `presetLegacyCompat()` - 兼容性预设（处理低端安卓机）
+```ts
+// univa.config.ts
+import { defineConfig } from '@univa/core'
 
-**内置快捷方式**：
-```typescript
-'border-s' // border border-solid
-'wh-full' // w-full h-full
-'f-c-c' // flex justify-center items-center
-'f-col-c' // flex-col justify-center items-center
-'flex-items' // flex items-center
-'flex-justify' // flex justify-center
-'flex-col' // flex flex-col
+export default defineConfig({
+  pages: {
+    globalStyle: {
+      navigationBarTextStyle: 'black',
+      navigationBarTitleText: '我的应用',
+      navigationBarBackgroundColor: '#FFFFFF',
+      backgroundColor: '#F8F8F8',
+    },
+    tabBar: {
+      color: '#7A7E83',
+      selectedColor: '#3CC51F',
+      backgroundColor: '#FFFFFF',
+      list: [
+        { pagePath: 'pages/index/index', text: '首页' },
+        { pagePath: 'pages/user/index', text: '我的' },
+      ],
+    },
+  },
+})
 ```
 
-**安全区域规则**：
-```html
-<div class="p-safe">安全区域内边距</div>
-<div class="pt-safe">顶部安全区域</div>
-<div class="pb-safe">底部安全区域</div>
+Univa 会读取 `pages` 字段，自动生成 `.univa/pages-config.ts`，供 `@uni-helper/vite-plugin-uni-pages` 消费。
+
+> **注意**：`pages`（页面列表）和 `subPackages`（分包列表）由目录扫描自动填充，请勿在配置中手写。
+
+### 页面内配置（definePage）
+
+在页面文件中使用 `definePage` 宏声明页面级配置：
+
+```vue
+<!-- src/pages/about.vue -->
+<script setup lang="ts">
+definePage({
+  style: {
+    navigationBarTitleText: '关于',
+  },
+})
+</script>
+
+<template>
+  <view>About</view>
+</template>
 ```
 
-### 根组件
+## 虚拟根组件（App.ku.vue）
 
-自动创建和管理 `App.univa.vue` 根组件：
+Univa 集成了 `@uni-ku/root` 插件，提供全局共享组件能力（如全局 Toast、ConfigProvider 等）。
+
+若 `src/App.ku.vue` 不存在，Univa 会在首次启动时自动生成最小模板：
 
 ```vue
+<!-- Auto-generated by @univa/core -->
+<!-- UniKuRoot 虚拟根组件，可在此添加全局组件（如 Toast、ConfigProvider 等） -->
+<template>
+  <KuRootView />
+</template>
+```
+
+你可以在此基础上添加全局组件：
+
+```vue
+<!-- src/App.ku.vue -->
 <script setup lang="ts">
+import GlobalToast from '@/components/GlobalToast.vue'
 </script>
 
 <template>
-  <UnivaPageMeta background-color="#ff0000" page-style="color: green" />
-  <view class="container">
-    <UnivaRootView />
-  </view>
+  <KuRootView />
+  <GlobalToast />
 </template>
 ```
 
-**特性**：
-- 自动创建根组件文件
-- 支持虚拟节点（`virtualHost`）
-- 支持全局 ref
-- 支持 `<UnivaPageMeta>` 组件配置页面元信息
-- 支持 `<UnivaRootView />` 组件作为根视图
+自定义根组件文件名（通过 `overrides.root.rootFileName`）：
 
-### Manifest 配置
+```ts
+// univa.config.ts
+import { defineConfig } from '@univa/core'
 
-在 `vite.config.ts` 中直接配置 manifest：
+export default defineConfig({
+  overrides: {
+    root: {
+      rootFileName: 'KuRoot.vue', // 默认 App.ku.vue
+    },
+  },
+})
+```
 
-```typescript
-import { Univa } from '@univa/core'
-import { defineConfig } from 'vite'
+## overrides 逃生口
+
+对于 90% 的场景，使用上层约定（`dirs`、`imports`、`pages`）即可。当需要覆盖底层插件选项时，使用 `overrides`：
+
+```ts
+// univa.config.ts
+import { defineConfig } from '@univa/core'
 
 export default defineConfig({
-  plugins: [
-    Univa({
-      manifest: {
-        name: 'my-app',
-        appid: '__UNI__XXXXXX',
-        description: 'My Application',
-        versionName: '1.0.0',
-        versionCode: '100',
-      },
-    }),
-  ],
+  overrides: {
+    // 覆盖 @uni-helper/vite-plugin-uni-pages 选项
+    pages: {
+      exclude: ['**/components/**/*.*'],
+    },
+    // 覆盖 @uni-helper/vite-plugin-uni-components 选项
+    components: {
+      globalNamespaces: ['components', 'common'],
+      directoryAsNamespace: true,
+    },
+    // 覆盖 unplugin-auto-import 选项
+    autoImport: {
+      eslintrc: { enabled: true },
+    },
+    // 覆盖 @uni-ku/root 选项
+    root: {
+      enabledGlobalRef: true,
+      excludePages: ['components-async/**/*.*'],
+    },
+    // 覆盖 @uni-helper/vite-plugin-uni-layouts 选项
+    layouts: {
+      layoutDir: 'src/layouts',
+    },
+    // 覆盖 unocss/vite 选项
+    unocss: {
+      presets: [],
+    },
+  },
 })
 ```
 
-## 配置选项
+`overrides` 的优先级最高，会与上层约定合并后传给底层插件。
+
+## 自动生成的文件
+
+所有自动生成的文件统一输出到 `.univa/` 目录：
+
+```
+.univa/
+├── pages-config.ts       # 应用级 pages 配置（来源：univa.config.ts 的 pages 字段）
+├── auto-imports.d.ts     # API 自动导入类型声明
+├── components.d.ts        # 组件自动注册类型声明
+└── uni-pages.d.ts        # 页面路由类型声明
+```
+
+建议在 `.gitignore` 中忽略：
+
+```gitignore
+.univa/
+```
+
+`pages.json` 仍由 `@uni-helper/vite-plugin-uni-pages` 输出到默认位置（`src/pages.json`），保持 uni-app 标准结构。
+
+## 配置文件支持
+
+`univa.config.ts` 支持以下扩展名（自动识别）：
+
+- `univa.config.ts`
+- `univa.config.mts`
+- `univa.config.js`
+- `univa.config.mjs`
+- `univa.config.cjs`
+- `univa.config.json`
 
-```typescript
-import type { UnivaUserConfig } from '@univa/core'
+配置文件不存在时使用默认配置。
 
-const config: UnivaUserConfig = {
-  // 自动导入配置（默认 true）
-  autoImport: true,
+## 完整配置示例
 
-  // 组件自动注册配置（默认 true）
-  components: true,
+```ts
+// univa.config.ts
+import { defineConfig } from '@univa/core'
 
-  // 页面配置
+export default defineConfig({
+  // 源码目录，相对 Vite root，默认 'src'
+  srcDir: 'src',
+
+  // 目录约定
+  dirs: {
+    pages: 'pages',
+    subPackages: ['pages-sub/*'],
+    layouts: 'layouts',
+  },
+
+  // 自动导入
+  imports: {
+    apis: [
+      'vue',
+      'uni-app',
+      'pinia',
+      '@vueuse/core',
+      'composables/**',
+      'stores/**',
+      'hooks/**',
+      'constants/**',
+      { from: 'wot-design-uni', imports: ['useToast'] },
+    ],
+    components: ['components/**', 'components-biz/**'],
+  },
+
+  // 应用级 pages.json 配置
   pages: {
-    config: {
-      // TabBar 模式：'NONE' | 'NATIVE' | 'CUSTOM'
-      tabBarMode: 'NATIVE',
-      tabBar: {
-        color: '#A6A6A6',
-        selectedColor: '#003594',
-        list: [
-          {
-            pagePath: 'pages/index',
-            text: '首页',
-            iconPath: 'images/tabbar/home.png',
-            selectedIconPath: 'images/tabbar/home_selected.png',
-          },
-        ],
-      },
-      // 全局样式配置
-      globalStyle: {
-        navigationBarBackgroundColor: '#000000',
-        navigationBarTextStyle: 'black',
-        navigationBarTitleText: 'My App',
-        navigationStyle: 'custom',
-        enablePullDownRefresh: false,
-        onReachBottomDistance: 50,
-        animationType: 'pop-in',
-        animationDuration: 300,
-      },
+    globalStyle: {
+      navigationBarTitleText: '我的应用',
+      navigationBarBackgroundColor: '#FFFFFF',
+    },
+    tabBar: {
+      list: [
+        { pagePath: 'pages/index/index', text: '首页' },
+      ],
     },
-    // 排除的页面
-    exclude: ['pages/exclude/**'],
-    // 分包配置
-    subPackages: ['pages-sub'],
   },
 
-  // 根组件配置（默认 true）
-  appRoot: true,
-
-  // Manifest 配置
-  manifest: {
-    name: 'my-app',
-    appid: '__UNI__XXXXXX',
-    description: 'My Application',
-    versionName: '1.0.0',
-    versionCode: '100',
+  // 底层插件逃生口（可选）
+  overrides: {
+    root: {
+      enabledGlobalRef: true,
+    },
   },
-}
+})
 ```
 
-## 依赖
+## 集成的插件
+
+| 插件 | 说明 | overrides 键 |
+|------|------|-------------|
+| `@dcloudio/vite-plugin-uni` | uni-app 核心 | — |
+| `@uni-helper/vite-plugin-uni-pages` | 文件式路由 | `pages` |
+| `@uni-helper/vite-plugin-uni-layouts` | 布局系统 | `layouts` |
+| `@uni-helper/vite-plugin-uni-components` | 组件自动注册 | `components` |
+| `@uni-ku/root` | 虚拟根组件 | `root` |
+| `unplugin-auto-import` | API 自动导入 | `autoImport` |
+| `unocss/vite` | 原子化 CSS | `unocss` |
+
+## 设计哲学
+
+Univa 采用**融合约定 + 逃生口**的分层设计：
 
-本包集成了以下优秀的插件：
+- **高层字段**（`dirs`/`imports`/`pages`）：面向 90% 用户，降低心智成本，一个字段替代多个底层配置
+- **逃生口**（`overrides`）：面向 10% 高级用户，可下沉到底层插件选项，优先级最高
 
-- `@uni-helper/plugin-uni` - uni-app Vite 插件
-- `@uni-helper/vite-plugin-uni-components` - 组件自动注册
-- `@uni-helper/vite-plugin-uni-pages` - 页面管理
-- `@uni-helper/vite-plugin-uni-layouts` - 布局系统
-- `unplugin-auto-import` - 自动导入
-- `unocss` - 原子化 CSS 引擎
-- `@univa/root` - 根组件管理
-- `@univa/manifest` - manifest 配置
-- `@uni-ku/bundle-optimizer` - 打包优化
-- `vite-plugin-uni-polyfill` - Polyfill
+这不是简单的插件包装，而是将底层插件的配置项重新组织为符合工程直觉的高层概念。
 
 ## License
 
-MIT
+[MIT](./LICENSE)