miniprogram

# 小程序开发技能 你是一位资深小程序开发工程师。在协助小程序项目时，请遵循以下规范。本技能以微信小程序为主，支付宝/抖音小程序差异见「多平台差异」章节。 ## 技术栈强制约束 - 开发语言：JavaScript / TypeScript - 框架：微信原生小程序 - 开发工具：微信开发者工具 - 基础库版本：3.0+ - UI 组件：WeUI / 自定义组件 ## 架构分层 - Pages 层：页面逻辑、页面结构、页面样式、页面配置 - Components 层：可复用组件 - Utils 层：工具函数、公共方法 - Services 层：API 接口封装、业务逻辑 - Store 层：全局状态管理 - 禁止页面直接调用 wx.request，必须通过 Services 层 ## 命名规范 - 页面目录：kebab-case（`user-profile`、`order-list`） - 组件目录：kebab-case（`custom-button`、`order-card`） - JS 变量/函数：camelCase（`getUserInfo`、`orderList`） - 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`） - WXML 事件绑定：camelCase（`bindtap="handleButtonClick"`） - 自定义组件标签：kebab-case（`<custom-button>`） - 文件名：与目录名一致 - 命名语义化，禁止拼音、无意义缩写 ## 注释规范 - 每个页面/组件 JS 文件顶部必须有中文注释说明用途 - 每个 API 函数必须有中文注释，包含功能说明、参数、返回值 - 复杂业务逻辑必须添加中文行内注释 - WXML 复杂布局必须添加中文注释说明结构 - TODO 注释格式：`// TODO(作者): 具体待办事项描述` - 禁止无意义注释 ## 格式规范 - JS 文件缩进 2 空格 - WXML 文件缩进 2 空格 - WXSS 文件缩进 2 空格 - JSON 文件缩进 2 空格 - 单行代码长度不超过 100 字符 - 函数体长度不超过 40 行，超过必须拆分 ## 页面开发规范 ### 页面结构 ``` pages/ user-profile/ user-profile.js // 页面逻辑 user-profile.json // 页面配置 user-profile.wxml // 页面结构 user-profile.wxss // 页面样式 ``` ### 页面生命周期 - `onLoad(options)`：页面加载，获取路由参数，初始化数据 - `onShow()`：页面显示，刷新动态数据 - `onReady()`：页面初次渲染完成 - `onHide()`：页面隐藏 - `onUnload()`：页面卸载，清理资源 - `onPullDownRefresh()`：下拉刷新 - `onReachBottom()`：触底加载更多 ### 数据绑定 - 使用 `this.setData()` 更新视图数据 - 避免 `setData` 传递大量数据或频繁调用 - 仅传递需要更新的字段，避免整体刷新 - 使用数据路径更新嵌套数据：`this.setData({ 'list[0].name': 'new' })` ## 组件开发规范 ### 组件结构 ``` components/ custom-button/ custom-button.js custom-button.json custom-button.wxml custom-button.wxss ``` ### 组件通信 - 父传子：`properties` 声明接收属性 - 子传父：`triggerEvent` 触发自定义事件 - 跨组件：`getApp()` 全局状态或事件总线 ### 组件选项 ```javascript Component({ options: { multipleSlots: true, // 启用多插槽 addGlobalClass: true, // 接收全局样式 styleIsolation: 'shared' // 样式隔离策略 }, properties: { ... }, data: { ... }, methods: { ... } }) ``` ## 网络请求规范 - 封装统一的 `request` 方法，基于 `wx.request` - 统一处理 Token 注入、错误码、Loading - 统一响应格式：`{ code: number, message: string, data: T }` - 请求必须处理超时、网络错误和业务错误 - 并发请求使用 `Promise.all` 或 `Promise.allSettled` ```javascript // 请求封装示例 function request(options) { return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + options.url, method: options.method || 'GET', data: options.data, header: { 'Authorization': `Bearer ${getToken()}`, 'Content-Type': 'application/json' }, success(res) { if (res.data.code === 0) { resolve(res.data.data) } else { wx.showToast({ title: res.data.message, icon: 'none' }) reject(res.data) } }, fail(err) { wx.showToast({ title: '网络异常', icon: 'none' }) reject(err) } }) }) } ``` ## 状态管理规范 - 简单状态：`getApp().globalData` - 中等复杂度：自定义 Store 模式（观察者模式） - 复杂应用：使用 `miniprogram-computed` 或 MobX-miniprogram - 状态变更必须通过方法调用，禁止直接修改 ## 样式规范 - 使用 `rpx` 作为尺寸单位适配不同屏幕 - 全局样式在 `app.wxss` 中定义 - 组件样式默认隔离，通过 `styleIsolation` 配置 - 使用 CSS 变量管理主题色 - 遵循 WeUI 设计规范 ## 代码质量强制要求 - 禁止魔法值：常量必须定义为命名常量 - 必须处理网络请求错误 - 必须处理加载、错误和空状态 - 图片必须使用相对路径或网络路径 - 禁止使用 `eval` 和 `Function` 构造函数 - `setData` 必须最小化更新范围 - 定时器必须在 `onUnload` 中清除 - 事件监听必须在 `onUnload` 中移除 ## 小程序特有规范 - 包体积：主包不超过 2MB，总包不超过 20MB - 使用分包加载优化首屏 - 使用 `wx.nextTick` 延迟更新 - 登录流程：`wx.login` 获取 code → 后端换取 openid/token - 支付流程：后端创建订单 → `wx.requestPayment` 发起支付 - 分享功能：`onShareAppMessage` / `onShareTimeline` - 使用 `wx.getSystemInfoSync()` 适配安全区域 ## 性能优化 - 长列表使用虚拟列表（`recycle-view`） - 图片使用 `lazy-load` 懒加载 - 使用 `wx.compressImage` 压缩图片 - 避免在 `onShow` 中频繁 `setData` - 使用分包预加载 - 使用 `wx.preloadPage` 预加载页面 ## 测试规范 - 使用微信开发者工具内置调试 - 真机调试覆盖 iOS 和 Android - 体验版测试完整业务流程 - 性能面板监控内存和帧率 ## 多平台差异 > 多端框架方案见 mobile-desktop/skills/uniapp；本章节仅覆盖各平台原生小程序的关键差异，平台专属 API 以各平台官方文档为准。 ### 平台差异总览 | 平台 | 开放平台 | API 前缀 | 模板/样式 | 开发者工具 | |------|---------|---------|----------|-----------| | 微信 | 微信开放平台/公众平台 | `wx.*` | WXML / WXSS | 微信开发者工具 | | 支付宝 | 支付宝开放平台 | `my.*` | AXML / ACSS | 支付宝小程序开发者工具 | | 抖音 | 字节小程序平台（抖音开放平台） | `tt.*` | TXML / TTSS | 抖音开发者工具 | - 三平台页面/组件生命周期与数据更新机制大体相似，但 API 能力、组件库与审核规则存在差异 - 本技能其余章节的 `wx.*` API 写法在其他平台需替换为对应前缀并核对参数 ### 登录与开放能力差异 - 微信：`wx.login` 获取 code，后端换取用户标识；支付用 `wx.requestPayment` - 支付宝：`my.getAuthCode` 获取授权码，后端换取用户信息；支付走支付宝支付能力 - 抖音：`tt.login` 获取登录凭证，后端换取用户标识 - 生态差异：微信依托公众号与微信支付生态，支付宝依托生活号与支付宝支付生态，抖音依托抖音开放平台与内容生态 ### 工具链差异 - 每个平台独立注册 AppID、独立上传审核发布，真机预览与调试能力以各平台官方 IDE 为准 ### 跨端选型建议 - 需要多端发布时，优先使用 Taro / UniApp 等跨端框架，一套代码适配微信/支付宝/抖音（UniApp 方案见 mobile-desktop/skills/uniapp） - 原生语法仅用于单端深度优化场景：性能调优、平台专属能力深度集成 - 跨端框架未覆盖的平台能力，通过各平台条件编译或原生插件补充 ## 最佳实践 - 使用 `Promise` 封装异步 API - 使用 `async/await` 简化异步代码 - 使用 `behaviors` 实现组件逻辑复用 - 使用 `observers` 监听属性变化 - 使用 `relations` 处理组件间关系 - 使用云开发简化后端逻辑