Files
code-bang/.cursor/rules/frontend-miniapp.mdc
T

85 lines
3.8 KiB
Plaintext
Raw Normal View History

2026-10-14 14:44:01 +08:00
---
description: 微信小程序前端规范:页面结构、接口服务层、TDesign 组件、样式与交互
globs: frontend/miniapp/**/*.{js,wxml,wxss,json,wxs}
alwaysApply: false
---
# 微信小程序前端规范
## 代码风格
- 遵循 `.prettierrc.yml` 与 `.eslintrc.js`:2 空格、单引号、分号、行宽 120、尾逗号、LF
- 用 `const/let`,禁止 `var`;用模板字符串,比较用 `===`;ES Module `import/export`
- 不提交调试日志:`console.log` 需删除,保留 `console.error/warn` 用于异常
- 提交信息遵循 commitlint(`feat: 新增需求交付页`、`fix: ...`)
## 目录与命名
- 页面:`pages/{模块}/{页面}/index.{js,json,wxml,wxss}`,目录名 kebab-case,新页面必须在 `app.json` 的 `pages` 中注册
- 页面私有组件放 `pages/{模块}/components/`,跨页面复用放 `components/`
- 接口函数放 `services/{模块}/fetchXxx.js`,一个模块一个文件
## 接口调用
1. 在 `config/api.js` 登记地址:`DemandDeliver: ApiRootUrl + 'demand/deliver', //需求发货`
2. 在 services 中封装,通过全局 `wx.$util.request(url, data, method)`:
```js
/** 需求发货 */
export function deliverDemand(params) {
return wx.$util.request(wx.$api.DemandDeliver, params, 'POST');
}
```
3. 页面只 import services 函数,**禁止**在页面里直接 `wx.request` 或拼接接口地址
4. 结果按 `res.code === 1` 判断成功,失败展示 `res.msg`:
```js
async onSubmit() {
wx.showLoading({ title: '提交中', mask: true });
try {
const res = await deliverDemand({ demand_id: this.data.id });
if (res.code !== 1) {
wx.showToast({ title: res.msg || '操作失败', icon: 'none' });
return;
}
wx.showToast({ title: '发货成功', icon: 'success' });
} catch (err) {
console.error('deliverDemand failed:', err);
wx.showToast({ title: '网络异常,请重试', icon: 'none' });
} finally {
wx.hideLoading();
}
}
```
- 新代码使用 `async/await`,不再写 `.then(success, fail)` 嵌套
- 提交类按钮加防重复点击(`submitting` 标志或 `t-button` 的 `loading`)
## 页面逻辑
- `data` 中每个字段写注释说明含义;列表页固定使用 `page`、`hasMore`、`isEmpty` 三个字段
- 分页:`onReachBottom` 判断 `hasMore` 加载下一页;`onPullDownRefresh` 刷新后调用 `wx.stopPullDownRefresh()`
- `setData` 只传变化的字段,单条更新用数据路径写法(如键名 `demandList[0].button`),不整体替换大列表
- 跨页面刷新使用已有机制:`wx.$util.markDemandRefresh(id)`(`globalData.refreshDemandId`)或 `backAndRefresh()`,不新增其他全局通信方式
- 按钮动作按后端返回的 `item.button.key` 分支,常量与后端 `DemandService::BUTTON_*` 保持一致
- 删除模板生成的空生命周期函数(空的 `onReady/onHide/onUnload/onShareAppMessage`)
## WXML / 组件
- UI 优先使用 TDesign 组件,在页面 `index.json` 的 `usingComponents` 中按需引入(`tdesign-miniprogram/xxx/xxx`);图片优先 `/components/webp-image/index`
- `wx:for` 必须写 `wx:key`(优先唯一 `id`);嵌套循环使用不同的 `wx:for-item/wx:for-index` 名
- 事件参数通过 `data-*` 传递,在 js 中用 `e.currentTarget.dataset` 解构读取
- 不在 WXML 中写复杂表达式,复杂格式化放 `.wxs` 或在 js 中预处理
## WXSS
- 尺寸使用 `rpx`;类名小写中划线,可用 BEM(`search-bar__input`、`refresh-btn--loading`)
- 主题色沿用 TabBar 选中色 `#FF5F15` 与 TDesign CSS 变量(`--td-brand-color` 等),不随意新增色值
- 避免行内 `style`,仅动态值(如 `max-height`)可用
## 安全与隐私
- 不在前端保存任何密钥;`token`、`userInfo` 仅存于 Storage
- 手机号展示使用 `phoneEncryption()` 脱敏;用户输入在提交前做必要的非空/长度校验,但以后端校验为准