我们要解决什么问题？

团队往往记得标题、替代文本和对比度，却忘了示例本身也是内容。页面看起来没有问题，但最重要的部分——代码、JSON 响应或字段表——可能难以阅读、过度依赖语法高亮，或者不利于屏幕阅读器理解。

一篇好的文章不应只说“请注意可访问性”，而应当在文章内部展示正确做法：给出上下文、预期结果、清晰结构，以及在没有颜色时仍然成立的说明文字。

可访问示例的原则

  1. 代码块之前先说明目标。
  2. 不要让颜色成为唯一的意义载体。
  3. 成功、警告和错误要分开呈现。
  4. 只有在确实存在行列关系时才使用表格。
  5. 一个单元格只放一个事实，一个示例只承担一个主要目的。

示例 1：先说明任务，再给出请求

获取报告 42。将 <token> 替换为有效的访问令牌。成功时服务器返回 HTTP 200，并给出 status 为 ready 的 JSON。

GET /v1/reports/42 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
{
  "id": 42,
  "status": "ready",
  "download_url": "/v1/reports/42/file"
}
{
  "error": "not_found",
  "message": "报告 42 不存在，或已不可用。"
}

示例 2：让表头承担意义

字段 类型 必填 含义 说明
id integer 是 报告标识符 所有成功响应都会返回
status string 是 处理状态 常见值：queued、running、ready、failed
download_url string 否 文件下载地址 只有 status = ready 时出现
error string 否 错误代码 仅失败响应中出现
检查项 要问的问题 好的表现
目标 是否说明了示例的用途？ 读者在看代码前就知道结果
结构 成功与错误是否分开？ 有独立区块或清晰标签
表格 表头是否定义了单元格的意义？ 结合表头即可理解单元格
语言 说明是否清晰且简洁？ 解释帮助理解，而不是增加负担

示例 3：当结构本身重要时，展示标记

<table>
  <caption>报告响应字段</caption>
  <thead>
    <tr>
      <th scope="col">字段</th>
      <th scope="col">类型</th>
      <th scope="col">必填</th>
      <th scope="col">含义</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>是</td>
      <td>当前处理状态</td>
    </tr>
  </tbody>
</table>

应避免的做法

  • 没有上下文的代码块；
  • 仅用颜色区分成功和错误；
  • 用表格排版步骤或长段落；
  • 单元格中塞入多个独立事实；
  • 用代码截图代替可复制文本。

作者可直接采用的写作顺序

  1. 目标。
  2. 前提条件。
  3. 示例。
  4. 预期结果。
  5. 常见错误。
  6. 如有必要，再给参考表格。

简短编辑清单

  • 在代码块前说明目的。
  • 将成功与错误分开。
  • 让代码在没有颜色时也可理解。
  • 只有在确有行列关系时才使用表格。
  • 优先使用可复制文本，而不是代码截图。

相关文章