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

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

uni-ui 组件库必须通过 npm 安装，不能直接用 CDN 或 script 引入

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-app 编译至微信小程序后，uni-ui 组件样式出现丢失或错位

这是最容易被忽视的兼容性问题：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 弹窗内容不出现，点击也没有响应

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 时间选择器不能回显已选择的值

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()，各端表现差异大

一些细节隐藏在组件内部逻辑中，例如 uni-calendar 的 insertDate 参数仅在第一次加载时有效，之后再修改也不会触发重绘；面对这类行为，必须查看源码或运行 demo 验证，不能只依赖文档说明。