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></script> 加载。所有组件都依赖 npm 包管理器完成注册和按需引入。
常见错误现象：Unknown custom element: <uni-badge></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/uni-ui@1.x
uni-app 编译到微信小程序时，uni-ui 组件样式丢失或错位
这是最常被忽略的兼容性问题：uni-ui 默认使用 CSS 变量（--uni-color-primary 等）定义主题色，而微信小程序基础库低于 2.27.0 不支持原生 CSS 变量，导致样式 fallback 失效、颜色/间距异常。
- 检查微信开发者工具右上角「详情 → 项目设置」里的「基础库版本」，确保 ≥
2.27.0 - 若无法升级基础库（如需兼容老用户），需手动覆盖变量：在
App.vue的<style></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"></uni-popup>（Vue 3）或<uni-popup :show="popupVisible"> popupVisible = val"></uni-popup>（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 验证，不能光靠文档描述。
