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