表格

3.9. 表格#

表格语法说明：http://docutils.sourceforge.net/docs/ref/rst/directives.html#csv-table

备注

一般情况下使用外部文件式CSV表格，修改比较方便。

3.9.1. 表格语法参考#

reStructureText提供两种表格：网格表格（Grid Tables）， 简单表格（Simple Tables）。

表格前后都需要空行

网格表格#

  • "-" 分隔行(短破折号，减号)

  • "=" 分隔表头和表体行

  • "|" 分隔列

  • "+" 表示行和列相交的节点

网格表格注意点：

  • 网格表格编辑复杂，可以使用Emacs来编辑生成

  • 行和列都支持并格

  • 如果文本内包含"|" ，并且恰好与表格内分隔对齐了，那么会产生错误。解决方案 : 方式一是加空格避免对齐，方式二是为该行增加一行

  • 可以不包含表头。

  • 列需要和"="左对齐，不然可能会导致出错

  • 如果碰到第一列为空，需要使用 "\" 来转义, 不然会被视为是上一行的延续。

示例：

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

结果：

Header row, column 1 (header rows optional)

Header 2

Header 3

Header 4

body row 1, column 1

column 2

column 3

column 4

body row 2

Cells may span columns.

body row 3

Cells may span rows.

  • Table cells

  • contain

  • body elements.

body row 4

简单表格#

简单表格使用 "=" 和 "_" 来进行绘制，其中"=" 放置于表格的最外两行（首行和末行）,如果有表头，则表头也用该符号进行分隔，"_"用于跨列合并（column span）。

简单表格需要各列首字母与该列指示的"="对齐(表头可不对齐，为了保持统一，尽量保持左对齐)，每列的"="需要覆盖该列字符的长度

包含表头的简单表格#

语法如下：

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

效果如下：

A

B

A and B

False

False

False

True

False

False

False

True

False

True

True

True

无表头的简单表格#

语法如下：

=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

效果如下：

False

False

False

True

False

False

False

True

False

True

True

True

跨列合并#

"_"用于跨列合并，仅支持在表头使用，"_"长度需要从起始列的第一个指示符"="到终止列的最后一个指示符"="

语法如下：

=====  =====  ======
合并两列      单独列
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

效果如下:

合并两列

单独列

A

B

A or B

False

False

False

True

False

True

False

True

True

True

True

True

单个表格中可以多行#

  • 简单表格的单个格子中可以包含多行的内容（比如列表），但是不支持行合并；

  • 增加空行可以进行换行，否则会自动将文本连接在一起。

  • 首列不能为空，为空时使用 \ 进行占位。

语法如下：

=====  ===================================
col 1  col 2
=====  ===================================
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  ===================================

效果如下：

col 1

col 2

1

Second column of row 1.

2

Second column of row 2. Second line of paragraph.

3

  • Second column of row 3.

  • Second item in bullet list (row 3, column 2).

Row 4; column 1 will be empty.

3.9.2. 外部文件式CSV表格#

可以通过外部文件的方式插入CSV表格，如：

.. csv-table:: 外部CSV表格示例
   :file: deploy.csv
   :widths: 5, 20
   :header-rows: 1

效果：

表 3.9.1 外部CSV表格示例#

name

备注

a1

igais/yubiao

a2

a4

osgeo/jubook

3.9.3. CSV表格#

使用CSV编写

.. csv-table:: Frozen Delights!
    :header: "Treat", "Quantity", "Description"
    :widths: 15, 10, 30

    "Albatross", 2.99, "On a stick!"
    "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
    crunchy, now would it?"
    "Gannet Ripple", 1.99, "On a stick!"

效果：

表 3.9.2 Frozen Delights!#

Treat

Quantity

Description

Albatross

2.99

On a stick!

Crunchy Frog

1.49

If we took the bones out, it wouldn't be crunchy, now would it?

Gannet Ripple

1.99

On a stick!

3.9.4. 列表式表格#

语法：

.. list-table:: Frozen Delights!
    :widths: 15 10 30
    :header-rows: 1

    * - Treat
      - Quantity
      - Description
    * - Albatross
      - 2.99
      - On a stick!
    * - Crunchy Frog
      - 1.49
      - If we took the bones out, it wouldn't be
        crunchy, now would it?
    * - Gannet Ripple
      - 1.99
      - On a stick!

效果：

表 3.9.3 Frozen Delights!#

Treat

Quantity

Description

Albatross

2.99

On a stick!

Crunchy Frog

1.49

If we took the bones out, it wouldn't be crunchy, now would it?

Gannet Ripple

1.99

On a stick!

3.9.5. 普通表格#

表格使用 == 号制作

语法示例：

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

效果：

A

B

A and B

False

False

False

True

False

False

False

True

False

True

True

True

在vscode可安装插件方便格式化表格：https://marketplace.visualstudio.com/items?itemName=shuworks.vscode-table-formatter

安装后通过Ctrl-Shift-P调用 Table: Format Current 或 Table: Format All

3.9.6. 表格引用#

示例

.. _拨码开关启动配置表:

.. table:: 拨码开关启动配置表

==== ====== ========== ==== == ===
编号 名称   NAND FLASH eMMC SD USB
==== ====== ========== ==== == ===
1    MODE0  0          0    0  1
2    MODE1  1          1    1  0
3    CFG1-4 1          0    0  X
4    CFG1-5 0          1    0  X
5    CFG1-6 0          1    1  X
6    CFG1-7 1          0    0  X
7    CFG2-3 0          1    0  X
8    CFG2-5 0          0    1  X
==== ====== ========== ==== == ===

引用示例 :ref:`拨码开关启动配置表` 。
自定义名称引用 :ref:`自定义名称 <拨码开关启动配置表>` 。

效果

表 3.9.4 拨码开关启动配置表#

编号

名称

NAND FLASH

eMMC

SD

USB

1

MODE0

0

0

0

1

2

MODE1

1

1

1

0

3

CFG1-4

1

0

0

X

4

CFG1-5

0

1

0

X

5

CFG1-6

0

1

1

X

6

CFG1-7

1

0

0

X

7

CFG2-3

0

1

0

X

8

CFG2-5

0

0

1

X

引用示例 拨码开关启动配置表 。 自定义名称引用 ref自定义名称 。 自定义名称引用 表 3.9.4 。

目录