@univa/core

🚀 开箱即用的 uni-app Vite 插件集，提供完整的开发体验

特性

• 📦 开箱即用 - 零配置即可开始开发
• 🎯 自动导入 - 自动导入 Vue、uni-app API
• 🧩 组件自动注册 - 自动注册组件，无需手动 import
• 📄 页面管理 - 增强的页面配置和管理
• 🎨 布局系统 - 灵活的布局系统
• 🎭 UnoCSS - 即时按需原子化 CSS 引擎
• 📱 自定义 TabBar - 支持自定义 tabBar 配置
• 🌳 根组件 - 自动创建和管理根组件

安装

# npm
npm install @univa/core

# pnpm
pnpm add @univa/core

# yarn
yarn add @univa/core

快速开始

1. 配置 Vite

在 vite.config.ts 中使用：

import { Univa } from '@univa/core'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Univa(),
  ],
})

2. 配置 TypeScript

在 tsconfig.json 中添加类型支持：

{
  "compilerOptions": {
    "types": [
      "@univa/core/client"
    ]
  }
}

功能详解

自动导入

自动导入 Vue、Pinia、uni-app 等 API，无需手动 import：

// 无需 import，直接使用
const count = ref(0)
const router = useRouter()
const store = useStore()

自动扫描目录：

• src/hooks/** - 自动导入 hooks
• src/store/** - 自动导入 store
• src/constants/** - 自动导入常量

组件自动注册

自动注册 components 目录下的组件，无需手动 import：

src/
├── components/
│   ├── MyButton.vue
│   └── common/
│       └── Icon.vue
└── components-biz/
    └── Card.vue

在页面中直接使用：

<template>
  <MyButton />
  <Icon />
  <BizCard />
</template>

特性：

• components/ 和 common/ 是全局命名空间，不添加前缀
• components-biz/ 会自动添加 Biz 命名空间前缀
• 自动生成类型声明文件

页面管理

定义页面配置

方式 1：在 pages.config.ts 中定义

// pages.config.ts
import { definePagesConfig } from '@univa/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',
      },
    ],
  },
})

方式 2：在 vite.config.ts 中直接定义

// vite.config.ts
import { Univa } from '@univa/core'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Univa({
      pages: {
        config: {
          tabBarMode: 'CUSTOM',
          tabBar: {
            list: [
              {
                pagePath: 'pages/index',
                text: '首页',
              },
            ],
          },
        },
      },
    }),
  ],
})

获取 Pages 配置

在组件中获取 Pages 配置：

import { pages, subPackages, tabBar } from 'virtual:univa-pages'

if (tabBar) {
  console.log(tabBar.list) // TabBar 列表
}

类型支持：确保在 tsconfig.json 中添加了 @univa/core/client 类型，以获得 virtual:univa-pages 的类型提示。

UnoCSS 预设

内置 UnoCSS 预设，提供开箱即用的原子化 CSS：

内置预设：

• presetUni() - uni-app 专属预设
• presetIcons() - 图标预设（scale: 1.2）
• presetLegacyCompat() - 兼容性预设（处理低端安卓机）

内置快捷方式：

| 快捷方式 | 展开后 | |---------|--------| | 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 |

安全区域规则：

<div class="p-safe">安全区域内边距</div>
<div class="pt-safe">顶部安全区域</div>
<div class="pb-safe">底部安全区域</div>

根组件

自动创建和管理 App.univa.vue 根组件：

<script setup lang="ts">
</script>

<template>
  <UnivaPageMeta background-color="#ff0000" page-style="color: green" />
  <view class="container">
    <UnivaRootView />
  </view>
</template>

特性：

• 自动创建根组件文件
• 支持虚拟节点（virtualHost）
• 支持全局 ref
• 支持 <UnivaPageMeta> 组件配置页面元信息
• 支持 <UnivaRootView /> 组件作为根视图

Manifest 配置

在 vite.config.ts 中直接配置 manifest：

import { Univa } from '@univa/core'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Univa({
      manifest: {
        name: 'my-app',
        appid: '__UNI__XXXXXX',
        description: 'My Application',
        versionName: '1.0.0',
        versionCode: '100',
      },
    }),
  ],
})

配置选项

import type { UnivaUserConfig } from '@univa/core'

const config: UnivaUserConfig = {
  // 自动导入配置（默认 true）
  autoImport: true,

  // 组件自动注册配置（默认 true）
  components: true,

  // 页面配置
  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,
      },
    },
    // 排除的页面
    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',
  },
}

依赖

本包集成了以下优秀的插件：

• @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

致谢

• 感谢 uni-helper 社区提供的优秀插件
• 感谢 uni-ku 提供的优秀插件

License

MIT

Contact

📧 Email: [email protected]