# 模板页：带标注的插图

> 在图上放文字的插图：资源锚点上的标注，插图自己的替代文本、题注和注释，标注的排法，离开所指之点、用引线连回的标注，图例和行内符号，以及标注的警告

- HTML版本: https://postext.dev/zh/docs/composed-pages-figures
- 最后更新: 2026-10-20
- 阅读时间: 6分钟
- 其他语言: [en](https://postext.dev/en/docs/composed-pages-figures.md), [es](https://postext.dev/es/docs/composed-pages-figures.md), [ca](https://postext.dev/ca/docs/composed-pages-figures.md), [de](https://postext.dev/de/docs/composed-pages-figures.md), [fr](https://postext.dev/fr/docs/composed-pages-figures.md), [it](https://postext.dev/it/docs/composed-pages-figures.md), [pt](https://postext.dev/pt/docs/composed-pages-figures.md), [ja](https://postext.dev/ja/docs/composed-pages-figures.md), [ar](https://postext.dev/ar/docs/composed-pages-figures.md)

## 简单来说

书里的地图或示意图上常常有文字：海和城市的名字，机器的各个部件。Postext把这些文字作为文本排在图上，每种语言都可以有自己的文字。本页说明怎样在Markdown里写这些标注，每个标注怎样放置和绘制，以及名字怎样离开所指的地方，用一条线指回去。本页还介绍带符号的图例，以及标注放不下或互相碰到时的警告。

本页介绍模板页或正文中在图上放文字的插图。模板页的写法见[模板页](https://postext.dev/zh/docs/composed-pages.md)；标注样式和锚点的标注字段见[配置 › 模板页](https://postext.dev/zh/docs/configuration-composed-pages.md#标注样式)。

## 带标注的插图

```md
:::figure{resource="mapa-europa" slot="mapa"}
::label[OCÉANO ATLÁNTICO]{at="atlantico" style="mar"}
::label[**Madrid**]{at="madrid"}
::label[Mar Negro]{at="62% 48%"}
:::
```

`:::figure{resource="…"}`像`::resource`一样放置一个资源，带有题注和编号，并列出要放在图上的标注：每个标注一行`::label[文字]{…}`，行与行之间可以有空行。

- `at`指定资源的一个锚点（在图上定义一次、各语言共用的点）；没有锚点的标注，则用图片宽高的百分比直接给出一个点：`at="x% y%"`。
- `style`指定一种标注样式，优先于锚点自带的样式。
- `leader`从标注画一条线到它的锚点，`leader="none"`去掉这条线（见[引线、图例与符号](https://postext.dev/zh/docs/composed-pages-figures.md#引线图例与符号)）。
- 方括号中的文字是行内Markdown：粗体、斜体、行内标签，以及写成`:icon`的符号。

插图在正文中和在框中都能用。它的标注作为文字画在图片上，插图放到哪里，标注就跟到哪里：栏中、浮动体里、被逐级重排（为放下内容而依次尝试的步骤）旋转或缩放的框里，以及跨页上。插图缺少结束的`:::`时，第一个既不是标注也不是空行的行就结束这幅插图，并把它报告为未闭合的容器。

### 图自己的文字

资源只保存一张图片、它的锚点和一套文字，而一本书的每个版本要用自己的文字。图可以自己给出`alt`、`caption`和`note`，写在开始行的属性里，或者写成单独的行，它们在该文件的页面中取代资源里的同名字段：

```md
:::figure{resource="relieve" alt="Mapa de relieve de Varenia"}
::caption[Relieve de **Varenia**, con sus tres cordilleras]
::note[Fuente: levantamiento de 1932]
::label[Mar de Sal]{at="mar"}
:::
```

- 写成开始行的属性时，`alt`、`caption`和`note`取引号中的一小段文字。`::alt[…]`、`::caption[…]`和`::note[…]`这几种行取方括号中的文字，可以含行内Markdown，也可以用`\\`换行，和资源的题注、附注一样。同名时行优先于属性；这些行可以放在标注之间，中间允许空行。
- 图没有给出的字段仍用资源里的。空值表示不要这一项：`caption=""`去掉题注，`alt=""`把图片标为装饰性图片。
- 这些文字只在写出它们的章节里取代资源的文字：排版、各种输出的替代文字和带标签的PDF都读取它们，资源本身不变。一个资源在一章里只有一套文字，就是第一幅图的：后面引用同一资源的图若写了别的文字，页面不会显示，并给出`figureWordsShared`警告。需要自己题注的缩小副本，要另建一个指向同一图片文件的资源。和标注不同，题注不会逐字符对应到Markdown；点击题注时，`sourceAt`的处理与点击资源题注时相同。

### 标注如何排出

- **位置**：标注放在其锚点所在的点上，这个点用整张图片的比例表示，所以图片裁到安全区或缩小排出时，标注会随图一起移动。锚点的`align`决定标注的哪一侧对准该点，`verticalAlign`决定哪一条边对准该点的高度。`start`和`end`按标注自身的书写方向理解：阿拉伯文标注的`start`是它的右边。`rotate`让标注绕该点顺时针旋转任意角度，例如沿河道书写的河名、斜排的山名。
- **样式**：标注自己的`style`优先，其次是锚点的`style`，它指定一种标注样式（见“配置：模板页”）；没有样式时，标注使用正文的字体设置。光晕（halo）在字形填充之下描出轮廓；底板（`background`）填满文字周围的方框，`padding`让方框更宽。
- **能否放下**：锚点设有`width`时，标注在这个宽度内于词与词之间换行，绝不在词中断开。某个词比宽度还宽时，整个标注会缩小排出，最小到其样式的`minScale`；缩到这个比例仍放不下时，绘制时最宽的词会被截掉一部分。没有`width`时，标注只占一行，除非像题注那样用`\\`强制换行。
- **文字**：方括号中的文字是行内Markdown，按题注的方式排出：粗体、斜体、行内标签、高亮标记、交叉引用、行内公式都可以用。由几个词组成的名称是一个标注，不管各语言中词序如何：`::label[大西洋]`和`::label[ATLANTIC OCEAN]`放在同一个锚点上。从右向左的标注按从右向左排出；中文和日文标注在字与字之间换行。
- **输出**：画布、PDF、HTML阅读器、固定版式EPUB和Folio都会画出标注。在从右向左的页面上，标注仍留在图片显示它的位置。
- **竖排**：在锚点（或其标注样式）上设置`writingMode: 'vertical-rl'`后，标注按竖排页面的方式排出：字符直立，一格一格自上而下，各列从右向左；拉丁文单词和长数字横倒着排，短数字合在一格里。这时`width`是占图片高度的比例，即一列的长度，中文或日文标注会排成更多列。`align`沿列的方向（`start`是列的上端），`verticalAlign`横跨各列（`top`是第一列，即最右一列），`rotate`再继续旋转标注。在从右向左书籍的镜像页上，标注同样自上而下读、字符直立，落在图片上的同一位置（自postext 1.40起）。
- **检查**：标注缩到其样式的`minScale`仍比宽度更宽时，会给出`labelOverflow`；两个标注的文字行相碰时，较后的那个给出`labelOverlap`。两项都在每个版本中分别检查，所以词更长的译文能显示出它需要更多空间的地方。篇的调色板（`:::part{palette="…"}`）会像给题注重新上色那样，给该篇各页的标注重新上色。对比度检查拿标注与它的底板比较，没有底板就与光晕比较；直接放在图片上的标注不检查，因为它的底色就是图片。印前检查也会检查标注中用多种油墨叠印的小字、标注的墨量，以及它与裁切线的距离。
- **在跨页上**：跨过跨页书脊的插图（带`crossGutter: true`的框）在两页上各画一半；标注若伸进订口带，会被折缝截断，两页上都读不全。这样的标注会横向滑到订口带的边缘，停在锚点所在的那一侧，高度不变；恰好落在书脊上的点归第一页，和框一样。设了`gutter: 'cross'`的锚点留在原处，适合横跨两页的标题。纸面的外侧边缘不做调整：超出裁切线的标注和图片一样被裁掉。自postext 1.43起。

### 引线、图例与符号

自postext 1.48起，标注可以离开它所指的东西，可以作为地图的图例，标注、题注和表格单元格里还可以放符号。

**引线。** 锚点的`labelAt`让它的标注离开所指的点（海上的一个地名，示意图页边的一条说明），引线则从标注画一条线回到那个点。引线的外观是标注样式的`leader`（见[配置 › 标注样式](https://postext.dev/zh/docs/configuration-composed-pages.md#标注样式)）；Markdown只为某一个标注打开或关闭它：

```md
:::figure{resource="relieve" slot="mapa"}
::label[Sierra Alta]{at="peaks" leader}
::label[Lago Verde]{at="lake" leader="none"}
:::
```

`leader`取`none`、`false`或`off`以外的任何值都会打开引线；没有这个属性时由锚点的`leader`决定；两者都没有时，离开所指之点的标注只要其样式有`leader`，就会画出引线。框里的说明也可以指向图上的某个地方：用一条[连接线](https://postext.dev/zh/docs/configuration-composed-pages.md#连接线)，让它的一端指定图片的锚点（`anchor: 'lake'`）。

**多行标注。** 在`:::figure`里，`:::label{at="…" style="…"}` … `:::`逐行写一个标注：源码中每个非空行都是标注的一行，所以图例或地址不必在每行末尾写`\\`。第一个`:::`结束标注，下一个结束插图。`::label[…]`仍是单行标注，只在写了`\\`的地方换行。

**图例。** 样式设了`kind: 'legend'`的标注是地图的图例：每一行是一个条目，条目开头的符号排在一列里，这一列和最宽的符号一样宽，所以各条目的文字从同一条边开始。每行先写符号：

```md
:::figure{resource="mapa-politico" slot="mapa"}
:::label{at="key" style="key"}
:icon[国家]{glyph="■" color="country"} 国家
:icon[首都]{glyph="⊙" font="Noto Sans Math"} 首都
:icon[城镇]{resource="town-mark" size="0.55"} 城镇
:icon[边界]{line="dashed" color="border"} 边界
:::
::label[:icon[首都]{glyph="⊙" font="Noto Sans Math"} Varena]{at="capital"}
:::
```

**符号。** `:icon[alt]{…}`在行内放一个小符号，立在基线上：

| 属性 | 作用 |
| --- | --- |
| `resource="…"` | 一个位图或SVG资源，保持原有比例。 |
| `glyph="…"` | 一个字符，用文字的字体，或用`font="…"`指定的字体。 |
| `line="solid\|dashed\|dotted"` | 一段线条样本，长是高的两倍：图例里的边界或道路。 |
| `color="…"` | 十六进制颜色或调色板条目：字形、线条或图片的色调。 |
| `size="…"` | 符号的高度，以文字的em为单位。默认`0.75`，即大写字母的高度。 |

`resource`、`glyph`和`line`中先写的那个决定符号的种类；三者都没有时，这条指令仍是文字。方括号中的文字是符号的替代文本：读屏软件、带标签的PDF和图片的替代文本都在符号的位置上读出它，方括号为空的符号是装饰。图的标注和资源的每一段文字（题注、附注和表格单元格）都会读取符号。在这一版本中，正文、标题和设计文字不读取符号。

### labelAnchorUnknown

某个`::label`用`at`指向了其插图资源中不存在的锚点。这个标注不会画出；流式EPUB仍会列出它，图片的替代文字也会提到它。警告带有资源、锚点、资源已有的锚点（`known`）、语言、页码以及标注文字的源码范围。请修改锚点id，在资源中添加该锚点，或用`at="x% y%"`指定位置。

在沙盒的检查面板中，点击这条警告会跳到正文面板中的这个标注；它的图钉按钮会打开图片的锚点，并预先填好这个名称，等你放置：在图上点击一次即可添加锚点。

### anchorUnlabelled

插图资源的某个锚点设置了标注样式，但插图在当前语言中没有任何`::label`放在这个锚点上：地图为一个词留了位置，这一版本却没有写。这是提示；`postext check`把它列为`info`。没有样式的锚点（例如漫画角色的锚点）不会报告。警告带有资源、锚点、其样式、语言、页码以及插图的源码范围。请在该语言的Markdown中写上标注，或者删除锚点上的样式。

在检查面板中，它会转到正文面板中的插图；它的图钉按钮会打开图片的锚点并选中这个锚点。

### labelOverflow

标注缩小到其样式允许的最小比例（`minScale`）后，仍然比锚点的`width`更宽：它按这个比例绘制，并超出自己的宽度。警告包含资源、标注文字、它的锚点（用百分比定位的标注没有锚点）、给定的宽度、达到的比例、语言、页码以及标注文字在源文件中的范围。每个版本分别检查，所以可能一种语言放得下，词更长的另一种语言却放不下。请加宽锚点的`width`，在这一版本的Markdown中缩短该词，或调低标注样式的`minScale`。中文或日文标注会在字与字之间换行，不会这样超出。自postext 1.39起。

### labelOverlap

同一幅图的两个标注，文字行相互碰到；带底板的标注按它的底板计算。警告出现在按书写顺序靠后的那个标注上，同时给出它碰到的第一个靠前标注的文字，以及它总共碰到多少个靠前的标注。检测用的是每一行各自的方框（随标注一起旋转），所以短行旁边的空白仍算空着；两行相互侵入不超过行高的八分之一时不算碰到。每个版本分别检查。请移动其中一个锚点，减小某个标注的`width`让它换行，或在这一版本的Markdown中缩短文字。在沙盒的检查面板中，图钉按钮会打开该图片的锚点，并定位到这个标注的锚点。自postext 1.39起。如果原书里某个标注本来就印得紧挨着旁边的标注（例如密集的地图），在锚点上或它的标注样式中写`overlap: 'allow'`，它就不再参与检查，包含它的任何一对都不会报告。自postext 1.42起。图片的`avoid`区域代表地图上的符号：它们是在图片标记的**避让区**模式下画在点和图标上的矩形，以占图片的比例表示。标注压到其中一个，同样会报告，只是把被压的对象写成`symbol 2`而不是某个标注（数据里是`withSymbol`）；`overlap: 'allow'`让一个标注同时不参与这两项检查。自postext 1.42起。

### figureWordsShared

某幅`:::figure`为一个资源写了文字（`alt`、`caption`或`note`），而同一章中前面的图已经给过这个资源文字，两者又不同。页面显示第一幅图的文字，后面这些被略去。警告里有资源、被略去的文字，以及其中第一处的源码范围；后面的图如果没写自己的文字，则不算问题。请给这幅图单独建一个资源：另一个指向同一图片文件的资源，有自己的题注、编号和锚点。在沙盒的检查面板中，它归在“图与表”一组。自postext 1.42起。