配置：页面与版式

#页面

page属性控制页面的物理尺寸和外观。

#镜像页边距

书是按跨页来读的，内侧页边距通常与外侧不同。margins.mirror把四边页边距变成对页页边距：

{
  "page": {
    "margins": {
      "top": { "value": 2, "unit": "cm" },
      "bottom": { "value": 2.5, "unit": "cm" },
      "left": { "value": 2.2, "unit": "cm" },
      "right": { "value": 1.4, "unit": "cm" },
      "mirror": true
    }
  }
}

按这份配置，每个奇数页左侧（订口）页边距为2.2 cm，右侧（切口）为1.4 cm；每个偶数页左侧（切口）为1.4 cm，右侧（订口）为2.2 cm。排好的每一页都在VDTPage上带有自己的contentArea，因此由它推导出来的一切，包括栏、整页宽的浮动体带、页眉页脚容器以及span: 'page'章首横带，都会自动随镜像后的几何关系变化。锚定到'page'/'bleed'的设计元素所用的页面框和出血框不受影响：它们描述的是实际纸张，而不是页边距。

#装订

“竖排的中文书籍在右侧装订，横排的书籍在左侧装订”（clreq §7.1.1.1）。page.binding: 'right'按右侧装订来排书：

• 第1页仍是奇数页，也仍是右页，所以breakBefore.parity、:::pagebreak{parity}、带parity的设计元素以及所有页数的含义都不变。变的是右页所在的一侧：它成了跨页中左边的那一页。所以从新的右页开始的章，开在左边一页上（clreq §7.1.3.3）。
• 设了margins.mirror时，left仍是内侧页边距，但左右互换的是奇数页：第1页的内侧页边距在右边，第2页在左边。位于'outer'/'inner'的oneAndHalf侧栏、贴着订口的旋转浮动体、篇章页的页边距，以及位于'outer'/'inner'的框角图标，都遵循同样的规则。
• 文档本身会标明这一点（VDTDocument.binding: 'right'），宿主程序无须读取配置：沙盒把跨页显示为[3 | 2]，第1页单独位于订口左侧；它的HTML查看器从右向左排列页面，从右端打开，左箭头翻到下一页。renderToHtml在multi模式下把一行页面从右向左排列。
• 无论是否带标签，PDF都写入/ViewerPreferences << /Direction /R2L >>和/PageLayout /TwoPageRight（第1页单独，之后两两成对）。Acrobat和Foxit会遵循这两项设置，Chrome内置的查看器则都忽略。

页码和书眉不会自行移动：把页码印在外侧角的模板，需要为右侧装订分别设置奇数页和偶数页的元素（元素可以带parity）。

从右到左书写的书（阿拉伯文、波斯文、希伯来文等）也在右侧装订：文档的direction解析为'rtl'时，'auto'给出右侧。这样的书还会把整个文字流镜像：第一栏在右边，缩进、列表标记、浮动体和脚注都在右侧；页眉和页脚的槽位保持物理方向。见阿拉伯文排版。

从右往左读的漫画书也在右侧装订：配置中有comics部分且其阅读方向解析为'rtl'时，'auto'给出右侧。日本漫画（comics.artDirection: 'rtl'）以及西方漫画的日文版或繁体中文版都是如此。由这一部分为全书决定，而不是某一章的:::page块。见漫画。

#页面尺寸预设

四种报纸开本是postext 1.18新增的，没有画在图中：对开大报一页的面积将近21 × 28页面的四倍。它们通常用'multiple'版式排，对开大报常见六栏，小报常见五栏。

#基线网格

基线网格是正文的节奏：从内容区域顶端算起，每隔一个正文行距一条线。无论是否画出来，版面都会使用它：标题、列表末尾、框、图和行间公式之后，文字都会回到网格上（除非它们自己的snapToGrid关闭），所以相邻各栏的行保持对齐。enabled只负责在Canvas、PDF和沙盒视图中画出这些线，用来检查节奏；打开或关闭它不会移动任何东西。这些线只覆盖页面上实际的文字，从第一行文字到最后一行，所以浮动体带、为奇偶页补的空白页以及末尾未用的空间都不显示网格。

page: {
  baselineGrid: { enabled: true, color: { hex: '#e0e0e0', model: 'hex' } }
}

#裁切线

启用后，画布会扩大以包含出血区域，引擎还会在每个角画出裁切标记，供印刷生产使用。PDF的每一页都带有TrimBox和BleedBox；PDF/X文件即使没有裁切线也有这两个框。在沙盒中，它们在导出 › 印前准备中设置。

纸张每一边扩大bleed + markOffset + markLength，裁切后的页面位于正中。成品的每个角有两条标记，各长markLength，分别与在该角相交的一条边对齐。标记从成品边缘外markOffset处开始；如果bleed比它宽，就从出血边缘开始，这样标记不会压在延伸到出血区域的图文上。按默认值（3 mm出血、3 mm偏移），标记位于成品外3到8 mm之间，标记之外还有一圈3 mm宽的空白带环绕纸张。cropMarkSegments(page, doc.config.page, doc.trimOffset)以页面像素返回一页的八条标记，也就是Canvas和PDF后端所画的那些。第三个参数是成品在纸张中的位置，PDF的TrimBox就是据此写出的；省略时按同样方式从cutLines算出。

出血区域之外，除了标记什么都不印。页面绘制的一切，包括锚定到'page'或'bleed'的设计元素，在Canvas、PDF和HTML输出中都会被裁到出血框以内，与桌面排版软件导出时的裁切一致：有意超出出血放置的色带或图片，在出血边缘被截断，反正裁切时那部分也会被切掉。postext 1.4及以前，这样的元素会越过标记一直延伸到纸张边缘。

在PDF（postext-pdf）中，每页的MediaBox是整张纸。页面还带有TrimBox（裁切后的成品页面）和BleedBox（成品加出血），供拼版和印前检查工具读取。标记用套准色即/All分色绘制，因此每块印版上都会印出。无论PDF以何种色彩空间写出（RGB、灰度或CMYK）都是如此：普通黑色到了印厂会变成四色叠黑，或只落在黑版上。color只用于画布。

#页码编号

page.pageNumbering块控制页码标签的格式以及计数器的起始值。它只定义整个文档的默认设置。要在文档中途重新编号（例如前置部分用罗马数字，正文各章改用从1开始的阿拉伯数字），请使用:::numbering指令（见文档格式 → 指令）。

计算出的标签以pageLabel存放在每个VDTPage上，页眉页脚占位符{pageNumber}解析出的就是它。PDF会写出/PageLabels数字树，使“预览”/Acrobat的页码指示和“转到页面”导航与印出的标签完全一致。PDF没有对应代码的样式（中文数字、带圈数字和全角数字）会逐页写出，所以阅读器同样显示一、二、三。

编号格式的写法

有三处设置可以选择编号格式，各自形成了自己的写法：页码标签（page.pageNumbering.format和:::numbering{format=…}）写作lower-roman，有序列表（orderedLists.numberFormat）用arabic表示十进制，资源类型（counterFormat）写作roman-lower。这三处都接受下表中的所有写法，所以从一处复制过来的格式在另外两处同样可用。名称不区分大小写；单字符形式区分（i和I不同）。

东亚样式在三处设置中都沿用CSS Counter Styles中的名称。中文小写数字在10到19之间写作十，前面不加一（十二，但一百一十）；数中连续的零只写一个零（一百零一、一千零五十）；万位用万或萬，亿位用亿或億（一万零一十）。只有cjk-decimal使用〇，逐位书写，与年份的写法相同（二〇二六，GB/T 15835—2011）。天干到10为止，地支到12，带圈数字到50；超出后以阿拉伯数字输出。一和壹跟随文档locale的字形：zh-Hant、zh-TW或zh-HK为繁体，其余为简体。有些较早的出版物把101写作一百一，不带零；Postext不输出这种形式。

日文样式（从postext 1.16起）同样遵循CSS Counter Styles。japanese-informal写十时前面不加一，空位不写零（百一、千十）；japanese-formal写大字壱 弐 参 拾 百 阡，每个单位前都保留壱（壱拾、壱百）。CSS中两者都到9 999为止；Postext接着按四位一组用万 億 兆（大写为萬 億 兆）往下写，每组在单位前保留一：一万一是10 001，一億一万是100 010 000。在日文文档（ja、ja-JP等）中，一表示japanese-informal，所以第{1:一}章在那里印作第百一章，在中文文档中印作第一百零一章；壹仍是中文大写数字。假名序列就是CSS中的列表：按五十音顺的48个假名（包括ゐ和ゑ）和按伊吕波歌顺序的47个假名；排到最后一个之后接着用两个假名（ああ、いい），它们没有零，所以编号为0的项印作0。逐位的汉字数字（二〇二六）是cjk-decimal，年份和页码用这种写法。

阿拉伯样式凡CSS已有名称的都沿用之（arabic-indic、persian；W3C《Ready-made Counter Styles》中的urdu和maghrebi-abjad分别读作persian和arabic-abjad-maghrebi）。arabic仍表示欧洲数字。arabic-abjad输出古典阿拉伯语和抄本页码所用的累加式阿布贾德数字，数值大的在前：11为يا，1446为غتمو，千位的倍数写在غ之前（2000为بغ，1002为غب）；超过999 999时以数字输出。W3C把这个名称用于一个28个字母的序列，其中11为ك；Postext把这个序列称为abjad，即按阿布贾德顺序给列表项编字母（أ، ب، ج، د، هـ），按字母表顺序的则是hijai（أ، ب، ت، ث）。两者都把第一个字母写成带hamza的أ，把单独出现的he写成带tatweel的هـ，以免被读作数字١和٥；超过28个后按lower-alpha的方式双写（أأ、أب）。马格里布数值依照口诀صعفض قرست ثخذ ظغش（ص为60，ض为90）；W3C的列表把ص与ض对调。单个أ无法区分两种字母序列，因此它们的记号是各自的前四个字母：{1:أبجد}、{1:أبتث}。文档本身的数字由numerals设定。

其他写法是为不经类型检查的配置准备的，即JSON预设和纯JavaScript。TypeScript类型仍然只列出每处设置自己的写法，也就是沙盒写入、resolveAllConfig返回的那种（东亚名称也包括在内），所以有类型的PostextConfig要守住这种写法，用别的写法需要类型断言。

// JavaScript或JSON预设（在TypeScript中，用每处设置自己的写法）
orderedLists: { numberFormat: 'decimal' },          // 等同于'arabic'
page: { pageNumbering: { format: 'roman-lower' } }, // 等同于'lower-roman'
resourceTypes: [{ id: 'plate', counterFormat: 'upper-roman', … }], // 等同于'roman-upper'

resolveAllConfig会把列表格式和页码格式转换成各自设置的写法：在orderedLists中'decimal'解析为'arabic'，在page.pageNumbering中'roman-lower'解析为'lower-roman'；stripConfigDefaults会去掉默认值的任一写法。沙盒的面板无论配置用的是哪种写法，都按三处设置各自的写法显示。其他任何值，如roman、01或拼写错误，都按十进制编号而不会印出undefined，并作为配置警告报告。标题编号模板在冒号后接受同样的名称（{1:roman-upper}即{1:I}），此外还有它们自己的补零形式{1:01}。

#版式

layout属性控制内容区域中的分栏方式。

#竖排

设了writingMode: 'vertical-rl'时，页面的排法相当于把一个横排页面顺时针转四分之一圈。文字流排在一个框架里，框架的宽度等于纸张的高度；框架中的行就是竖排文字的各列，从右往左读，引擎对行所做的一切（断行、两端对齐、浮动体、脚注、不拆分规则）都在这个框架里进行。因此在纸面上：

• 版式中的一栏就是一栏（tier）：layoutType: 'double'得到上下叠放的两栏，从右上方开始填；gutterWidth是两栏之间的距离，栏线则是两栏之间的一条横线。章末各栏不做齐底（clreq §7.1.3.4）：竖排文档中各栏齐底默认关闭，除非设置了headings.balancing.enabled。
• 文字流所说的“顶部”是纸张的右边缘，阅读从这里开始：顶部浮动体位于页面右侧，底部浮动体位于左侧，通栏章首横带是沿右边缘向下的一条带，脚注落在每一栏的左端。锚定到页面顶部的设计元素（标题版面设计、固定框）锚定在右边缘。sideColumnSide为'left'时是上栏，'right'是下栏；'outer'和'inner'分别按'right'和'left'理解。
• 文字流的页边距是纸张页边距旋转后的结果：右页边距是文字流的顶部，上页边距是它的左侧。page.margins在纸面上保持原来的名称。
• 书眉、页码、裁切标记和页面背景留在纸面上，横排，与clreq对竖排书籍的描述一致。
• 图和表保持直立。图在题注允许的范围内占满所在栏的高度，宽度最多与页面相同；它所占的宽度就是它在文字流中占用的空间。题注横排在图下方，表格的单元格也横排：两者都按横排文字度量。表格直立横贯页面，比栏高时按栏切分行。placement.align把图放在所在栏的顶端（'left'）、中间或底端。图在竖排文字中首次被引用的位置不会应用placement.rotate：构建时报告rotateIgnoredVertical内容警告。书中横排的部分（layout设为'horizontal-tb'的标题样式）会按要求旋转其中的图。
• 版面设计中的图片（章首页的插图、篇章页的插图）同样直立。它在文字流中的框按宽高互换来确定尺寸，所以size.width是图片沿栏向下延伸的长度，它在纸面上的宽度则按比例得出。
• 字符：汉字、假名和全角字符直立，各占一个全角；拉丁单词和数字侧转，保持其横排宽度；标点使用字体的竖排字形。点号从不旋转：中国大陆字体把、。，．放在字格右上角，！？：；放在字格右半部；台湾或香港字体则居中（cjk.region）。括号使用竖排字形，中国大陆文本中的“ ”‘ ’显示为『』「」。破折号、省略号和波浪线在字体有竖排字形时使用它（Noto CJK把—的竖排字形与fwid一起放在vert下：字格中央一条竖线），否则旋转，使墨迹位于栏的中轴上。中文文本中的破折号（——）在栏中是一条连续的线：它的竖排字形会在每个字格两端留空，所以每个破折号随行旋转，并像横排时一样拉伸（见标点宽度）。不超过两位的数字直立占一个字格，除非它位于拉丁语句中，这时跟随该句的单词（见竖排中的数字）。间隔号（·）在中国大陆文本中占半个字格，在台湾和香港文本中占一整个字格。Unicode规定直立的符号（× © ± § ℃ ①之类）单独占一个字格，在数字中间也是如此：3×4是侧转的3和4，中间夹一个直立的×。拉丁单词中两个字母之间的撇号或间隔号（don’t、l·l）留在单词里，一起侧转。竖排文字流中的拉丁段落遵循同样的规则。行内公式、行内标签和色块随行侧转。
• 每个字符都按绘制的方式度量：直立字符沿行向下前进一个字格，侧转的文字前进其横排宽度。在纸面上保持横排的文字（书眉、页码、题注、表格单元格）按横排度量。
• 标点宽度、标点悬挂和汉字与拉丁字母之间的空白沿竖行的作用与沿横行相同。字形前的空白在它上方，后的空白在它下方：开明式的“、”占半个字格，」「挤压为一个半字格，行首被挤压的开括号上移半个字格，悬挂的“。”位于所在行底端之下，侧转单词上下各有四分之一个全角的汉字与拉丁字母间空白。：；？！在竖排中无论哪个地区都占一整个字格。
• 字符网格沿行计字符数，横跨页面计行数：charsPerLine决定一栏有多长，linesPerPage决定一页有多少行，layoutType: 'double'得到两栏，每栏都是整数个字，栏间距是整数个全角。

供读取版面的宿主程序参考：竖排页面带有VDTPage.flow。它的contentArea、栏、块、行、浮动体、脚注区、章首横带和块级设计叠加层都使用文字流坐标；width、height、header和footer使用纸面坐标。flowToPage、pageToFlow、flowRectToPage和pageRectToFlow在两者之间换算，verticalOrientation(char, region)给出一个字符的朝向。flow.centralBaselines按字体族给出版面让直立字符居中所用的轴线：“中”字墨迹的中心。“中”字的长竖贯穿全角框的高度（在Noto Serif和Noto Sans中位于基线上方0.38 em，SC与TC相同），中文、日文和韩文字体都有这个字。每一行都以这条轴线居中：竖行的基线位于行框顶端之下半个行距再加该字体族的中心基线处（横行的基线在行距的0.8处），因此一列字符位于其行距的正中，而在两列之间按整行距画的线正好落在两者中间。竖排的设计文字在其自身的行中按同样方式排。Canvas自行绘制竖排页面；要用字体自带的竖排字形绘制标点，浏览器宿主程序需要为每个字体族加载一次打开了这些字形的孪生字体：loadVerticalAlternates(family, faces)，其中faces是该字体族的来源（URL或字节数据）和描述符。孪生字体只在浏览器会对Canvas文字应用该特性时保留（Chrome 140及以后）：它用孪生字体和一份不带该特性、按给定字重与样式加载的同一组字体各画一次「（《，墨迹不同时就保留孪生字体。之后对一个已在使用孪生字体的字体族再为其他字体调用（常规体之后的粗体），会把它们加入孪生字体。沙盒对竖排文档的每个字体族都这样做。没有孪生字体时，括号绕其全角框旋转，中国大陆的点号在字格内移到字体竖排字形所在的位置：、。，．移到右上角（与Noto Serif SC的竖排字形相差不超过0.07 em），！？：；右移半个全角并稍稍上移（相差不超过0.02 em）。PDF和HTML排出的是同样的页面：见PDF中的竖排文字，以及HTML输出与Canvas和PDF的区别下的表格。以Noto Serif TC和SC逐字格与HarfBuzz（使用vert的竖排排版）比对，「賈雨村」云云，宜乎？故曰！；：、。“引”‘單’……中的每个字符，在Canvas和PDF中偏差都在0.02 em以内，在HTML中在0.05 em以内（Chrome把旋转后的字形居中于字体上伸部与下伸部的中点，在Noto中比全角框中心高0.05 em）。flow.dashAdvances按字体族给出页面为填满字格而拉伸的每种横线（— – ― ⸺ ⸻ －）的横排前进宽度（以em计），供没有自身字体度量的渲染器使用：HTML按它拉伸横线，Canvas和PDF则按各自的度量拉伸。书眉和页码也可以竖排：见竖排文字元素。

#栏线

在栏间距中画一条细竖线，从视觉上分隔各栏。

在通栏标题（span: 'page'）之下，栏线从各栏文字开始的地方开始，也就是标题横带下方，无论横带是默认的章首样式还是自己的版面设计所绘。postext 1.4及以前，栏线从文字块顶端开始，穿过横带。

标题样式可以在其layout中设置自己的栏线（见标题样式），该样式所在部分的页面就画这条栏线。样式没有设置的字段取文档的值，所以只改变栏数的部分保留文档的栏线。postext 1.4及以前，样式的栏线从不绘制：每一页都画文档的栏线。

#版式类型

• 'single'：一栏，占满整个内容宽度。最适合窄页面或以长段落为主的文字。

• 'double'：两个等宽栏。经典的编辑版式，使行长保持在40–50个字符的最佳范围内，读起来舒适。

• 'oneAndHalf'：非对称版式，一个主栏加一个较窄的侧栏。侧栏（由sideColumnPercent控制）适合放边注、小图或辅助内容。取值在25–40%之间效果较好；用于行号或边缘标记的窄栏，约取10–15%。侧栏占内容宽度的sideColumnPercent%，主栏是扣除栏间距后剩下的部分，所以取50%时侧栏比主栏宽一个栏间距。只要两栏都至少保有内容宽度的1%，任何值都按原样排版；会让任一栏更窄的值（0或以下，或者宽到主栏被栏间距吞没）会被限制到能保住两栏的最近值，非数字的值则取默认值33。这时文档的configWarnings会带有{ kind: 'sideColumnPercentClamped', path: 'layout.sideColumnPercent', value, used }。标题样式自己的layout的路径会指明该样式，例如headingStyles[2].layout.sideColumnPercent，并按该样式的页边距来度量。沙盒在其检查面板中列出这些警告；collectConfigWarnings(config)不做排版就返回同样的列表。不是'oneAndHalf'的版式从不读取这个值，也从不报告它。设了sideColumnRole: 'floats'时，正文从不进入侧栏：侧栏成为一条通道，专门容纳用span: 'side'放置的图、表和标注框。侧栏中的图或表，在首次引用它的那一页从通道顶端开始叠放，所以即使正文在更靠下的位置才引用，教材的边栏图也位于该页顶部；通道剩余空间放不下的，等到下一页的通道。侧栏中的框叠放在它所打断的文字旁边；如果通道剩余空间放不下，它就上移到仍能放下的最低位置（底边与通道底边齐平），或者等到下一页。框的围栏之后的文字接到下一页时（栏已排满，或断页规则把那段文字移到后面），框留在围栏处，位于前面文字的旁边；设了sideAtColumnEnd: 'after'的样式则把它放在下一页的通道里，与围栏后文字的第一行平齐，写在所属行之前的行号和边栏标题需要这样。标题版面设计中位于通道内的元素（锚定在外侧页边距的章序号）也会被叠放内容避开（见预留高度）。span: 'page'浮动体和框仍然横跨两栏，带placement.captionSide的栏内浮动体则把题注放在通道中，与图平齐。与镜像页边距和sideColumnSide: 'outer'配合，通道就位于每一页的外侧边缘，即教材的边栏。

• 'multiple'：三到八个等宽的栏，栏数由columnCount给出（默认3），是报纸和许多杂志的版式网格（postext 1.18起）。每栏宽为(内容宽度 − (n − 1) × gutterWidth) / n。正文像双栏版式一样从一栏接到下一栏；每个栏间距都画栏线，齐栏在章末页和通栏框之前让所有栏平齐，脚注在每一栏中都可用，通栏的图、框和标题横跨整个页面。图或浮动框可以只占其中几栏：placement.columns（见资源类型）和标注框样式的columns。columnCount超出3–8或不是整数时，取整并限定到最接近的有效栏数（不是数字的值取3），文档的configWarnings带有{ kind: 'columnCountClamped', path: 'layout.columnCount', value, used }（标题样式自己的layout的路径会写出样式，如headingStyles[1].layout.columnCount）。其他类型的版式从不读取这个值。layout为'multiple'的标题样式沿用文档的columnCount，除非它设定了自己的栏数，因此一份五栏的报纸可以把评论版排成四栏。

#页眉与页脚

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结构在输入时解析，并在解析配置时改写为定位，所以已有的配置无须改动即可继续使用。