快速开始 ​

本节介绍如何在项目中使用 Uniboot UI。

用法 ​

完整引入 ​

若对包体积不太敏感，完整引入最为省事。

import { createApp } from 'vue'
import UnibootUI from 'uniboot-ui'
import 'uniboot-ui/dist/index.css'
import App from './App.vue'

const app = createApp(App)

app.use(UnibootUI)
app.mount('#app')

Volar 支持 ​

若使用 Volar，请在 tsconfig.json 的 compilerOptions.types 中加入全局组件类型定义。

{
  "compilerOptions": {
    // ...
    "types": ["uniboot-ui/global"]
  }
}

按需引入 ​

按需引入需要配合插件使用。

自动导入 ​

先安装运行时依赖 uniboot-ui，再安装构建插件 unplugin-vue-components、unplugin-auto-import（按需解析的 resolver 随 uniboot-ui 发布，路径为 uniboot-ui/resolver，与 Element Plus 从 unplugin-vue-components/resolvers 引入 ElementPlusResolver 的方式不同）。

$ npm install uniboot-ui vue
$ npm install -D unplugin-vue-components unplugin-auto-import

$ yarn add uniboot-ui vue
$ yarn add -D unplugin-vue-components unplugin-auto-import

$ pnpm add uniboot-ui vue
$ pnpm add -D unplugin-vue-components unplugin-auto-import

将下列配置加入 Vite 或 Webpack 配置文件。模板中的 U* 组件（如 UButton）、Pro 组合组件（如 ProLayout、DialogForm）与 v-loading 等指令会由 resolver 自动解析 import；默认 importStyle: 'css' 会按需注入组件样式，一般无需再在入口全量引入 uniboot-ui/dist/index.css。

import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { UnibootCombinedResolver, UnibootUIResolver } from 'uniboot-ui/resolver'

export default defineConfig({
  // ...
  plugins: [
    // ...
    AutoImport({
      resolvers: [UnibootUIResolver()],
    }),
    Components({
      resolvers: [
        UnibootCombinedResolver({
          // importStyle: 'sass', // 使用 Sass 变量定制主题时改为 'sass'
          // importStyle: false,   // 关闭按需样式时，请在 main.ts 引入 'uniboot-ui/dist/index.css'
        }),
      ],
    }),
  ],
})

const AutoImport = require('unplugin-auto-import/webpack')
const Components = require('unplugin-vue-components/webpack')
const {
  UnibootCombinedResolver,
  UnibootUIResolver,
} = require('uniboot-ui/resolver')

module.exports = {
  // ...
  plugins: [
    AutoImport({
      resolvers: [UnibootUIResolver()],
    }),
    Components({
      resolvers: [UnibootCombinedResolver()],
    }),
  ],
}

从 Element Plus 迁移时，将 ElementPlusResolver 换为 UnibootUIResolver；若项目还使用 ProLayout、ProTable、DialogForm 等 Pro 组合组件，推荐直接使用 UnibootCombinedResolver。resolver 的 import 路径为 uniboot-ui/resolver，其余选项（importStyle、directives、ssr 等）与官方 resolver 类似。更多说明见 迁移指南。

更多打包工具（Rollup、Vue CLI）与配置方式，请参考 unplugin-vue-components 与 unplugin-auto-import。

Nuxt ​

Nuxt 用户只需安装 @uniboot-ui/nuxt。

$ npm install -D @uniboot-ui/nuxt

$ yarn add -D @uniboot-ui/nuxt

$ pnpm install -D @uniboot-ui/nuxt

然后在配置中加入：

export default defineNuxtConfig({
  modules: ['@uniboot-ui/nuxt'],
})

具体配置见 文档。

手动引入 ​

Uniboot UI 基于 ES Module 提供开箱即用的 Tree Shaking。

样式按需需安装 unplugin-uniboot-ui，配置方式见 文档。

<template>
  <u-button>I am UButton</u-button>
</template>

<script setup lang="ts">
import { UButton } from 'uniboot-ui'
</script>

import { defineConfig } from 'vite'
import UnibootUI from 'unplugin-uniboot-ui/vite'

export default defineConfig({
  // ...
  plugins: [UnibootUI()],
})

脚手架模板 ​

推荐使用 create-uniboot 创建项目，内置三套模板：

simple  - 简单前端项目（Vite）
auth    - 含授统一认证授权服务中心（Auth Service）和管理后台服务（Admin Service）
website - Nuxt 4 官网模板（SSR + Uniboot UI + Vite 8）

通过 pnpm create 运行：

pnpm create uniboot my-app

也可以直接指定模板：

pnpm create uniboot my-app --template simple
pnpm create uniboot my-app --template auth
pnpm create uniboot my-app --template website

创建完成后进入项目并启动：

cd my-app
pnpm install
pnpm dev

simple 与 auth 基于 Vite，默认开发端口为 3002（可通过 VITE_PORT 配置）。website 基于 Nuxt 4，默认端口为 3000；首次启动前需复制 .env.example 为 .env 并执行 pnpm db:push、pnpm db:seed。更多说明见 create-uniboot 使用指南。

全局配置 ​

注册 Uniboot UI 时可传入全局配置对象，通过 size 设置表单类组件默认尺寸，通过 zIndex 设置弹出层默认层级；zIndex 默认值为 2000。

完整引入：

import { createApp } from 'vue'
import UnibootUI from 'uniboot-ui'
import App from './App.vue'

const app = createApp(App)
app.use(UnibootUI, { size: 'small', zIndex: 3000 })

按需引入：

<template>
  <u-config-provider :size="size" :z-index="zIndex">
    <app />
  </u-config-provider>
</template>

<script setup lang="ts">
import { UConfigProvider } from 'uniboot-ui'

const zIndex = 3000
const size = 'small'
</script>

使用 Nuxt.js ​

也可使用 Nuxt.js，详见 Uniboot UI Nuxt 启动模板。

开始使用 ​

现在可以开始搭建项目。各组件用法请查阅对应组件文档。