Package Exports

@univa/core
@univa/core/client
@univa/core/hooks

Readme

@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: libre1103@163.com