Files
code-bang/.cursor/rules/frontend-miniapp.mdc
T
2026-10-14 14:44:01 +08:00

85 lines
3.8 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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()` 脱敏;用户输入在提交前做必要的非空/长度校验,但以后端校验为准