配置：页眉与页脚

#页眉与页脚

header和footer属性控制每一页的页眉和页脚槽位。页眉和页脚渲染在现有的页边距之内：它们不另外占用空间，也不会缩小内容区。

容器框。 锚定到'container'的元素放在正文与裁切边之间的页边带里，宽度等于内容区的宽度。页眉容器从裁切上边一直延伸到正文顶部；页脚容器从正文底部一直延伸到裁切下边。因此，页眉的top-*锚点和页脚的bottom-*锚点从裁切边量起，而页眉的bottom-*锚点和页脚的top-*锚点从正文边缘量起。容器从不包含出血区或裁切标记带，所以无论page.cutLines开还是关，页眉或页脚在裁切后的页面上都落在同一位置。要超出内容区的宽度或伸进出血区，就锚定到'page'（裁切框）或'bleed'。

槽位使用统一的设计槽位模型：每个元素都有一个placement，其中包含一个anchor（锚定到容器，或通过#id锚定到另一个元素）、一个可选的offset和一个可选的size。旧版的平铺字段align、marginFromBody、marginFromEdge和width: 'full'在输入时仍然接受，并会自动迁移成新的结构；对应的新结构写法见下文。

每个槽位保存一组文本、线条和方框元素。数组顺序就是绘制顺序（第一个元素最先绘制，最后一个元素画在最上层）。无论锚点怎么写，这一点都成立：元素可以锚定到排在它后面的元素（anchor.to: '#ttl'），所以背景方框可以排在最前面，同时仍按它衬在其后的文本来定位。

内置默认值。 当header或footer为undefined时，postext会使用一套合理的内置默认设置，而不是留一个空槽位：

• 默认页眉： 奇数页右对齐显示{title}，偶数页左对齐显示{chapterTitle}，另加一条通宽线条；全部使用调色板的主色，Open Sans 8pt/600，marginFromBody为16pt（文本）/13pt（线条）。
• 默认页脚： 每页居中显示{pageNumber}，使用调色板的主色，Open Sans 8pt/600，marginFromBody为16pt。

要关闭内置默认值，设置header: { elements: [] }（或footer: { elements: [] }）。显式的空elements数组会保留为“没有元素”；只有undefined才会触发默认值。

#文本元素

文本元素渲染一个模板字符串，并替换其中的占位符。占位符使用{name}语法；{{和}}输出字面的花括号。

下表中的默认值是你自己添加的文本元素的默认值。上文内置默认值中介绍的内置页眉和页脚是现成的元素，带有各自的取值（调色板主色的Open Sans 8pt/600），并非元素的默认值。

可用的占位符：

• {pageNumber}：当前页从1开始的页码。
• {totalPages}：文档的总页数。在逐章排版的书中（沙盒、buildBundle），每一章都是一个文档，所以这是该章自己的页数。
• {bookTotalPages}：整本书的总页数：所有章，包括空白页。对单独排版的文档，它等于{totalPages}。见下文全书页数。
• {title}、{subtitle}、{author}、{publishDate}：从content.metadata读取的值。未知或为空的元数据渲染为空字符串（并在沙盒中发出警告）。
• {chapterTitle}：当前页或之前最近一个H1的文本。标题样式设了runningChapter: false的H1（插图页、地图）会被跳过。
• {chapterTitleAtTop}、{chapterNumberAtTop}：页面顶部所属章的标题和编号；在新章从页面中部其他文本之后开始的页上，它们与{chapterTitle}和{chapterNumber}不同。见下文页面顶部所属的章。
• {partTitle}、{partNumber}：当前篇的标题和编号（当前页或之前最近的:::part页；紧挨在篇页之前为奇偶补的空白页已属于该篇）。第一篇之前为空。
• {firstMark.<key>}、{lastMark.<key>}：页面的第一个和最后一个检索词：某一级标题（h1–h6），或某个段落样式的词条。见下文检索词：首标记与尾标记。

全书页数

{bookTotalPages}输出整本书的页数，也就是读者在“第12页，共348页”里看到的那个数。它和{totalPages}一样统计实际页数，包括空白页，但覆盖所有章：

• 单独排版的文档（不带continuation的buildDocument）就是整本书：{bookTotalPages}等于{totalPages}。
• buildBundle先排整本书，把所有章的页数加起来，再用这个总数重新排一遍，所以每一章输出的数字都相同。这个数从不改变分页位置，所以多排一轮就能定下来；不输出{bookTotalPages}的配置不会多花任何代价。
• 沙盒在所有章的页数都已知之后，把总数交给每一章。在此之前，一章输出的是到它自己结尾为止的页数。PDF标签页的整书导出统计它排出的页数：如果某一章因为当时页数尚未确定而输出了别的数字，它会用各章最终合计的页数把书再排一遍。
• 自行逐章排版的宿主程序把总数作为continuation.bookPageCount传入（第一章也要传）。不传时，{bookTotalPages}统计到文档结尾为止的页数（continuation.pageIndexOffset加上自身的页数），这只对最后一章是正确的。

footer: {
  elements: [{
    kind: 'text', id: 'folio', content: '{pageNumber} / {bookTotalPages}',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'top' }, size: { width: 'auto', height: 'auto' } },
  }],
}

configUsesPlaceholder(config, 'bookTotalPages')告诉宿主程序是否值得计算这个总数。

检索词：首标记与尾标记

词典在书眉里印出每页的第一个和最后一个词目（“Aback – Anchor”）；参考书印出第一个和最后一个小节。{firstMark.<key>}和{lastMark.<key>}用来输出它们。键名指定用什么来标记页面：

• h1到h6：该级的标题。标记是标题的文本，不含编号。
• 段落样式id（entry）：:::paragraphs{style="entry"}容器中的段落。标记是段落开头的粗体部分，即词目，去掉末尾的标点：**Aback.** Said of…的标记是Aback。不以粗体文本开头的段落不产生标记。

{firstMark.<key>}是在本页开始的第一个标记，{lastMark.<key>}是最后一个。没有任何标记在其上开始的页（一个很长的词条接排过来），两者都输出当时生效的标记，即它之前的最后一个。第一个标记之前的页不输出任何内容；在逐章排版的书中，这指的是该章的第一个标记，因为标记不会从一章带到下一章。跨页拆开的标题或段落只标记它开始的那一页。键名写在点号之后，由字母、数字、_和-组成，以字母或_开头；未知的键名不输出任何内容。

:::paragraphs{style="entry"}
**Aback.** Said of the sails when pressed back against the mast.
 
**Abaft.** Towards the stern, or behind a given point.
:::

header: {
  elements: [{
    kind: 'text', id: 'guide', content: '{firstMark.entry} – {lastMark.entry}',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'bottom' }, size: { width: 'auto', height: 'auto' } },
  }],
}

检索词属于书眉：它们在页眉和页脚槽位中解析（包括标题样式的header和footer），在标题、篇和目录的设计中不输出任何内容；在标题和篇的设计中，检查面板会把它们标为未知占位符。要在左页显示第一个词目、右页显示最后一个，就用两个元素，分别设parity: 'even'和parity: 'odd'。标题样式设了runningChapter: false的H1不产生h1标记。

页面顶部所属的章

{chapterTitle}和{chapterNumber}指向本页或之前最后开始的一章。在各章接排、章与章之间不分页的书中，如果一页结束了一章，又在靠近页脚处开始下一章，这一页就会在仍属于旧章的文本上方印出新章的标题。{chapterTitleAtTop}和{chapterNumberAtTop}改为指向页面顶部所属的章，章节接排的小说和许多参考书都是这样做的：

• 第一个块是某章H1的页，指向该章；
• 其他页指向从上一页接排过来的章，即使有新章在页面下方开始；
• 为奇偶补的空白页归属于它后面的页，always-*模式的分隔页归属于它前面的页（见空白页的归属）；如果奇偶补页后面那一页以一章的结尾开头，而不是以它的H1开头，这张空白页也归属于那一章；
• 带runningChapter: false的H1会被跳过。

header: {
  elements: [{
    kind: 'text', id: 'chapter', content: '{chapterTitleAtTop}', parity: 'odd', pages: 'body',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'bottom-right' }, size: { width: 'auto', height: 'auto' } },
  }],
}

和检索词一样，这两个占位符都属于书眉：它们在页眉和页脚槽位中解析，在标题、篇和目录的设计中不输出任何内容。{attr.<key>}始终读取最后开始的一章。

由锚点边隐含的对齐方式

当文本元素的placement.anchor.to通过#id引用另一个元素时，锚点边会为折行后的各行隐含一个默认的文本对齐方式：

• right-of和align-left隐含文本align: 'left'：折行从锚点向右排。
• left-of和align-right隐含align: 'right'：折行贴向离锚定目标最近的一侧。

沙盒的标题编辑器在你更改锚点边或目标时会自动应用这些隐含的对齐方式。它们让折成多行的文本在视觉上始终锚定在相关的元素上（例如折行后“Postext”的“P”与“Introduction”的“I”上下对齐）。

行内标记与描边

文本元素默认用一种字体排出全部文本：**、^及其他Markdown标记按原样输出。设inlineMarks: true后，解析后的文本会被当作行内Markdown读取，支持与正文相同的标记（见文档格式 → 行内格式）：

• **bold**设为字重700（元素自身的fontWeight更重时取后者）；*italic*翻转元素的倾斜状态，所以斜体元素中的强调会变成正体；***both***两者兼有。下划线形式（__bold__、_italic_）也可以用。
• ^superscript^和~subscript~以58%的字号排出，上标升高字号的三分之一，下标降低字号的0.15；紧挨在一起的下标和上标（T~0~^2^）会上下叠排，与正文相同。
• 反斜杠让标记字符按字面输出（\*、\_、\^、\~）。链接保留其文本；代码的反引号会被去掉。

标记在占位符填入之后读取，所以值本身可以带标记：标题属性中的作者行可以把单位编号排成上标。折行、两端对齐、省略号模式、dropCap和paragraphIndent都适用于带标记的文本；每一段文字都保持元素的颜色。

{ "kind": "text", "id": "authors", "content": "{attr.authors}", "inlineMarks": true, "overflow": "wrap",
  "fontSize": { "value": 11, "unit": "pt" },
  "placement": { "anchor": { "to": "#title", "edge": "below" }, "offset": { "y": { "value": 6, "unit": "pt" } } } }

# Snow cover and river flow {authors="Ana Ruiz^1^, Luis Gil^2^ and Marta Sanz^1,3^"}

stroke围绕字母绘制描边：width是线宽，以字形边缘为中心（一半落在字母内侧，一半在外侧；测得的文本宽度不变），color默认取文本颜色，hollow: true让字母不填充，只显示描边，适合空心的展示数字，或需要从照片上突显出来的标题。描边画在填充之上，在Canvas、HTML（-webkit-text-stroke）和PDF（文本渲染模式2，空心时为1）中的做法相同。

{ "kind": "text", "id": "year", "content": "1863", "fontFamily": "Bitter", "fontSize": { "value": 120, "unit": "pt" }, "fontWeight": 700,
  "color": { "hex": "#1d3557", "model": "hex" },
  "stroke": { "width": { "value": 1.5, "unit": "pt" }, "hollow": true },
  "placement": { "anchor": { "to": "page", "edge": "bottom-right" }, "offset": { "x": { "value": -15, "unit": "mm" }, "y": { "value": -20, "unit": "mm" } } } }

在PDF中，粗体和斜体部分会嵌入元素字体族中对应的字面，所以字体提供程序必须提供这些字面。

文本默认值与锚定陷阱

你自己写的文本元素从以下取值开始，其中有些会出乎意料：

• overflow取决于所在位置。 在标题版式或篇章页中，长标题会折成多行；在书眉、页码或目录的篇行中，对所在空间来说太宽的文本会被截成一行并加上…。可能较长的书眉（地址、署名）要设overflow: 'wrap'，并查看被截断文字的designTextTruncated警告。内容中的换行（换行符，或模板、属性值中的\n）在所有模式下都会另起一行；省略号模式各自截断每一行。
• align为'center'，verticalAlign为'middle'。 自动宽度的元素收缩到最长的一行，所以各行彼此居中；要排成齐左的一块，设align: 'left'（锚定到另一个元素的自动宽度元素会自行向锚点一侧对齐各行，见上文）。
• 字体为EB Garamond 8 pt、黑色、lineHeight 1.2，与正文用什么字体无关。与配置中的其他行距不同，设计文本的lineHeight通常写成一个简单的倍数（1.2）；Dimension也可以（见上文）。

没有placement.size.width（或为'auto'）的元素按文本确定自身大小，但只能在锚点与它延伸方向上的容器边缘之间的空间内伸展；对top或bottom锚点，这个空间是到较近边缘距离的两倍。offset也计算在内。背离那条边的偏移不占空间：锚定在top-left、x为负值（悬挂到左页边距中）的书眉不损失空间，因为它向右延伸。朝向那条边的偏移会让空间缩小同样的量（对top或bottom锚点缩小两倍），而把锚点推过边缘的偏移则让空间归零：x小于容器宽度负值的top-right锚点，或横向移动超过容器宽度一半的top锚点。空间归零时，省略号模式什么也不输出，'wrap'则每行只排一个字符。有三种解决办法：

• 给元素一个固定的size.width：固定宽度从不受限制；
• 把它锚定到'page'或'bleed'，让页面（或出血区）框定它的空间；
• 把它锚定到容器的另一侧边缘。

页眉的容器从裁切上边一直延伸到正文，页脚的容器从正文一直延伸到裁切下边：在页眉中，top-*锚点从裁切边量起，bottom-*锚点从正文量起，页脚中则相反（见上文容器框）。页眉或页脚从不移动正文，并且画在正文之上，所以被推进正文区域的元素会盖住文本。相比之下，章首页的色带画在正文之下；它在文本流中占多少空间见预留高度。

#竖排文本元素

设了writingMode: 'vertical-rl'的文本元素在文本为横排的槽位中竖排：任何书的书眉和页码（它们始终在书页上）以及横排页面的所有设计都是如此。它的排法是：在自身的框里按横排文本排好（这个框顺时针转了四分之一圈），再转回到页面上：

• 它的方框留在定位所给的位置。方框的高度就是一行的长度：由size.height设定（或'auto'，即文本的长度；'fill'，一直延伸到容器边缘），size.width决定横向能排几行，size.maxWidth限制一行的最大长度。
• align沿方框方向放置各行（'left'在顶部），verticalAlign在横向放置（'top'在右侧，即第一行所在的位置），方框的内边距留在它所写明的那一侧。
• 字符的测量和绘制与竖排页面相同：汉字直立，每字占一个全角，标点用竖排字形，拉丁词侧转，短数字排在一格内（cjk.uprightDigits）。Canvas、PDF和HTML把它放在同一个矩形中。
• 设inlineMarks: true时，方向标记像在正文中一样把一段文字单独处理：第:tcy[3.0]回把3.0排在一格内，:upright[GDP]把字母逐个直立上下排列，:sideways[…]把一段文字侧转；这些片段内部从不断行。横排元素忽略这些标记。
• 竖排元素不排首字下沉。
• 在竖排页面的文本流中（章首页、篇页、方框标题），文本本来就是竖排的，writingMode在那里不起作用。

竖排中文书把书眉和页码放在以下三种位置之一（clreq §7.2；日文见JLREQ §2.6）：

下面是沙盒添加的切口书眉（页眉 › 切口书眉（竖排）），这里按10 pt正文设置（沙盒把它们设为正文字号的80 %）：

{
  "page": { "pageNumbering": { "format": "trad-chinese-informal" } },
  "header": { "elements": [
    { "kind": "text", "id": "head", "content": "{chapterTitle}", "writingMode": "vertical-rl",
      "fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
      "placement": { "anchor": { "to": "outer", "edge": "top" }, "offset": { "y": { "value": 4, "unit": "em" } } } },
    { "kind": "text", "id": "folio", "content": "{pageNumber}", "writingMode": "vertical-rl",
      "fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
      "placement": { "anchor": { "to": "outer", "edge": "bottom" }, "offset": { "y": { "value": -5, "unit": "em" } } } }
  ] }
}

anchor.to: 'outer'（见元素定位）是每一页的外侧页边距，所以在右翻书（page.binding）中，这两个元素沿右页的左边缘和左页的右边缘竖排。{pageNumber}按页码格式输出：trad-chinese-informal在第103页给出一百零三，cjk-decimal给出一〇三。各槽位的规则照样适用：pages: 'body'让书眉不出现在章首页上。书眉和页码之间的短装饰（鱼尾︻、一条线）是锚定到同一框的普通元素。

在VDT中，竖排块带有vertical（VDTDesignTextBlock.vertical：区域、直立数字和每个字体族的中轴）；它的各行位于块自身旋转后的框中，xOffset从方框顶部向下量，baselineY从方框右边缘向左量。带标记的行中的一段文字带有tcy或orientation，与正文的片段相同。

#线条元素

线条元素渲染一条线：横贯槽位，或纵贯槽位。

#方框元素

方框元素在槽位内绘制一个圆角矩形，可用作章首页、侧栏或页脚中文本的背景。方框元素只通过placement字段定位，没有旧版的平铺简写。填充、描边和圆角半径放在嵌套的style对象（ElementBoxStyle）中，如“元素定位”下的JSON示例所示。

#图像元素

image元素绘制文档中的一个位图或SVG资源，例如扉页上的出版社标志，或书眉中的一个标记。它的大小由placement.size决定：width / height中有一边保留为'auto'（默认值）时，另一边按图像的宽高比确定；两边都设定时，图像在方框内等比缩放并居中。缺失的资源或非图像资源不绘制任何内容。

{
  kind: 'image', id: 'logo', resourceId: 'logo-publisher',
  placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 64, unit: 'mm' }, y: { value: 233, unit: 'mm' } }, size: { width: { value: 83, unit: 'mm' }, height: 'auto' } },
}

resourceId接受文本元素content所接受的占位符，所以同一个设计可以为每个标题绘制不同的图片。在标题样式中设resourceId: '{attr.vignette}'后，# Chapter I {style="opener" vignette="log"}绘制资源log，# Chapter II {style="opener" vignette="wig"}绘制wig：各章共用同一个样式，不必每张图片克隆一个。页眉或页脚读取本页所属章的属性，与书眉中的{attr.<key>}相同；其他占位符同样可用（'map-{chapterNumber}'）。结果为空的id，例如没有该属性的标题，不绘制任何内容。自postext 1.8起提供。

PDF后端像嵌入图一样嵌入该资源（带印刷母版的SVG会使用母版）；HTML查看器通过resourceImageUrl解析它。

设计所绘制的图片，在其资源对它有描述时属于内容：资源的altText，没有时取其题注的纯文本（行内标签按其标签文字读，:ref有text时按text读），会写入VDT（VDTDesignImageBlock.altText），在HTML中成为其<img>的alt，在带标签的PDF中成为带/Alt的Figure，紧接在所属设计的文本之后读出（章的插图页紧接在该章标题之后）。资源两者都没有的图片，以及标为decorative的图片，属于装饰：HTML中为alt=""加role="presentation"，PDF中为artifact。书眉或页脚中的图片每页重复出现，所以无论资源怎么描述都属于版面附属物：VDT中没有altText，HTML中为alt=""加role="presentation"，PDF中为页面的artifact。

#元素定位

ElementPlacement是统一的定位模型，任何设计槽位（页眉、页脚或标题级的高级设计槽位）中的每种元素类型（文本、线条、方框）都使用它。一个定位由三部分状态描述：

interface ElementPlacement {
  /** 该元素锚定到什么，以及锚定到目标的哪条边。 */
  anchor: {
    to: 'container' | 'page' | 'bleed' | 'outer' | `#${string}`; // container = 槽位；page = 裁切框；bleed = 裁切框 + 出血；outer = 外侧页边距（页眉、页脚）；#id = 另一个元素
    edge: AnchorEdge;
  };
  /** 距锚点的距离。 */
  offset?: { x?: Dimension; y?: Dimension };
  /** 可选的固定宽度 / 高度。宽度还接受 'fill'（横跨槽位）。
   *  `maxWidth` 限制 'auto' 宽度（文本）的上限：元素仍收缩贴合其内容，
   *  所以锚定到它的元素保持相连，但长文本会在此处折行或加省略号，
   *  这样书眉可以为挂在它旁边的标签预留空间，而不会把标签挤掉。 */
  size?: { width?: Dimension | 'fill' | 'auto'; height?: Dimension | 'fill' | 'auto'; maxWidth?: Dimension };
}

AnchorEdge接受：

• 容器边（anchor.to为'container'、'page'或'bleed'时）：top、top-left、top-right、bottom、bottom-left、bottom-right、left、right。
• 相对元素的边（anchor.to === '#someId'时）：right-of、left-of、below、above、align-top、align-bottom、align-left、align-right。

每种相对元素的边都把本元素的一个角放在所锚定元素的一个角上，再由offset从那里移动：

• right-of：本元素左上角放在目标右上角（在目标旁边，顶部齐平）；left-of：本元素右上角放在目标左上角；
• below：本元素左上角放在目标左下角（在目标下方，左边齐平）；above：本元素左下角放在目标左上角；
• align-top和align-left：本元素左上角放在目标左上角。这两个名字给出相同的定位：顶边和左边都对齐；
• align-bottom：本元素左下角放在目标左下角；
• align-right：本元素右上角放在目标右上角。

相对元素的边与'container'、'page'或'bleed'一起使用，或容器边与'#id'一起使用时，都按左上角处理。

anchor.to: 'page'把元素锚定到裁切框（裁切后的实际页面），'bleed'则锚定到四边各扩出cutLines.bleed的裁切框（关闭裁切线时与裁切框相同）。这两个框也成为size: 'fill'和自动宽度限制的参照，所以色带可以不受页边距影响，从一边延伸到另一边：

{ "kind": "box", "id": "band", "placement": { "anchor": { "to": "bleed", "edge": "top-left" }, "size": { "width": "fill", "height": { "value": 6, "unit": "cm" } } }, "style": { "backgroundColor": { "hex": "#1d3557", "model": "hex" } } }

开启裁切线时，元素画出出血框之外的部分都会被裁掉（见裁切线）。

anchor.to: 'outer'（页眉和页脚槽位）把元素锚定到页面的外侧页边距：横向从版心边缘到远离书脊一侧的裁切边，纵向从版心顶端到底端。在左翻书中，它位于右页的右侧和左页的左侧，右翻书则相反（page.binding），所以一个元素就能同时服务跨页的两页：例如沿切口竖排的书眉（见竖排文本元素）。在其他槽位中，它按'container'处理。文本元素的offset可以用em表示，即它自身fontSize的em：版心顶端往下四个字就是{ "y": { "value": 4, "unit": "em" } }。

在标题的高级设计槽位中，锚定到页面和出血区的元素不会增加为标题预留的高度，除非它们延伸到标题顶边以下（横跨页面顶部的色带衬在章首页后面；延伸到标题以下的色带会把正文往下推）。用advancedDesign.minHeight可以无论如何都预留一个固定的章首页高度，对不应推动文本的元素则设reserve: false。完整规则见预留高度。

每个元素都有一个稳定的id（由沙盒自动分配；你也可以手动设置）。锚定到其他元素的元素构成一个小型依赖图，引擎在测量前解析它，所以一个元素可以接在另一个元素后面定位，无须手动指定坐标。

旧版的align + marginFromBody + marginFromEdge结构在输入时解析，并在解析配置时改写为定位，所以已有的配置无须改动即可继续使用。