配置：标注框

#标注框样式

calloutStyles属性声明一组具名的框样式，文档用:::callout{type="…"}容器来套用：注释、提示、警告、学习目标，以及任何需要用底色框或描边框与正文区分开的内容。默认只带一种中性样式note（浅灰底色，无边框、无色条、无图标、无标题），所以不做任何配置也能使用:::callout；一旦声明calloutStyles，就会替换这份默认列表。

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#:::callout容器

:::callout{type="<id>"}一行打开框，单独一行:::关闭它。围栏接受五个属性：type（样式id）、title（覆盖样式的标题）、span、placement和columns（覆盖样式中的值）；两者之间的内容排在框内：先是可选的标题，然后是段落、列表、引文块、公式或资源嵌入，各自按样式的body / lists排版（标题保留它们平常的样式）。子块之间的外边距像正文中一样合并；框内部脱离基线网格，框之后文字流回到网格上，框下方至少留出marginBottom（以网格为准，外边距是最小值，资源遵循的也是这一约定）。snapToGrid: false的样式则保持精确的marginBottom，框之后的正文一直偏离网格，直到下一个标题或列表结尾。紧挨在标注框之前的标题与框保持同栏。

本版本的限制：

• 标注框保持完整，除非其样式设置了keepTogether: false。栏中剩余空间放不下时，它整个移到下一栏或下一页；一个被浮动区带或区带上限截短的空栏，只要完整的一栏能容纳它，框也会从中移出。比一整栏还高的框改为拆分，与可拆分的框一样；只有任何切口都拆不开的框（比栏还高的图或表，或没有切口能满足的splitMinLines）才会照排并溢出；此时版面记录一条calloutOverflow警告（VDTDocument.warnings），沙盒会列出它。:::columns组像它外面的框一样切开，切口落在子栏之间（自postext 1.25起）；只有设置了layout.flowColumns: false或位于嵌套框内时，它才保持完整，并可能以同样的方式溢出。可拆分的框留下能放下的部分，即完整的子块，或段落的若干行，每侧不少于splitMinLines行（单独一个图、表或独立公式就足以构成一侧），然后在下一栏或下一页的一个不带图标的框中继续，除非样式重复标题，否则也不带标题，还可以在它留下的部分下方加一个标记（见拆分框的标记）。
• 浮动体让位于不可拆分的框。当图的引用之后紧接的块是keepTogether标注框时，如果某个位置会让这个框在当前栏带中无栏可落（引用所在的栏，或它之后的空栏，在浮动之前本可容纳它），就不采用这个位置：图移到它的下一个位置，通常是下一页，框留在文字流中。这正是排版工人的做法：不会把框挤出页面，只在栏里留下那张图。
• 在多栏版式中，span: 'page'让框成为通栏块：它按整个版心宽度排布，把页面切分成栏带。它上方的各栏文字在切线处结束，框自己占一个通栏宽的栏，下方新开一组文字栏，文字流在每一栏中都从框下继续。在各栏平齐的地方，即页面顶端、span: 'page'的章首标题正下方、另一个通栏块正下方，或顶部浮动区带正下方，框直接在那里切开。如果它在页面中部出现、各栏参差不齐，就按排版工人的方式处理：它上方的正文在所有栏中齐平切断（引擎把该栏带的各栏缩短到相同的网格行数后重新排布，于是文字自然地从一栏流向下一栏，所有段首孤行、段末孤行和与下文同栏的规则照样生效），框横跨整页，各栏在它下方继续。切断要多跑几遍排布；如果切线下方放不下框加上段首孤行（widow）规则所需的最少正文行数，或者尝试几次后仍没有合适的排法，框就移到下一页顶端。上方的正文遵守这条切线：一栏在图下方只剩几行、放不下一个段落的开头时，该段落移到下一栏（图于是单独占据那一栏）；当某个块仍会越过切线时，切线下移一行，而不是移到那个块结束的地方。开启栏带的拆分框也在那里切断，所以它的其余部分不会越过切线。在headings.balancing.beforeSpan（默认开启）下，框离开的栏带在它后面齐平切断，就像一章的收尾栏带；样式允许拆分时（keepTogether: false），框中能放进拉齐后各栏下方的部分结束这一页，其余部分开启下一页。设beforeSpan: false时，框离开的页面只做常规的各栏齐底，不强制分页。紧挨在通栏块之前的标题不随它移动。在单栏版式中，span: 'page'就是普通的行内排布。
• placement: 'fixed'把框移出文字流：先排出框（width: 'auto'按标题收缩宽度；'fill'取锚点下方那一栏的文字宽度），再把它固定在它在文字流中所在的页面上，位置由fixed.anchor / fixed.offset描述，默认为内容区的左下角。它覆盖的文字栏让出这块区域（从底部截去，栏仍为空时从顶部截去），与浮动区带完全相同；如果这块区域中已经有正文、浮动体或通栏块，框就移到下一页。收尾一章的固定框（下一个块是章首页、:::part、浮动体屏障框或文档末尾）会先把它上方的各栏拉齐（headings.balancing.trailing），这样较短的收尾页会齐底结束，下方是徽标。框形和子块放在page.floats中，在所有后端中都在栏的裁切区之外渲染。
• placement: 'top' | 'bottom'让框像资源一样浮动：它在出现处离开文字流，占用该处之后第一个空闲区带，即当前页的页脚（'bottom'），或文字流打开的下一页的页首 / 页脚，宽度为一栏（span: 'column'）或整个版心（span: 'page'）；它之后的正文填满它离开的那一页。它的框形和子块进入page.floats，与固定框一样。位于新一页页首的浮动框排在等待该页的图之前；在较早一页引用、随后能放在它下方的图，即使剩下的正文不足三行，也会占满该页其余部分（图集页：框加图，中间没有正文）。span: 'side'框从不浮动：无论placement如何，它都叠放在正文旁边。columns大于1时（在样式中或作为围栏属性，postext 1.18起），span: 'column'框占用这么多相邻的栏：一组顶端平齐的空栏的栏首，或者当前栏及其后空栏的栏脚，例如:::callout{placement="top" columns="2"}。
• width: 'auto'只按标题收缩宽度，子内容被忽略。
• 嵌套在另一个标注框中的:::callout是一个独立的框：它按自己的样式（底色、边框、圆角、内边距、色条、标题、图标、标记、标签、排版）以父框的全部内宽排布，作为父框的一个子块叠放，其marginTop / marginBottom与相邻块合并。它的span和placement（围栏或样式中的）被忽略，嵌套框总是在父框内顺排；floatBarrier和snapToGrid同样被忽略。框可以任意层级嵌套，也可以放在:::columns组中（每个框完整地位于一栏中）。父框拆分时，切口落在嵌套框之前或之后，嵌套样式允许拆分时也可以落在它内部；每个片段都会重画它切过的框形，从上一个片段接续过来的嵌套框不带标题和图标，与顶层的接续部分一样。
• 子块中的:::columns{count=N} … :::组在框内把这些子块排成N个等宽的栏，间距为columnGap：这一串内容在最能让各栏平齐的块边界或行边界处切开（在中途切开的段落或列表项在下一栏开头继续，不带项目符号），每一栏都从组的顶部开始，组的高度等于最高的一栏；组之后的子块恢复全宽。拆分的框（keepTogether: false，或比一栏还高的框）也会在组内部、各栏之间切开：蛇形组依次填满各栏，接到下一个片段；平行组（breaks）则逐个流接续（postext 1.25起；见文档格式 › :::columns）。围栏上的gap为该组替代columnGap，rule在每条栏间空白中画一条竖线。可用来排两栏的要点小结，或让宽框中的几张表并排。
• 围栏的第六个属性label印在样式的标签上（见上文label）：:::callout{type="box" label="BOX 1-1" title="The octet rule"}；样式没有label时忽略该属性。

在VDT中，框是一个type: 'callout'的框形块，其装饰（底色、色条、图标、标题）放在designOverlay上，后面在同一栏中跟着它的子块；框形和每个子块都带有围栏的containerId。嵌套框是子块中一个独立的type: 'callout'框形，后面跟着它自己的块；这些块保留顶层围栏的containerId（排布和各栏齐底仍把它们看作一个单元），并加上calloutPath，即包围它们的各层嵌套围栏的容器id，由外到内排列（嵌套框形自己的id是最后一项）。带标签的PDF为每个嵌套框在其父框的Div内生成一个Div。图标图片与资源图片的解析方式相同：canvas图片注册表、HTML的resourceImageUrl选项和PDF的resourceBytes提供器。

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => 每个继承字段都从已解析的各节中填入；可选的
//    locale决定接续字符串的语言
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => 对内置的`note`默认值返回undefined；去掉静态默认值

#编号的命题与证明

带numbering的样式为它的框计数，就像LaTeX的amsthm为定理环境计数（postext 1.19起）。每个框印出它的标签和编号，即第一段开头的“定理2.”，围栏的title以括号跟在编号之后：:::callout{type="theorem" title="Bradley–Terry"}以“定理2（Bradley–Terry）.”开头。以标识符打开的框（{#thm:main}）可以作为交叉引用的目标，引用印出“定理2”（:ref{id="thm:main"}），\ref{thm:main}或style=number印出2。

证明就是一个标签不编号、带结束记号的样式：

calloutStyles: [
  { id: 'theorem', numbering: { label: '定理' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: '引理', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: '定义' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: '证明', counter: false, bold: false, italic: true } },
]

逐章排版的书中，计数器接着上一章继续（LayoutContinuation.statementCounters，由continuationAfter填入），全书大纲为每个编号框的锚点给出它的标签（OutlineEntry.numberLabel），所以从另一章引用时也能印出它。

#框内的排版

框用自己的body和lists排版设置内容，其余一切沿用文档的样式：

• 段落采用框的body：字体、字号、行距、颜色、强调颜色、字重、italic、smallCaps、对齐、断词、缩进和段间距。未设置的字段继承bodyText。继承来的强调颜色保留与调色板的关联，所以框内的粗体、斜体和:ref标签与框外一样随colorPalette变化。（postext 1.4及以前，无论主色是什么，框内的粗体都保持#295AA3。）
• 项目符号列表以框的lists（项目符号字符、颜色、字形大小和字重、缩进、间隔、条目间距）覆盖unorderedLists，文字是框的正文。lists.bulletChar或lists.color与文档的设置（unorderedLists）不同时，替换每一层的项目符号或颜色；与之相同或未设置时，每一层保留各自的设置（unorderedLists.levels），所以嵌套的破折号在框内依然保留。
• 编号列表采用lists.indent、gap和itemSpacing；只要样式设置了lists.color，也采用它，即使它就是文档的项目符号颜色；未设置时，编号保持orderedLists.color。（postext 1.4及以前，只有当颜色与unorderedLists.color不同时才会作用到编号上，所以设成同一种颜色不起作用。）编号本身的字体、字号和分隔符来自全局的orderedLists，因为lists只有项目符号字段：框内编号的样式请在那里设置。
• 框内的:::paragraphs使用它们的段落样式，嵌套框中也是如此。段落样式未设置的字段继承文档的bodyText，而不是框的body（也不继承框的斜体或小型大写字母）。
• :::columns组没有自己的样式：每一栏都共用框的正文和列表排版，columnGap设置栏间距。
• 引文块采用框的正文字体、字号和字重（与正文中一样为灰色斜体），以及框的小型大写字母。标题保留标题样式；独立公式保留数学设置。
• 图和表保留文档的题注和表格样式，宽度为框的内宽；它们的常规字重和粗体字重跟随框的body字重。
• 行内标签保留自己的标签样式；em字号按框的正文字号计算。
• :::space以框的正文行为单位计量（它在哪些位置被丢弃，见:::space）。
• 嵌套框完整采用自己的样式；它的span、placement、floatBarrier和snapToGrid被忽略。

#拆分框的标记

框跨栏或跨页拆分时（keepTogether: false，或框比一栏还高），第一部分之后的每一部分都不带标题和图标开始，默认也没有任何提示告诉读者框还在继续。图书或剧本常用的标记可以通过两个选项加上：

• repeatTitle: true在每个接续部分的开头重复标题，后接continuedSuffix，默认为“Key points (cont.)”。重复的标题采用标题样式，所以配合textTransform: 'uppercase'就得到剧本里的“HAMLET (CONT'D)”。图标和标签只留在第一部分。
• continuesMarkerEnabled: true在每个还要接续的部分的最后一行下方、框内，排出continuesMarker：“Continued”，西班牙语文档中为“Continúa”。它使用框的正文字体和字号：除非continuesMarkerItalic为false，否则为斜体；除非continuesMarkerAlign设为'left'或'center'，否则右对齐。标记占用它所结束的那一部分的空间，选择切口时会保证它放得下。

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

结束这一页的部分以“(MORE)”收尾，下一页以“HAMLET (CONT'D)”开始。两者都是分页附属物：在无障碍PDF中它们是artifact，在HTML中对辅助技术隐藏，所以标题只被朗读一次。在VDT中，它们是标记为artifact: true的designOverlay文本块。