# Miniprogram

> Miniprogram

- Skill: `dkbnull/miniprogram` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/miniprogram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/miniprogram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/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
- 体验版测试完整业务流程
- 性能面板监控内存和帧率

## 最佳实践

- 使用 `Promise` 封装异步 API
- 使用 `async/await` 简化异步代码
- 使用 `behaviors` 实现组件逻辑复用
- 使用 `observers` 监听属性变化
- 使用 `relations` 处理组件间关系
- 使用云开发简化后端逻辑