85 lines
3.8 KiB
Plaintext
85 lines
3.8 KiB
Plaintext
---
|
||
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()` 脱敏;用户输入在提交前做必要的非空/长度校验,但以后端校验为准
|