uni-app如何使用uni-ui组件库 uni-app官方UI库安装教程【配置】

作者：袖梨 2026-07-29

uni-ui 必须通过 npm 安装并按需引入，不支持 CDN 或 script 引入；微信小程序需基础库 ≥2.27.0 才支持 CSS 变量；uni-popup 需 v-model 双向绑定且禁用 v-if；uni-datetime-picker 的 value 必须为毫秒时间戳。

uni-app 的 uni-ui 是一个基于 Vue 3（兼容 Vue 2）的跨端 UI 库，它不是内置模块，也不支持在 index.html 里通过 <script> 加载。所有组件都依赖 npm 包管理器完成注册和按需引入。

常见的报错表现：Unknown custom element: <uni-badge>、Component is not defined —— 原因基本都是没有安装，或 import 配置不正确。

必须执行 npm install @dcloudio/uni-ui（推荐使用 npm，pnpm/yarn 在某些 HBuilderX 版本下有路径解析问题）
不推荐全局注册：文档虽然提供了 Vue.use(uniUI)，但实际使用时会让全部组件无条件打包进首屏，导致 JS 体积明显增加
更建议按需引入：在页面或组件内使用 import { uniBadge } from '@dcloudio/uni-ui'，随后在 components 选项中完成注册
需要匹配 Vue 版本：Vue 3 项目使用 @dcloudio/uni-ui@next（当前默认），Vue 2 项目则需要锁定 @dcloudio/[email protected]

这是最容易被忽视的兼容性问题：uni-ui 默认通过 CSS 变量（--uni-color-primary 等）设置主题色，但微信小程序基础库版本低于 2.27.0 时无法支持原生 CSS 变量，因而会使样式 fallback 失效，并引发颜色或间距异常。

打开微信开发者工具右上角的「详情 → 项目设置」，检查「基础库版本」并确保 ≥ 2.27.0
如果因兼容老用户而不能升级基础库，就要手动覆盖变量：在 App.vue 的 <style> 中加入全局 CSS 变量声明，例如：
```
:root {  --uni-color-primary: #007aff;  --uni-spacing-row: 20rpx;}
```
不要在 uni.scss 中覆盖，因为它只影响编译期 Sass，不会改变运行时 CSS 变量
H5 端不会遇到该问题；App 端则取决于基座版本，建议使用 3.9.0+ 基座

uni-popup 是最容易出错的组件之一，主要原因是它依赖 v-model 控制显示与隐藏，但许多人把它当作普通组件直接固定写入 show 属性，或遗漏需要绑定的值。

必须用双向绑定：<uni-popup v-model:show="popupVisible">（Vue 3）或 <uni-popup :show="popupVisible" @change="val => popupVisible = val">（Vue 2）
不能通过 v-if 控制它的挂载，因为 uni-popup 内部需要在 mounted 后执行 DOM 操作，而v-if 会打乱生命周期
弹窗内如果包含表单或 input，一定要添加 animation="true" 属性，否则在 iOS 微信中唤起软键盘时，弹窗位置会发生错乱
避免在 onLoad 钩子中立即打开：部分平台（尤其是 App）需等页面渲染完成，建议延后一帧：setTimeout(() => this.popupVisible = true, 30)

uni-datetime-picker 的 value 属性要求接收时间戳，也就是毫秒数，而非字符串或 Date 对象；这正是大多数人出错的根源。

错误方式：value="2024-05-20" 或 :value="new Date()" → 会直接失效，界面显示空白或默认使用当前时间
正确方式：:value="new Date('2024-05-20').getTime()" 或 :value="1716163200000"
后端若返回字符串时间，必须先将其转换成时间戳：String(new Date(timeStr).getTime())（需要注意：不能使用 parseInt，因为 Safari 解析 ISO 字符串的行为并不一致）
日期格式化建议统一用 uni.$u.timeFormat() 或 dayjs，别依赖浏览器 Date.prototype.toLocaleString()，各端表现差异大