模板页：带标注的插图

本页介绍模板页或正文中在图上放文字的插图。模板页的写法见模板页；标注样式和锚点的标注字段见配置 › 模板页。

#带标注的插图

:::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"去掉这条线（见引线、图例与符号）。
• 方括号中的文字是行内Markdown：粗体、斜体、行内标签，以及写成:icon的符号。

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

#图自己的文字

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

:::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（见配置 › 标注样式）；Markdown只为某一个标注打开或关闭它：

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

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

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

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

:::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、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起。