uniapp-skill

# uni-app Skill ## 意图 帮助 Agent 处理 uni-app / uni-app x 项目的开发、审查、调试、配置、测试与发布。主文件保持轻量；详细示例和长表格放在 `references/` 中，按任务读取。 官方文档：<https://uniapp.dcloud.net.cn/> ## 触发场景 用户提到以下内容时使用： - `uni-app`、`uniapp`、`uni-app x`、`uvue`、`nvue`、`UTS`、HBuilderX、DCloud。 - H5、微信/支付宝/抖音/QQ 等小程序、App、HarmonyOS、鸿蒙元服务。 - `pages.json`、`manifest.json`、条件编译、`uni.request`、`uni.navigateTo`、easycom、uni-ui。 - Pinia、生命周期、路由、网络请求、组件、媒体文件、设备 API、web-view、RenderJS、WXS、subNVue。 - uni-automator、Vitest、CI/CD、安全、性能优化、发布打包。 - nvue 横竖屏切换、横屏布局、横屏样式错位、rpx 横屏放大、overlay 浮层定位异常。 - 需要通过 UTS / ArkTS / ETS 封装鸿蒙能力时，同时使用 `harmony-uts-plugin`。 - 需要通过 UTS 封装 iOS、Android、HarmonyOS 三端共用 SQLite 插件时，同时使用 `sqlite-uniapp-uts`。 ## 工作流 1. **识别目标平台与项目形态** - 传统 uni-app 还是 uni-app x。 - 目标是 H5、小程序、App、`APP-HARMONY`、`MP-HARMONY` 还是多端。 - 优先检查 `pages.json`、`manifest.json`、项目结构和已有平台条件编译。 2. **先选官方跨端能力** - 能用 `uni.*`、内置组件、uni-ui、DCloud 插件解决时，不要直接引入 Web/Node/浏览器专用方案。 - 网络请求优先 `uni.request`，路由优先 `uni.navigateTo` / `switchTab` 等 uni API。 3. **按场景读取 references** - 只读取当前任务需要的文件，避免一次加载全部长资料。 - 如果不确定，从 `references/full-guide.md` 或下方索引开始。 4. **实现或审查时坚持平台差异显式化** - 用 `#ifdef` / `#ifndef` 隔离平台差异。 - 注意 `APP` 包含鸿蒙，`APP-PLUS` 不包含鸿蒙；鸿蒙 App 用 `APP-HARMONY`。 5. **验证** - 代码任务优先跑目标平台可用的 lint/test/build。 - 涉及 App/鸿蒙/硬件能力时，模拟器结果不能替代真机验证。 ## 关键规则 - 不要在 uni-app 项目里默认使用 axios；跨端请求用 `uni.request`。 - tabBar 页面跳转用 `uni.switchTab()`，不要用 `navigateTo()`。 - 组件里用 Vue 生命周期；页面里用 `onLoad` / `onShow` 等页面生命周期。 - 条件编译支持 `||`，不要假设支持复杂 JS 表达式。 - 小程序主包体积受限，静态资源应分包、压缩或上 CDN。 - uni-app x / uvue 强类型和 CSS 能力更接近原生约束；布局优先 flex。 - 鸿蒙原生能力优先查 `uni.*` 是否已覆盖；确需原生封装时使用 `harmony-uts-plugin`。 - 三端 SQLite UTS 插件不要只按普通 UTS 插件处理；使用 `sqlite-uniapp-uts` 管统一 API、能力矩阵和真机验证。 - 不要输出或写入密钥、证书密码、token、真实用户隐私数据。 ## 常用 references | 场景 | 读取 | |---|---| | 完整详细指南 / 原长版内容 | `references/full-guide.md` | | 项目搭建与目录 | `references/project-setup.md` | | 页面与路由配置 | `references/pages-config.md` | | `manifest.json` | `references/manifest.md` | | 生命周期 | `references/lifecycle.md` | | 网络、路由、存储、UI API | `references/api.md` | | 进阶网络（WebSocket / UDP / mDNS） | `references/network-advanced.md` | | 组件与 uni-ui | `references/components.md`、`references/more-components.md` | | 条件编译与平台标识 | `references/conditional-compilation.md` | | Vue3 写法与迁移 | `references/vue3-patterns.md` | | 样式、性能、RenderJS、WebView、SSR | `references/advanced-features.md` | | App 原生能力 / 权限判断 | `references/app-native.md`、`references/native-resources.md`、`references/app-permissions.md` | | uniCloud、UniPush、统计、一键登录、广告变现 | `references/cloud-services.md`、`references/advertising.md` | | uni-app x / UTS | `references/uniapp-x-uts.md` | | nvue 横竖屏兼容 | `references/nvue-landscape-layout.md` | | 鸿蒙基础/开发/发布/迁移 | `references/harmony-basics.md`、`references/harmony-development.md`、`references/harmony-advanced.md`、`references/harmony-migration.md` | | 媒体、文件、设备系统 API | `references/media-file-api.md`、`references/system-device-api.md`、`references/canvas-api.md`、`references/hardware-open-api.md` | | web-view / Native.js / WXS / subNVue | `references/webview.md`、`references/native-js.md`、`references/wxs.md`、`references/subnvue.md` | | 富文本、共享元素、Datacom | `references/editor.md`、`references/share-element.md`、`references/datacom.md` | | 测试、安全、CI/CD | `references/testing.md`、`references/security.md`、`references/cicd.md` | | DCloud 开发者中心（账号/应用/云打包/发票） | `references/dev-center.md` | | 调试发布与避坑 | `references/debug-publish.md`、`references/pitfalls.md`、`references/community-practices.md` | ## 开发检查清单 - [ ] 已确认目标平台和项目类型。 - [ ] 已优先使用 uni 官方跨端 API / 组件。 - [ ] 平台差异已用条件编译隔离。 - [ ] 页面、组件、store、utils 的职责清晰。 - [ ] 请求、登录态、权限、隐私数据处理符合目标平台限制。 - [ ] 涉及 App 权限时，已区分“权限授权状态”和“系统服务开关状态”，并规划拒绝后的设置页引导。 - [ ] 对涉及硬件、App、鸿蒙的能力已规划真机验证。 - [ ] 文档表述与真实功能一致，没有承诺未验证能力。 - [ ] nvue 横屏页面：横竖屏样式已分开，横屏只用 `px`，关键 overlay 有独立直接类选择器。 - [ ] nvue 横屏页面：父页全局样式不污染子组件，子组件接收 `isLandscape` 控制尺寸。