Markdown 表格

表格是 GFM（GitHub Flavored Markdown）扩展——原版 Markdown 不支持，但现在几乎所有引擎都支持。表格让数据、对照、参数说明一目了然，是技术文档的利器。但它的语法不算直观，而且有明显局限。这一章讲清楚。

1. 基本表格

表格由表头行、分隔行、数据行组成，每列用竖线 | 分隔：

| 姓名 | 年龄 | 城市 |
|------|------|------|
| Alice | 25 | 北京 |
| Bob | 30 | 上海 |
| Carol | 28 | 广州 |

关键点：第二行的 |---| 是分隔行，不可省略——它告诉解析器"上面是表头"。它的横线数量不重要，但至少一根。

2. 列对齐

在分隔行里加冒号，可以控制该列的对齐方式：

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 左     | 中       | 右     |
| 姓名   | 工号     | 金额   |

（冒号位置决定对齐方式）
- 左：冒号在左
- 中：两边都有冒号
- 右：冒号在右
- 默认：无冒号，左对齐

对齐只影响渲染（CSS 的 text-align），不影响数据。中文等宽字符的对齐效果通常不太明显，英文数字更直观。

3. 紧凑写法

不强制对齐列宽，竖线之间的内容可以紧贴：

分隔线最少只需一个减号：

|姓名|年龄|城市|
|-|-|-|
|Alice|25|北京|
|Bob|30|上海|

不强制对齐列宽，但可读性差。

虽然语法允许，但源码可读性很差。建议在编辑器里用 Prettier 自动格式化表格，让列宽对齐。

4. 单元格内的行内格式

单元格里可以放任何行内 Markdown——粗体、斜体、代码、链接、图片：

单元格内支持行内格式：

| 命令 | 说明 |
|------|------|
| `git init` | 初始化仓库 |
| **加粗** | 强调重要命令 |
| [文档](url) | 跳转链接 |
| ~~旧版~~ | 已废弃 |
| ![图](a.png) | 也可放图片 |

这个特性让表格非常适合写"命令说明"、"参数对照"、"版本兼容性"等。

5. 单元格内的多行内容

块级元素（列表、标题、代码块）不能直接放在单元格里——会破坏表格结构。变通方法是用 HTML：

单元格不能直接放块级元素（列表、标题、代码块）。

变通 1：用 HTML <br> 换行
| 步骤 | 内容 |
|------|------|
| 安装 | 下载 <br> 解压 <br> 运行 |

变通 2：用 HTML <ul><li>
| 类型 | 选项 |
|------|------|
| 颜色 | <ul><li>红</li><li>蓝</li></ul> |

变通 3：用行内短横线
| 颜色 | 红 / 蓝 / 绿 |

6. HTML 表格（回退方案）

当 Markdown 表格能力不够时（合并单元格、着色、嵌套），直接写 HTML——大多数 Markdown 引擎会原样渲染：

需要合并单元格等复杂排版，直接写 HTML：

<table>
  <tr>
    <th>季度</th>
    <th>销售额</th>
  </tr>
  <tr>
    <td>Q1</td>
    <td>100 万</td>
  </tr>
  <tr>
    <td>Q2</td>
    <td>150 万</td>
  </tr>
</table>

缺点是源码可读性变差，建议仅在必要时使用。

7. 表格的局限

Markdown 表格的局限：
- 不能合并单元格（colspan / rowspan）
- 单元格内不能嵌套块级元素
- 不能直接调整列宽
- 不能设置背景色（需 HTML）
- 不能嵌套表格

需要这些功能时，请直接写 HTML 表格。

记住这些限制，遇到需求时不要硬用 Markdown 表格——直接写 HTML 或换一种表达方式（如列表 + 缩进）。

8. 最佳实践

• 用 Prettier 自动对齐：源码里表格列宽整齐，便于阅读和 diff。
• 列数不要太多：超过 4 列在手机端会横向滚动，体验差。
• 避免长文本：表格适合放短数据，长段落请用普通段落。
• 数字右对齐：金额、数量等数字列建议右对齐，便于对比。
• 第一行必须是表头：留空表头会让屏幕阅读器困惑。

9. 常见坑

• 忘写分隔行：少了 |---|，整个表格不渲染。
• 列数不一致：某行少一个 |，该行末尾会出现空白单元格或解析错乱。
• 表格紧贴前文：表格前后必须有空行，否则会和段落粘连。
• 单元格内有竖线：竖线是分隔符，必须用 \| 转义或写成 HTML 实体。
• 表格内换行：源码里换行会破坏单元格，必须用 <br>。

小结

表格让文档"信息密度"上一个台阶——尤其适合参数表、对照表、版本兼容性。下一篇讲引用，把别人的话或自己的旁注清晰标出。

← 上一篇 代码

下一篇 引用 →