表格

AsciiDoc表语法的外观和行为与其他分隔块类型相似，并支持标准块配置条目。格式化易于阅读，同样重要的是，易于输入。

可以使用内置的可自定义样式格式化单元格和列。
可以在列和单元格上设置水平和垂直单元格对齐。
支持水平和垂直单元格的合并。

谨慎使用表格

当技术用户首次开始创建文档时，表（包括列跨越和表嵌套）通常被认为非常重要。实际情况是表格很少使用，即使在技术文档中也是如此。

试试这个练习：翻阅你的技术书籍库，你会惊讶于实际上很少使用表格，更不用说包含块元素（如段落或列表）或合并单元格的表格。这不是偶然的，如数字，表格在正常的文件流程之外 - 表格用于咨询而不是阅读。

表是为显示面向列的表格数据而设计的，通常只应用于表格。

1. 表样例

Table 1. 简单的表
1	2	A
3	4	B
5	6	C

AsciiDoc源:

[width="15%"]
|=======
|1 |2 |A
|3 |4 |B
|5 |6 |C
|=======

Table 2. 使用强大，等宽和强调样式格式化的列
	Columns 2 and 3
footer 1	`footer 2`	footer 3
1	`Item 1`	Item 1
2	`Item 2`	Item 2
3	`Item 3`	Item 3
4	`Item 4`	Item 4

AsciiDoc源:

[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
|==========================
|      2+|Columns 2 and 3
|1       |Item 1  |Item 1
|2       |Item 2  |Item 2
|3       |Item 3  |Item 3
|4       |Item 4  |Item 4
|footer 1|footer 2|footer 3
|==========================

Table 3. 水平和垂直源数据
Date	Duration	Avg HR	Notes
22-Aug-08	10:24	157	Worked out MSHR (max sustainable heart rate) by going hard for this interval.
22-Aug-08	23:03	152	Back-to-back with previous interval.
24-Aug-08	40:00	145	Moderately hard interspersed with 3x 3min intervals (2min hard + 1min really hard taking the HR up to 160).

AsciiDoc源:

[width="80%",cols="3,^2,^2,10",options="header"]
|=========================================================
|Date |Duration |Avg HR |Notes

|22-Aug-08 |10:24 | 157 |
Worked out MSHR (max sustainable heart rate) by going hard
for this interval.

|22-Aug-08 |23:03 | 152 |
Back-to-back with previous interval.

|24-Aug-08 |40:00 | 145 |
Moderately hard interspersed with 3x 3min intervals (2min
hard + 1min really hard taking the HR up to 160).

|=========================================================

Table 4. 包含外部源CSV数据的表
ID	Customer Name	Contact Name	Customer Address	Phone
AROUT	Around the Horn	Thomas Hardy	120 Hanover Sq. London	(171) 555-7788
BERGS	Berglunds snabbkop	Christina Berglund	Berguvsvagen 8 Lulea	0921-12 34 65

AsciiDoc源:

[format="csv",cols="^1,4*2",options="header"]
|===================================================
ID,Customer Name,Contact Name,Customer Address,Phone
Unresolved directive in asciidoc-table.adoc - include::customers.csv[]
|===================================================

Table 5. 列合并，对齐和样式
1	2	3	4
5	`6`		`7`
8
9	`10`

AsciiDoc源:

[cols="e,m,^,>s",width="25%"]
|============================
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|============================

2. 表输入数据格式

AsciiDoc表数据可以是 psv，dsv或csv格式。默认表格式为psv。

AsciiDoc psv（前缀分隔值）和dsv（分隔符分隔值）格式是面向单元格的 - 表被视为一系列单元格 - 没有明确的行分隔符。

psv使用分隔符为每个单元格添加前缀，而dsv使用分隔符分隔单元格。
psv和dsv分隔符是Python正则表达式。
默认的psv分隔符包含与命名的正则表达式组相关的单元格说明符。
默认的dsv分隔符是 : | \n（冒号或换行符）。
psv和dsv单元格分隔符可以通过在它们前面加上反斜杠字符进行转义。

这里有四个psv单元格（第二个项目合并两列;最后一个包含一个转义分隔符）：

|One 2+|Two and three |A \| separator character

csv是通常用于导入和导出电子表格和数据库数据的标准行导向逗号分隔值（CSV）格式。

3. 表属性

可以通过以下属性自定义表：

format

psv（默认值），dsv或csv（请参阅表数据格式）。

separator

单元格分隔符。Python正则表达式（psv和dsv格式）或单个字符（csv格式）。

frame

定义表格边框，可以采用以下值：topbot（顶部和底部），all（所有边），none和side（左边和右边）。默认值为all。

grid

定义在表行和列之间绘制的网格线。grid属性值可以是以下任何值：none，cols，rows和all。默认值为all。

align

使用align属性在页面上水平对齐表格（仅适用于HTML输出，对DocBook输出没有影响）。以下值有效：left，right和center。

float

使用float属性在页面上向左或向右浮动表格（仅适用于HTML输出，对DocBook输出没有影响）。浮动仅与表width属性值小于100％一起才有意义（否则表将占用所有可用空间）。float和align属性是互斥的。使用 unfloat::[] 块宏来停止浮动。

halign

使用halign属性水平对齐表中的所有单元格。以下值有效：left，right和center（默认为left）。可由列说明符和单元格说明符覆盖。

valign

使用valign属性垂直对齐表格中的所有单元格。以下值有效：top，bottom和middle（默认为top）。可由列说明符和单元格说明符覆盖。

options

options属性可以包含逗号分隔值，例如：header,footer。默认情况下，页眉和页脚行被省略。有关可用表选项的完整列表，请参阅属性选项。

cols

cols属性是以逗号分隔的列说明符列表。例如 cols="2<p,2*,4p,>"。

如果cols存在，则必须指定所有列。
如果未指定cols属性，则列数将计算为表的第一行中的数据项数。
cols属性的简并形式是一个整数，用于指定列数，例如 cols=4。

width

width属性表示为百分比值（"1%"…"99%"）。width指定相对于可用宽度的表格宽度。HTML后端使用此值来设置表格宽度属性。使用DocBook有点复杂，请参阅侧边栏<<,DocBook表格宽度>>。

filter

filter属性定义为每个单元调用的外部shell命令。内置的asciidoc表样式是使用过滤器实现的。

DocBook表格宽度

AsciiDoc docbook后端生成CALS表。CALS表不支持表宽度属性 - 表格宽度只能通过指定绝对列宽来控制。

指定绝对列宽不是媒体独立的，因为不同的表示媒体具有不同的物理尺寸。为了解决这个限制， DocBook XSL样式表和 dblatex都实现了表宽处理指令，用于将表宽度设置为可用宽度的百分比。如果width属性与比例列宽度一起设置，则AsciiDoc会发出这些处理指令（AsciiDoc docbook后端pageunits属性默认为 *）。

要生成具有绝对列宽的DocBook表，请将pageunits属性设置为CALS绝对单位（如pt），并将pagewidth属性设置为与表示媒体的宽度相匹配。

4. 列说明符

列说明符定义在表cols属性中，用以说明如何呈现列。列说明符由可选的列乘数后跟可选的对齐，宽度和样式值组成，格式如下：

[<multiplier>*][<align>][<width>][<style>]

所有组件都是可选的。乘数必须是第一个，样式必须是最后一个。<align> 或 <width> 的顺序并不重要。
列 <width> 可以是整数比例值（1…）或百分比（1%…100%）。默认值为1.为确保跨不同后端的可移植性，不提供绝对列宽（不要与以百分比和绝对单位都可用的输出列宽标记属性混淆）。
<align> 列对齐说明符的格式如下：

[<horizontal>][.<vertical>]

其中 <horizontal> 和 <vertical> 是以下字符之一：<，^ 或 > 分别代表水平对齐左，中，右或垂直对齐上，中和下。

<multiplier> 可用于指定重复列，例如 cols="4*<" 指定四个左对齐列。默认乘数值为1。
<style> 名称指定用于标记列单元格的表格样式（如果你愿意，可以使用完整样式名称，但通常用第一个字母就足够了）。
列特定样式不应用于标题行。

5. 单元格说明符

单元格说明符允许psv格式化表格中的单个单元格进行合并，复制，对齐和样式化。单元格说明符前缀psv分隔符为 |，格式如下：

[<span>*|+][<align>][<style>]

<span> 指定水平和垂直单元格跨度（+ 运算符）或单元格复制的次数（* 运算符）。<span> 的格式如下：

[<colspan>][.<rowspan>]

其中 <colspan> 和 <rowspan> 是指定要跨越的列数和行数的整数。

<align> 指定水平和垂直单元格对齐方式与列说明符中的相同。
<style> 值是表格样式名称的第一个字母。

例如，以下psv格式的单元格将跨越两列，文本将居中并强调：

2+^e| Cell text

6. 表格样式

表样式可以应用于整个表（通过在表的属性列表中设置样式属性）或基于每列（通过在表的cols属性中指定样式）。可以使用以下预定义样式格式化表数据：

default: 默认样式：AsciiDoc内联文本格式；空行被视为分段符。
emphasis: 像默认一样，但强调（斜体）所有文字。
monospaced: 与默认值一样，但所有文本都采用等宽字体。
strong: 像默认一样，但所有文字都是粗体。
header: 应用与表头相同的样式。通常用于在第一列中创建垂直标题。
asciidoc: 使用此样式表单元格可以包含文档部分中允许的任何AsciiDoc元素。此样式将 asciidoc(1) 作为处理单元格内容的过滤器运行。另请参阅 Docbook表限制。
literal: 没有文字格式；等宽字体；保留所有换行符（与AsciiDoc LiteralBlock元素相同）。
verse: 保留所有换行符（就像AsciiDoc 段落样式一样）。

7. 标记属性

AsciiDoc为表标记模板和标记提供了许多属性。替换colspec单元格数据标记时，可以使用列特定的属性。

pageunits: 仅限DocBook后端。指定表列绝对宽度单位。默认为 *。
pagewidth: 仅限DocBook后端。以pageunit为单位的标准输出页宽。用于计算CALS表的绝对列和表宽度。默认为 425。
tableabswidth: 根据width和pagewidth属性计算的整数值。在pageunit单位下。
tablepcwidth: 表宽度表示为可用宽度的百分比。整数值（0..100）。
colabswidth: 从cols列宽度，width 和pagewidth属性计算的整数值。在pageunit单位下。
colpcwidth: 列宽表示为表宽的百分比。整数值（0..100）。
colcount: 表列总数。
rowcount: 表行总数。
halign: 水平单元格内容对齐：left, right或center。
valign: 垂直单元格内容对齐：top, bottom或middle。
colnumber, colstart: 单元格占用的最左列的编号（1…）。
colend: 单元格占用的最右列的编号（1…）。
colspan: 单元格应跨越的列数。
rowspan: 单元格应跨越的行数（1…）。
morerows: 单元格应跨越的额外行数（0…）。

8. 嵌套表

另一个psv分隔符 ! 可以在嵌套表中使用（而不是 |）。这允许单级表嵌套。包含嵌套表的列必须使用asciidoc样式。可以在 ./examples/website/newtables.txt 中找到一个示例。

原文链接