前端开发 是做什么的?
供真实用户使用键盘、屏幕阅读器、慢速手机和打印机的浏览器UI标准。 以下规则是UI“看起来已完成”时经常被忽略的部分。
最重要的规则
- 使用含义正确的元素。
<button>用于操作,<a href>用于导航,每个字段都需要<label>,表格数据使用<table>。带有点击处理器的<div>不可聚焦、没有角色,并且对辅助技术不可见。ARIA 仅用于填补原生元素无法满足的空白。 - 每个异步视图有四种状态: 加载、错误、空数据和数据。在认为视图完成之前,请编写所有四种状态。空白区域是一个bug。
- 绝不伪造数据。 缺失的数据点是间隙或“无数据”标签,绝不是零,也不是插值线。预测始终与实际情况明显不同。
- 绝不单独使用颜色传递信息。 每个颜色编码的状态还必须包含文本或带有可访问名称的图标。否则,灰度打印和色盲读者将无法获取任何信息。
- 可共享的状态存在于URL中。 过滤器、标签页、搜索词、选中的ID。返回、刷新和分享必须保留这些状态。临时状态(悬停、打开的提示框)不放入URL。
- 由多个状态片段推导出的值应放在一个函数中,在任何状态变化时调用。 绝不要将其计算在属于某个状态的回调函数内部。例如:基于截止日期和组过滤器构建的下载链接,仅在截止日期的获取回调中重建,因此在过滤器更改后,导出功能会静默地指向整个列表。
- 从320 CSS像素宽度开始适配。 没有水平页面滚动,没有内容被裁剪,文本可缩放至200%。在手机宽度和你设计的桌面宽度上都进行测试。
- 根据需求匹配工具。 在现有仓库中,遵循已有的框架和构建工具。对于小型新页面或内部工具,在添加构建流程之前,先考虑纯HTML、CSS和少量JavaScript;当状态确实需要时再使用框架。
何时不应使用
- 选择视觉方向、排版或调色板:请使用
designer和visual-design技能。 - 原生 iOS、Android 或 React Native:请使用
mobile技能(Swift 代码使用swift)。 - API 形状和服务器端点:请使用
api-design和backend-patterns技能。 - 测试技术深入:请使用
tdd和testing-strategy技能。
状态的存储位置
在编写组件状态之前决定。从局部开始,仅在明确理由下升级。
| 状态 | 存储位置 | 示例 |
|---|---|---|
| 本地UI | 组件状态 | 模态框打开、输入草稿、悬停 |
| 兄弟组件共享 | 最近的共同父组件 | 两个面板读取的活动标签页 |
| 服务器数据 | 服务器缓存库(TanStack Query, SWR)或框架的加载器 | API响应、分页、重新获取 |
| 应用级客户端状态 | 小型存储(仅在需要时) | 已登录用户、通知队列 |
| 可共享视图状态 | URL查询或路由 | 过滤器、搜索、选中的ID |
| 跨重新加载持久化,按设备 | localStorage | 偏好设置、未发送的草稿 |
仅在以下情况升级:两个无关组件需要相同状态(提升它,或使用服务器缓存);状态必须在重新加载后持久化(URL或存储);数据来自服务器(服务器缓存,而非全局存储)。复制到全局存储的服务器数据会变得过期,并且重复加载和错误逻辑。
图表、打印和简化视图
- 图表:前后端共享一种颜色映射,明确的空状态,诚实的间隙,HTML图例。在构建或更改图表之前阅读
references/charts.md。 - 打印或PDF:在构建可打印视图之前阅读
references/print.md。没有其中描述的捕获步骤,Canvas 无法可靠打印。 - 面向非技术读者的简化或只读视图:无编辑控件,慷慨的文本和目标大小,使用颜色和文字表示状态,基于数据计算的通俗语言摘要,少量屏幕,以及用简短句子呈现的关键数字而非原始表格。
性能
按影响顺序优化:先处理请求瀑布流,然后是传输的JavaScript,接着是服务器响应时间,再是交互期间主线程的工作,最后是微优化。目标:在第75百分位的实际访问中,LCP ≤ 2.5秒,INP ≤ 200毫秒,CLS ≤ 0.1。当页面速度慢时,在添加重量级依赖项之前,或在进行有性能目标的发布之前,请阅读 references/performance.md。
陷阱
- 渲染路径是热点循环。 组件体或计算的getter在每次悬停和每次无关状态更改时都会运行。那里的重量级推导会阻塞主线程,第一个症状可能是其他地方的测试不稳定。先去重,然后在上游输入上记忆化。
- 未声明的CSS自定义属性会静默失败。 当 token 是
--font-mono时,var(--mono)在计算值时间使声明无效:属性继承,没有错误。在简写属性中(font: 400 10px/1 var(--mono)),字号和行高也会丢失。为var()提供回退值,或检查已声明的 token 与已构建样式表中被引用的 token 是否一致。 - 图表的高度放在其包装器上。
canvas上的高度会与库的调整大小逻辑冲突,导致图表在每次调整大小时变大。 - 焦点管理是你自己的责任(在自定义小部件中)。 打开对话框将焦点移入其中;关闭对话框将焦点返回到触发器;Escape 关闭对话框。优先使用原生
<dialog>元素。使用innerHTML重建标记会丢失焦点。 - 没有替代方案的
outline: none会移除键盘用户唯一的线索。请改用:focus-visible来设置样式。 - 仅图标的按钮需要名称(
aria-label或视觉上隐藏的文本)。 - 仅在客户端获取后才存在的内容 在弱设备上很慢,当 JavaScript 失败时显示为空白,对爬虫更不友好。在堆栈允许的情况下,在服务器上渲染有意义的内容。
- 未设置尺寸的媒体会导致布局偏移。 在图片、视频和嵌入内容上设置
width和height(或aspect-ratio)。永远不要延迟加载首屏上方最大的图片。 - 手工制作的下拉菜单、标签页和滑块 需要来自 WAI-ARIA 创作实践的完整键盘模型。原生元素几乎总是更便宜。
- 手工编写的伪造DOM会使测试失效。 如果伪造对象每次查找都返回一个新鲜对象,那么写入它的每个属性(
href、disabled、value)都会丢失,并且任何关于它的断言都不会失败。回退该特性并要求测试在信任它之前失败。 - 使用固定版本的CDN,绝不使用未固定版本。 未固定的脚本会在没有提交的情况下悄然改变。
验证
使用项目已有的工具(测试运行器、linter、类型检查器、无障碍性工具)进行验证,然后再添加新工具。
- 测试、lint 和类型检查通过。任何新测试在回退该特性后应能观察到失败。
- 在手机宽度和桌面宽度上渲染并查看了页面。尽可能给审查者提供运行的预览以及截图。
- 纯键盘:每个控件可到达、可操作且可见焦点;顺序与视觉顺序匹配;无陷阱。
- 自动化无障碍审核(axe、Lighthouse 或项目工具)没有新的违规。使用工具检查对比度:正文文本 4.5:1,大文本和UI组件边框 3:1(WCAG AA)。
- 通过强制触发,分别显示加载、错误、空数据和数据状态。
- 可共享状态在刷新和返回后仍然存在。
- 加载时和使用过程中,控制台零错误和零警告。
- 如果更改添加了依赖项或影响了重量级视图,则检查性能预算(包分析器、限速分析)。
- 如果页面可打印,则检查打印预览。
对于审查,按文件报告发现的违规,指出违反的规则和修复方法,从最严重的开始。