uni-app中如何使用uView UI组件库 uni-app安装配置uView教程-uni-app-PHP中文网

uView在uni-app中需完成四步配置：①main.js/ts正确注册（Vue2用Vue.use，Vue3用createSSRApp().use且须最先调用）；②pages.json启用easycom并配对路径；③App.vue和uni.scss按序引入SCSS样式文件并加lang="scss"；④Vue3项目还需在vite.config.js中配置optimizeDeps.include和scss.additionalData。

uni-app中如何使用uview ui组件库 uni-app安装配置uview教程

uView 在 uni-app 中不能“装完就用”，必须完成四步基础配置，缺一不可；否则运行时报 Unknown custom element 或样式错乱，尤其是 Vue3 项目容易卡在 app.use() 调用方式和 vite.config.js 预构建上。

main.js 或 main.ts 中正确注册 uView 实例

Vue2 项目直接在 main.js 中 import 并 Vue.use()；Vue3（尤其 Vite + Composition API）必须用 createSSRApp().use() 方式，且 uview-plus 的 app.use() 必须放在所有其他插件（如 i18n、pinia）之前。

Vue2 写法（main.js）：

import uView from '@/uni_modules/uview-ui'
Vue.use(uView)

Vue3 + Vite 写法（main.ts）：

import { createSSRApp } from 'vue'
import uViewPlus from 'uview-plus'
export function createApp() {
  const app = createSSRApp(App)
  app.use(uViewPlus) // 注意：必须最先调用
  return { app }
}

常见错误：在 Vue3 项目中仍写 Vue.use() → 报 Cannot read property 'use' of undefined
注意顺序：若同时用了 vue-i18n@v9，app.use(uViewPlus) 必须在 app.use(i18n) 之前，否则 i18n 的 legacy: false 会干扰 uView 的内部逻辑

pages.json 中必须启用 easycom 组件自动导入

uView 的组件（如）不手动 import 就能用，全靠 easycom 规则匹配。漏配或路径写错，页面里写对了标签也渲染不出，控制台无报错但空白。

正确配置位置：项目根目录 pages.json 的顶层对象内（不是 subNVues 或 tabBar 下）

Vue2 / uView 2.x 对应规则：

"easycom": {
  "^u-(.*)": "@/uni_modules/uview-ui/components/u-$1/u-$1.vue"
}

Vue3 / uView Plus 对应规则：

"easycom": {
  "^u-(.*)": "uview-plus/components/u-$1/u-$1.vue"
}

关键点：路径中的斜杠方向必须是正斜杠 /，Windows 下复制反斜杠 \ 会导致匹配失败
验证方法：删掉该配置，重启 HBuilderX 或运行 npm run dev:mp-weixin，立刻变白屏

样式文件三处导入缺一不可且位置敏感

uView 的样式分三层：基础结构（index.scss）、主题变量（theme.scss）、全局覆盖（uni.scss 引入的预设）。任意一处漏、顺序错、lang 属性没加，都会导致按钮无边框、图标不显示、颜色全灰。

uni-app

uni-app 是基于 Vue 的跨端开发框架，适合开发 H5、App、小程序、鸿蒙和多端业务应用。

下载

App.vue 中第一行内引入：

@import "@/uni_modules/uview-ui/index.scss";

（Vue2）或

@import "uview-plus/index.scss";

（Vue3）

uni.scss 中引入主题变量：

@import "@/uni_modules/uview-ui/theme.scss";

（Vue2）或

@import "uview-plus/theme.scss";

（Vue3）

必须加 lang="scss"：没加则 SCSS 语法（如 @import、变量）被忽略，退化为纯 CSS 解析 → 全部样式失效
顺序不能颠倒：App.vue 的 index.scss 必须在最前，它依赖 theme.scss 定义的变量；uni.scss 的 theme.scss 必须在其他自定义样式之前，否则你的重写会被 uView 覆盖

Vue3 项目额外要处理 vite.config.js

Vue3 + Vite 环境下，uView Plus 的组件含大量 defineComponent 和 setup()，不显式预构建会触发热更新异常、HMR 失效、甚至开发服务器卡死。

必须在 vite.config.js 的 optimizeDeps.include 中加入：
```
include: ['uview-plus']
```
SCSS 变量需全局注入：在 css.preprocessorOptions.scss.additionalData 中补全：
```
additionalData: '@import "uview-plus/theme.scss";'
```
漏掉 optimizeDeps.include 的典型现象：首次启动正常，修改 App.vue 后保存，控制台反复打印 [vite] hot updated: /src/App.vue 却无实际刷新，必须手动刷新浏览器
注意：HBuilderX 自带的编译器不读 vite.config.js，所以 Vue3 项目务必用 CLI 启动（npm run dev:mp-weixin），否则配置无效