# 前端代码标准 - **功能**:约束前端交互、按钮、颜色与主题、卡片列表、移动端、界面质量与可访问性、代码整洁、请求层与类型、组合式函数的写法,保证全站一致、可维护。 - **何时用**:新增或修改前端组件、样式、请求封装、composable 时;评审前端改动时。 ## 规则 ### 交互防抖与加载原则 - 点击后需要跳转到其他页面时,应立刻执行跳转,不要在跳转前等待接口返回;目标页面在数据未加载完成时必须展示页面级 loading。 - 点击后不跳转页面时,触发接口的按钮必须自身展示 loading 或在请求期间禁用,防止网络慢时被多次触发。 - 登录、创建/更新、结束会话等必须确认后端成功的操作属于例外:按钮先进入 loading,成功后再跳转。 - 同一异步动作执行期间必须通过 loading 或 disabled 阻止重复触发,不能只依赖路由跳转后的页面卸载。 ### 按钮规范 - 主操作 / 卡片 CTA:`size="large"`(实测 40px 高、15px 字),如 Study 开始任务、Welcome 快速入口。 - 区块工具栏 / 页内操作:默认尺寸(32px 高、14px 字),如 Review 刷新、ReviewRecall 面板操作。 - 表格/列表行内操作:`size="small"`(28px 高、13px 字;不得再调小)。 - 弹窗 footer:默认尺寸;确认按钮 `type="success"`,取消按钮默认;危险操作统一 `type="danger"`。 - 正向/保存语义统一 `success`,次级编辑语义可用 `primary`,不要在同一功能上混用。 - 窄屏(`max-width: 768px`)操作区按钮纵向全宽,全局规则位于 `src/assets/main.css` 的 `.action-row / .edit-actions / .fragment-edit-actions / .task-actions`。 ### 颜色与主题 - 禁止在组件内写颜色字面量:新增颜色先加到 `src/assets/base.css` 的 `:root`,组件只用 `var(--x)`。语义色已提供 `--accent-warning / --accent-warning-soft / --accent-warning-strong / --accent-success-soft / --accent-success-softer / --accent-success-strong / --accent-success-text`。 - Element Plus 主题色在 `src/assets/main.css` 的 `:root` 覆盖(`--el-color-success` / `--el-color-primary` 指向 `--green-700`),全站按钮/标签/开关自动生效,不要在组件里逐个覆盖 EP 组件色。 - `src/main.ts` 中自定义样式必须写在 `import 'element-plus/dist/index.css'` **之后**,否则主题覆盖会被 EP 覆盖。 - 实底主色统一用满足 WCAG AA(白字对比度 ≥4.5:1)的 `--green-700`;`--green-600` 仅用于文字/链接。 - 颜色字面量不得出现在 JS/模板表达式里(如 `:color="'#xxx'"` 引 CSS 变量会失效),需要动态色时保留字面量或改用 CSS 类。 ### 界面质量与可访问性 交付前逐项过 `roles/ui-review-checklist.md`;本节只列代码层面的写法要求。 - 可聚焦元素必须有 `:focus-visible` 焦点环;不得写 `outline: none` 而不给替代。粘性头部/遮罩不得盖住获得焦点的控件。 - 过渡显式列出属性(`transition: opacity .2s ease, transform .2s ease`),**禁止 `transition: all`**;只动 `transform` / `opacity`。 - 需要动效时给 `@media (prefers-reduced-motion: reduce)` 降级;全站统一的淡入上移不作为入场方案。 - 统计、覆盖率、计时、金额等需要上下比较的数字加 `font-variant-numeric: tabular-nums`。 - 加载/处理中的文案以 `…`(省略号字符)结尾,不用 `...`。 - 长内容容器加 `min-width: 0` 并允许换行或省略,验证 URL、ID 与用户输入的极端情况。 - 空态与错误态分开:空态给下一步动作,错误态给原因 + 重试;不要用同一个 `el-empty` 兜住失败。 - 加载指示延迟约 150–300ms 再显示,并保证最短可见约 300–500ms,避免快响应时闪一下。**统一用 `useDelayedVisible`**,不要自己写定时器。 - 骨架形状要与最终内容一致(清单在 `roles/ui-review-checklist.md`);骨架用 `main.css` 的 `.skeleton-line`,不要在组件里另造一套灰。 - 纯图标按钮必须有 `aria-label`;装饰图标 `aria-hidden="true"`。 > 页面的信息架构与视觉层级取舍见 `roles/design-principles.md`,设计变量的当前取值见 `roles/design-system.md`;出现新页面或大范围 UI 改动时走 `skills/ui-review/`。 ### 卡片列表交互 - 卡片列表的卡片整体可点击进入详情:外层加 `role="link" tabindex="0"` 与 `aria-label`,并绑定 `@click` 及 `@keydown.enter/@keydown.space.prevent`。 - 卡片内的附加按钮必须 `@click.stop`,避免被卡片点击吞掉(如 Review 的「回忆复习」)。 - 卡片操作使用右对齐操作簇(`justify-content: flex-end`),**禁止用 `space-between` 把两个按钮拉到卡片两端**。 - 加载失败必须区分于空数据:保留一个 `loadFailed` 状态,失败时给出可读提示 + 重试按钮,重试前先重置该状态;不要只靠 `finally` 关 loading 导致空白页。 ### 移动端适配 - 断点约定:按钮/弹窗使用 768px,卡片与汇总布局使用 900px。 - 弹窗:窄屏宽度 `calc(100% - 24px)`,body 允许纵向滚动,footer 按钮等宽;全局规则位于 `main.css` 的 `@media (max-width: 768px)`,新增弹窗不需要再逐页适配。 - 多按钮弹窗(如 Welcome 回忆卡片)在窄屏纵向堆叠。 - 列表页优先使用卡片列表而非 `el-table`,桌面与移动端视觉统一,参考 `Review.vue` 的 `.task-list`。 - 文案不缩写:使用完整字段名,如 `学习报告数量`、`学习残片数量`,不使用 `报告数`、`残片数`。 ### 代码整洁 - Markdown 渲染统一使用 `src/utils/markdown.ts` 的 `renderMarkdown`,禁止在组件内复制实现。 - 应用场景状态常量统一使用 `src/utils/taskApplication.ts` 的 `applicationStatusOptions`。 - 用户可见错误提示必须口语化、可理解,不要直接展示接口原始 message、JSON、参数名或“服务器返回”等技术信息;技术细节留在日志。 - 不保留无消费者代码:未使用的 import、prop、事件、API 封装、CSS class、组件文件与依赖应及时删除。 - 组件公开 props/events 只在有实际消费者时保留,例如 MindMapViewer 通过 `toOutline()` 导出编辑内容,不依赖无人监听的 change 事件。 - Vite 模板遗留文件(示例组件、icon、logo)不进入业务代码。 ### 请求层与类型规范 - 所有接口封装必须放在 `src/api/`,组件内禁止直接拼 URL 调用 `request`(历史遗留的裸调用在改动到时迁移)。 - request 层统一返回 `Promise>`:新增接口必须显式标注泛型 `T`,组件消费 `res.data` 时应有明确类型,禁止把后端字段拼错暴露到运行期。 - 默认超时 30 秒;AI 聚合类接口(残片生成、思维导图生成/对比、报告草稿、结束会话)在 api 层显式覆写 `{ timeout: 300_000 }`,不要调大全局默认值。 - 组件解构响应时使用 `res?.data` 判空兜底;`ApiResponse` 从 `@/utils/request` 导入复用。 ### 组合式函数复用 - “已等待 N 秒”类秒表计时统一使用 `useElapsedSeconds`,禁止组件内手写 `setInterval` 秒数递增。 - 骨架/加载指示的「延迟显示 + 最短可见」统一使用 `useDelayedVisible`,禁止组件内手写 setTimeout 开关加载态。 - 页面新增功能域时先抽 composable(参考 `useSessionHistory` / `useSummaryReport` / `useSessionExpectation`),不要继续膨胀 StartTask 等大页面组件。 - 通用解析器、格式化工具放 `src/utils/`,不埋在组件内(如大纲文本转树应放 utils)。