默认表格语法

一张表格由一个竖直的条形和三个等号 (|===) 划分。它包含的单元格按照表格被分配的列数排成行。表格包含的列数可以通过表格第一行的单元格数隐式指定，或者通过设置 cols 属性来明确指定。每个单元格都由一个竖直的条形 (|) 指定。

如果你对AsciiDoc表格不熟悉，build-a-basic-table.html 提供了创建你的第一个表格的分步指导。

样式和布局选项

表格的内容可以是：

  • 按列或单元格样式化并对齐，

  • 按行对齐，

  • 重复出现在多行中，并且

  • 被任何AsciiDoc语法标记。

表格单元格可以跨越多行和多列。

你可以调整一个表格的：

  • 宽度，

  • 朝向，和

  • 边框样式。

您也可以指定每一列的宽度，并且指定表头和表尾行。

受支持的数据格式

默认的表格数据格式是前缀分隔值（PSV）；这意味着处理器每次遇到垂直线（|）时就会创建一个新的单元格。AsciiDoc还支持逗号分隔值（CSV）、制表符分隔值（TSV）和定界数据值（DSV）。

逃离单元格分隔符

解析器会在处理单元格文本之前扫描单元分隔符来划分单元格。因此，即使你尝试使用内联跳过来隐藏单元分隔符，解析器也会识别它。如果单元格内容中包含单元分隔符，你必须转义该字符。有三种转义方法：

  • 在字符前加上前导反斜杠（即 \|），这将从输出中删除。

  • 在内容中使用 {vbar} 属性引用来代替 |。

  • 更改表格使用的单元格分隔符。

除非你做了这些事情之一，否则单元格分隔符将被解释为单元格边界。

考虑以下示例，它使用前导反斜杠来转义单元格分隔符：

|===
[cols=2*]
|PSV 表格中默认的分隔符是 \| 字符。
|这个 \| 字符经常被称为“管道”符。
|===

这张表格将会如下呈现：

结果：转换后的PSV表格包含管道字符 [列=2*]

PSV表格中的默认分隔符是|字符。

|字符通常被称为“管道”。

注意，在渲染的结果中管道字符出现没有前导反斜杠（即，未转义）。

一个替代方法是使用属性引用`{vbar}`作为替代。这种方法产生的结果与前一个例子相同。

|====
[cols=2*]
|PSV 表中的默认分隔符是 {vbar} 字符。
|{vbar} 字符常被称为“管道符”。
|====

在单元格的内容中每次遇到单元格分隔符时都进行转义可能很繁琐。 也有一些时候，你不能或不想修改单元格内容（可能是因为它包含在另一个文件中）。 为了解决这些情况，AsciiDoc允许你覆盖单元格分隔符。

单元格分隔符是通过表格块上的`separator`属性来控制的。 您会想选择任何一个在内容中找不到的单个字符。 一个好的候选字符是破折号，或者`¦`。

这是用自定义分隔符重写的前一个例子。

[cols=2*,separator=¦]
|===
PSV表格中默认的分隔符是 | 字符。
| 字符通常被称为“管道”。
|===

请注意，现在不再需要在表格单元格的内容中转义管道字符。 你可以在单元格内容中安全地使用原始的单元格分隔符，并且不用担心它会被解释为单元格的边界。

分隔符分隔的值 == 分隔符分隔的值

表格也可以从格式为分隔符分隔值的数据填充（即数据表）。与前置分隔值（PSV）格式相比，在PSV格式中分隔符位于每个单元格值的前面，而分隔符分隔格式（CSV、TSV、DSV）中的分隔符则放置在单元格值之间（称为_分隔符_），并且不接受单元格格式规范。每行数据被假定为代表一行，尽管你会发现这不是一个严格的规则。表格数据如何被解释由表格的`format`和`separator`属性控制。

这些分隔符是什么？** 难道逗号分隔值不是https://en.wikipedia.org/wiki/Delimiter-separated_values[分隔值定界符^]的一个子集吗？这真的取决于你咨询的对象。

本文中的“分隔符分隔值”一词指的是使用分隔符的数据格式家族，包括逗号分隔值（CSV）、制表符分隔值（TSV）和定界符数据（DSV），所有这些格式都在AsciiDoc表中得到支持。CSV是最常用的数据格式。

"`逗号分隔值`"实际上是一个易引起误解的术语，因为CSV可以使用除了`,`之外的其他定界符作为字段分隔符（在这个上下文中，它用来分隔单元格）。我们真正讨论的是数据如何被解释。

CSV和TSV都使用定界符和一个可选的包围字符，它们大致基于https://tools.ietf.org/html/rfc4180[RFC 4180^]。DSV（即定界数据）仅使用定界符，可以使用反斜杠进行转义；不识别包围字符。这些解析规则在[data-table-formats]中有详细描述。**

让我们考虑一个使用逗号分隔值（CSV）填充AsciiDoc表格数据的例子。要指导处理器将数据读取为CSV，需要将表格的`format`属性设置为`csv`。当`format`属性设置为`csv`时，默认的数据分隔符是逗号（,），如下表所示。

源代码

Unresolved directive in data-format.adoc - include::example$data.adoc[tag=csv]

.Result: Rendered CSV table
[width=90%]
Unresolved directive in data-format.adoc - include::example$data.adoc[tag=csv]

这个功能在你想要从存储在一个单独文件中的数据来填充你手稿中的表格时特别有用。
你可以使用表格分隔符之间的xref:directives:include.adoc[include指令]来实现，如下所示：

[source]
include::tracks.csv[] 
如果你的数据是由制表符分隔的而不是逗号，将 `format` 设置为 `tsv`（制表符分隔的值）即可。

现在让我们考虑一个使用定界符数据（DSV）来填充AsciiDoc表格的例子。为了指示处理器将数据读取为DSV，请将表格上的`format`属性值设置为`dsv`。当`format`属性设置为`dsv`时，默认的数据分隔符是冒号（`:`），如下表所示。

[source]

Unresolved directive in data-format.adoc - include::example$data.adoc[tag=dsv]

.Result: Rendered DSV table
[width=90%]
Unresolved directive in data-format.adoc - include::example$data.adoc[tag=dsv]

== 数据表格格式

CSV和TSV数据格式的解析方式与DSV数据格式不同。以下两节将概述这些差异。

=== CSV和TSV

CSV或TSV格式的表格数据根据以下规则进行解析，这些规则基本上基于{url-rfc-4180}[RFC 4180^]：

CSV文件的默认分隔符是逗号（`,`），而TSV文件的默认分隔符是制表符。
空行会被跳过（除非包含在引号值中）。
每个值周围的空白会被去除。
值可以用双引号（`"`）包围。
 ** 引用的值可以包含零个或多个分隔符或换行符。
 ** 引用中的换行符不会开始新行，除非换行符被双引号包围。
 ** 如果引用的值中包含双引号字符，则可以使用另一个双引号进行转义（`""`）。
 ** 引用中的换行会被保留。
如果行的单元格数量不一致（所谓的“不规则”表格），单元格将被重新排列以完全填满行。
 ** 这与Excel的处理方式不同，Excel会使用空单元格填充较短的行。
 ** 最后一行末尾的多余单元格将被舍弃。
 ** 一般来说，一行的数据应该在同一行上。

=== 分隔值数据

DSV格式的表格数据根据以下规则进行解析：

* DSV的默认分隔符是冒号(`:`)。 * 空行将被跳过。 * 去除每个值周围的空白。 * 如果值中包含分隔符字符，可以使用单个反斜线(`\:`)进行转义。 * 如果行的单元格数不一致（“不规则”的表格），将重新排列单元格以充分填满行。

== 自定义分隔符

每种数据格式都有一个默认的分隔符与之关联（csv=逗号，tsv=制表符，dsv=冒号），但可以通过设置表格的`separator`属性将分隔符更改为任何字符（甚至一串字符）。

以下是一个使用自定义分隔符（即定界符）的DSV表的例子：

一张使用自定义分隔符[source]的DSV表格

a

b

c

d

e

f

 
提示：要创建TSV表格，您可以将`format`属性设置为`csv`，并将分隔符设置为`\t`。尽管更推荐使用`tsv`格式。

分隔符与格式的处理规则无关。
如果你设置 `format=dsv` 和 `separator=,`，即使数据看起来像是CSV，数据也会按照DSV规则进行处理。

== 数据表的简写表示法

AsciiDoc为指定表格的数据格式提供了简写符号。 表格块定界符（即 `|===`）的第一个位置可以被内置的定界符替换, 以设置表格格式（例如，`,===` 用于CSV）。

要创建一个CSV表格，你可以使用`,===`作为表格块的分隔符：

源代码

Unresolved directive in data-format.adoc - include::example$data.adoc[tag=s-csv]

.Result: Rendered CSV table using shorthand syntax
[width=90%]
Unresolved directive in data-format.adoc - include::example$data.adoc[tag=s-csv]

为了制作DSV表格，您可以使用 `:===` 作为表格块的分隔符：

[source]

Unresolved directive in data-format.adoc - include::example$data.adoc[tag=s-dsv]

.Result: Rendered DSV table using shorthand syntax
[width=90%]
Unresolved directive in data-format.adoc - include::example$data.adoc[tag=s-dsv]

当使用CSV或DSV简写时，你不需要设置`format`属性，因为它是隐含的。

为了创建一个TSV表格，你可以将`format`属性设置为`tsv`，而不是将`format`设置为`csv`并将分隔符设置为`\t`。
在这种情况下，你可以使用`|===`或者`,===`作为表格块的分隔符。
没有特别的界定块表示法用于TSV表格。

== 格式化数据表中的单元格

限定格式不提供表达单个表格单元格格式的方法。相反，您可以使用表格上的`cols`规范来对给定列中的所有单元格应用单元格格式。

源代码

Sky
sky

Forest
forest 
数据表格不支持跨多行或多列的单元格，因为那些信息只能在单元格层面上表示出来。如果您需要这项功能，建议您使用PSV格式。