Postext配置

Postext的每一项版面决定都由同一个配置对象控制。

PostextConfig控制页面尺寸、分栏方式、正文排印、标题样式、文档语言（locale）等。所有属性都是可选的：Postext自带一套合理的默认值，参照的是传统书籍排版。你只需写出想改的部分。

import { buildDocument } from 'postext';
 
const document = buildDocument(content, {
  page: { sizePreset: '21x28', dpi: 300 },
  layout: { layoutType: 'double', gutterWidth: { value: 0.5, unit: 'cm' } },
  bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt覆盖默认的8 pt
  headings: { fontFamily: 'Open Sans' },
});

引擎如何处理这份配置，概览见架构一页。

#内容一览

这份参考很长，主要分为以下几块：

• 页面：尺寸、页边距、基线网格、裁切线、装订。
• 版式：栏数、栏间距、栏线、竖排。
• 页眉与页脚：每页的文字元素和线条元素，支持占位符、奇偶页和对齐方式。
• 正文：排印、断词、段首孤行与段末孤行。
• 文档语言：顶层的locale，决定断词的后备语言、内置资源类型、表格和拆分标注框的续接文字、写入无障碍PDF的语言标签；另见Postext排版所支持的语言与文字。
• 东亚排版：cjk，涵盖中文、日文和韩文的地区惯例与断行、两端对齐时行内空白的分配、标点宽度与悬挂、汉字与拉丁字母之间的空白、字符网格、竖排中的直立数字，以及着重号、注音和割注。完整指南见中文排版。
• 标题：共享默认值以及H1–H6各自的覆盖设置。
• 无序列表与有序列表：项目符号、编号、嵌套。
• 数学公式：LaTeX渲染、缩放、颜色、外边距。
• 资源类型：图、表及自定义类型的分类编号。
• 表格样式（含命名表格样式）与题注样式：表格资源及其题注的排印与装饰。
• 图示样式：把嵌入的SVG图示改为单一油墨，用于专色印刷。
• 段落样式：供:::paragraphs容器使用的命名样式，如参考文献、术语表、注释。
• 标注框样式：供:::callout容器使用的带框注释、提示和学习目标。
• 篇：:::part容器生成的篇章分隔页，包括奇偶页、正文区域、篇首页版面设计、正文排印。
• 标题样式：供{style="…"}标题使用的命名样式，如不编号的章、带独立书眉的前置部分、页面几何与调色板。
• 目录：:::toc排出的内容，包括条目排印、前导符、页码、作者行、篇条目。
• 索引：:::index排出的内容，包括条目排印、缩进、页码分隔符与页码范围、字母分组、排序语言。
• 单位与颜色 + 调色板：Dimension、ColorValue、命名颜色。
• 自定义字体：在Google Fonts之外声明用户上传的字体族。
• HTML查看器：HTML后端的目标栏宽与断行。
• PDF生成（配置）：PDF后端的书签大纲、无障碍（带标签的）输出、强制色彩空间。
• 调试：编辑器中的可视化叠加层与编写警告。
• 以编程方式使用：buildDocument、它报告的警告、解析器、缓存。
• 在Web Worker中运行排版：在主线程之外构建，并可取消。
• 集成HTML查看器与生成PDF：端到端的完整做法。

#页面

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）。

#页面尺寸预设

#基线网格

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

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

#裁切线

启用后，画布会扩大以包含出血区域，引擎还会在每个角画出裁切标记，供印刷生产使用。

纸张每一边扩大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（成品加出血），供拼版和印前检查工具读取。PDF以CMYK写出时（colorSpace: 'cmyk'，或pdfGeneration.forceColorSpace配合colorSpace: 'cmyk'），标记用套准色即/All分色绘制，因此每块印版上都会印出。RGB和灰度PDF则用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不输出这种形式。

其他写法是为不经类型检查的配置准备的，即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'配合，通道就位于每一页的外侧边缘，即教材的边栏。

#页眉与页脚

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为'ellipsis-end'。 对所在空间来说太宽的文本会被截成一行并加上…。地址、署名或任何可能较长的标题，都要设overflow: 'wrap'。内容中的换行（换行符，或模板、属性值中的\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结构在输入时解析，并在解析配置时改写为定位，所以已有的配置无须改动即可继续使用。

#正文

bodyText属性控制所有段落文字的排版。

引用块

引用块（以>开头的行）沿用正文的字体族、字号、行距、字重、对齐方式和断词设置。其余由bodyText.blockquote设置；不设置时，引用块的样子与postext 1.4及更早版本相同：灰色、斜体，使用正文的首行缩进，没有侧缩进。

bodyText: {
  firstLineIndent: { value: 1.5, unit: 'em' },
  // 正体诗行，使用正文颜色，缩进2 em，无首行缩进。
  blockquote: { color: { hex: '#241f26', model: 'hex' }, italic: false, indent: { value: 2, unit: 'em' }, firstLineIndent: { value: 0, unit: 'em' } },
}

在沙盒中，这些设置位于“正文”部分的引用块分组。

每个fontFamily只写一个字体族

fontFamily，无论是这里还是其他任何字体族字段（headings.fontFamily、tableStyle.bodyFontFamily、separatorFontFamily、行内标签样式或设计元素的fontFamily……），都只指定一个字体族。Canvas、HTML输出和PDF必须使用同一款字体，而PDF对每个字体族只嵌入一款字体，没有回退链，所以CSS字体栈没有可以回退的对象。写成字体栈时，按其中第一个字体族排版，并报告一条配置警告：

bodyText: { fontFamily: "'EB Garamond', Georgia, serif" } // 用EB Garamond排版

排版前要先加载这个字体族（见自定义字体，以及生成PDF中的字体提供器）；如果缺少它，浏览器会用默认字体测量，不管字体栈其余部分写了什么。引号内的逗号是名称的一部分（'"Foo, Bar"'是一个字体族）。

#断词

文字对齐设为'justify'时，断词在音节边界处拆分长词，避免词间距过大。引擎使用TeX/Liang断词模式在音节边界找到自然的断点。详细说明见断词与两端对齐。不齐行文字只有在你要求时才断词：见下文不齐行文字。

受支持的语言：'en-us'（英语）、'es'（西班牙语）、'fr'（法语）、'de'（德语）、'it'（意大利语）、'pt'（葡萄牙语）、'ca'（加泰罗尼亚语）、'nl'（荷兰语）。

选择断词模式时，地区、文字和变体子标签都被忽略，大小写和_分隔符也一样：'es-ES'、'es-MX'和'es_419'都用'es'断词，'pt-BR'用'pt'，所有英语标签（'en'、'en-GB'）都用'en-us'。'en-us'是唯一内置的英语模式，所以英式英语文字得到的是美式断点。没有内置模式的语言（'sv'、'pl'、'fi'……）用'en-us'模式断词，结果是错误的断点，而不是不断词；引擎对每个标签用console.warn报告一次，沙盒则在“检查”面板中列出。这样的文档请设置enabled: false，警告也随之消失。中文、日文和韩文（zh、ja、ko，不论地区或文字）不需要断词模式，也不打印警告：用这些语言写的文档不断词。如果要拆分其中引用的拉丁文词语，设置enabled: true，并在locale中写明它们的语言（英语写'en-us'）。设置enabled: true但没有locale，或locale是中文、日文或韩文时，断词保持关闭，并在控制台提示一次。matchHyphenationLocale(tag)返回一个标签对应的内置语言（没有时返回undefined），HYPHENATION_LOCALES列出所有内置语言。解析后的配置（doc.config.bodyText.hyphenation）在locale中写明实际使用的模式，如果你给的标签与之不同，则保留在tag中。PDF后端根据顶层locale声明文档语言，只有在locale未设置时才采用这个标签（见文档语言）。

import { matchHyphenationLocale } from 'postext';
 
matchHyphenationLocale('es-MX'); // 'es'
matchHyphenationLocale('en-GB'); // 'en-us'
matchHyphenationLocale('sv');    // undefined：用'en-us'断词，并在控制台警告

少于5个字符的词从不断词。引擎要求断点前至少有2个字符，断点后至少有3个字符。

不齐行文字

默认只对两端对齐的文字断词：设置textAlign: 'left'时，以及在左对齐、居中或右对齐的段落样式中，无论边缘多么参差，每个词都保持完整，只有文中手动输入的软连字符（U+00AD）处例外。设置hyphenation.ragged: true即可对不齐行文字也断词。

不齐行的行从不拉伸，所以如果把每个放不下的词都拆开，边缘会挂满连字符。断词区对此加以限制，做法与桌面出版软件的单行排版器相同。一个词在行尾放不下时，引擎看的是把它整个移到下一行会留下多大的空白。如果空白比zone宽，就在能放下的最后一个音节处拆分；否则整词移到下一行。以em表示的断词区相对于该文字自身的字号。默认值3em只拆分那些会留下明显短行的词。断词区越宽，连字符越少，边缘越参差；设为0则拆分每个放不下的词。逐行排时，连续以音节结尾的行不超过两行。硬连字符（enseñanza-aprendizaje）、URL的连接处、文中手动输入的软连字符，以及比整行还宽的词，都照常断开：断词区和两行限制只管词典给出的音节。

这项设置作用于整篇文档。正文和引用块不齐行时适用；每个不齐行的段落样式和标注框正文，只要它自己的hyphenation是开启的（默认取正文的hyphenation.enabled），也都适用，所以设置hyphenation: false可以让某个样式的词保持完整。标题、题注、注释、表格单元格和目录不断词；在这些地方，和其他地方一样，只有比整个行长还宽的词才会拆分。设计文字（书眉、章首页、篇页）遵循各个文字元素自己的hyphenate标志，内置的整页章首页和篇页都设置了它，同样使用文档的词典。两端对齐文字忽略ragged和zone。

const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    textAlign: 'left',
    // 比默认的3 em多断一点词。
    hyphenation: { ragged: true, zone: { value: 2, unit: 'em' } },
  },
};

开启optimalRagged（默认）时，不齐行的连续正文用Knuth-Plass断行，断词区的含义不变：只有当一个词放不进本行余下的空间，而且整词移下去会留下超过断词区的空白时，才拆分它。连续两行以音节结尾并不被禁止，但代价与两端对齐文字中连续两个连字符相同，所以很少会连续出现第三行。设置optimalRagged: false或optimalLineBreaking: false时，先填满一行再排下一行，与postext 1.4及更早版本相同。

不齐行断词用的是带行内格式（粗体、斜体、链接、数学公式）的段落一直使用的那个断行器，所以开启它可能会让连字符以外的少数断点也发生变化。在不齐行的行上，除了空格和词典给出的音节，这个断行器还会在两个词之间的硬连字符或破折号之后断行（largas—separadas；开启breakAfterDashes时，任何在词间紧排的破折号都算，riddles.—I和riddles—*and*也包括在内），在URL的连接处和表意文字之间断行，并把分成几个片段排的一个词保持在一起（**Nota**:、(*véase*）。不开启不齐行断词时，没有格式的不齐行段落在optimalRagged开启（默认）时由Knuth-Plass断行：在词间空格处、在两个字母之间的硬连字符之后（meta- · analyses），这一点与另一个断行器相同；开启breakAfterDashes时，还在紧排的破折号之后。逐行排时，它交给pretext的断行器处理，区别有三点：它还可能在结束插入语的破折号之前或开启插入语的破折号之后断行（él · — y），断词时可能在斜杠之后断行（km/ · h），而对于比整行还宽的词，它会在任意字符处截断且不加连字符，另一个断行器则先尝试在音节处拆分。

在沙盒中，这个开关是不齐行文字断词，位于“正文”部分的段落对齐方式下面，断词区在它下方。正文两端对齐时，同一个开关与两端对齐设置放在一起，供不齐行的段落样式和框使用。

#文档语言

顶层locale是整篇文档的语言。它的取值与hyphenation.locale相同，并在后者未设置时作为回退值，所以一本西班牙语书只需写locale: 'es'就能按西班牙语断词。它还决定表格和拆分标注框内置续接文字的语言（(cont.) / Continued与Continúa，见高于页面的表格和拆分框上的标记），决定用文字拼写的标题编号的语言（Chapter One与Capítulo uno，见用文字拼写的编号），也是写入无障碍PDF的语言。未设置时，引擎假定为'en-us'；沙盒则回退到界面语言，并在设计 › 书写系统下设置此字段。

它也决定内置的资源类型。未设置resourceTypes时，buildDocument用defaultResourceTypes(locale)编号和生成题注，所以只写locale: 'de'就会得到Abbildung 1.1和Tabelle 1.1。未设置locale时，由断词语言代替它，资源类型和表格文字都是如此。显式给出的resourceTypes列表始终优先。早先的版本中，除非你自己传入defaultResourceTypes(locale)，否则无论locale是什么都使用英文类型；设置了locale又想保留英文标签的文档，可以传入resourceTypes: defaultResourceTypes('en')。沙盒中的书和文件包自带类型列表，所以不受影响。

这里与hyphenation.locale一样接受任意BCP 47标签：'de-AT'得到德文文字。内置文字提供断词所支持的八种语言，以及简体和繁体中文；其他语言一律使用英文文字。

中文接受zh、zh-Hans、zh-Hant、zh-CN、zh-SG、zh-TW、zh-HK、zh-MO以及长形式（zh-Hant-TW），不区分大小写，分隔符用-或_均可。文字按书写系统选择，由Intl.Locale(tag).maximize()判断：zh、zh-CN和zh-SG是简体，zh-TW、zh-HK和zh-MO是繁体。依语言而定的排版默认值则按地区选择，这是clreq §1.2的建议：CN、SG和MY算作中国大陆，TW算作台湾，HK和MO算作香港；没有地区的标签按书写系统判断（zh-Hant为台湾，zh和zh-Hans为中国大陆）。localeScript(tag)、cjkRegionOf(tag)、stringsKeyOf(tag)和sameContentLocale(a, b)给出这些判断结果，DOCUMENT_LANGUAGES列出带内置文字的语言，每种语言都用它自己的语言命名，与沙盒“文档语言”下拉框中的显示一致。

题注前缀是类型的名称（Figure 1.1.）。中文类型在章内编号，用连字符连接，即{h1}-{n}（图 1-1）；配合题注设置labelNumberGap: ''和labelSeparator: '　'，题注显示为“图1-1　标题”（见题注样式）。索引同样跟随语言：简体中，交叉引用前用“见”和“另见”，符号和数字条目上方的标题为“符号”和“数字”；繁体中则为“見”“另見”“符號”和“數字”。

中文、日文或韩文文档会在HTML输出中（.pt-doc根元素上的lang，zh-Hant-TW完整保留）以及它绘制的Canvas上（ctx.lang，Chrome 136及以上版本）声明语言，使浏览器绘制该地区的字形：Unicode统一了汉字编码，同一个码位在台湾字体和日文字体中的样子并不相同。其他文档照旧不带lang。PDF则对每个文档（无论是否带标签）根据locale声明/Lang，包括其书写系统和地区。

const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // 按西班牙语断词
};

#语言与文字

Postext能排从左到右书写的拼音文字，以及横排和竖排的中文。中文排版介绍中文的排法和相关设置；对应的配置键位于东亚排版、竖排和装订。各种文字的支持情况如下：

• 中文：段落中的CJK字符多于词间空格时，由CJK排版器处理：行在字符之间断开，遵守cjk.lineBreak的避头尾规则（行首不出现。、」或ー，行尾不出现「或（），——和……不拆开，数字连同其符号、拉丁文单词都保持完整；两端对齐的行在字符之间均匀分配空白以填满行长。标点宽度、标点悬挂、汉字与拉丁文之间的间距、字符网格、着重号、专名号和书名号、注音以及割注，都按locale的地区处理，横排（沿行）和竖排（layout.writingMode: 'vertical-rl'）都一样。只引用少量CJK词语的拉丁文段落保持最优断行，并可以在这些词语旁边断行；拉丁文中引用的CJK括号、间隔号或全角符号（〈h〉、％）不影响任何处理。
• 日文和韩文：使用同一个排版器，不断词，但采用中国大陆中文的默认值：它们各自的规范（JLREQ、KLREQ）尚未实现。韩文除了在空格处断行，也在音节之间断行。
• 从右到左的文字（阿拉伯文、希伯来文、波斯文、乌尔都文……）目前还不支持。没有双向算法：各行按从左到右的方向断行并对齐到左边距，每行显示的效果取决于它的绘制方式。在Canvas和PDF输出中，没有行内格式的左对齐行作为一整段文字绘制，由浏览器或PDF的字体引擎自行转为从右到左，因此全部由同一种从右到左文字组成的行可以正确阅读，但混有不同方向、数字或标点的行则不行。HTML输出，两端对齐、居中和右对齐的行，以及带行内格式的行，都是从左到右逐词绘制的：每个词本身读起来正确，但词的顺序与阅读顺序相反。page.binding: 'right'可以为这类书排出右装订的跨页，但处理不了其中的行。

断词模式内置八种语言（en-us、es、fr、de、it、pt、ca、nl）；内置的资源类型和续接文字提供这八种语言以及中文。中文、日文和韩文不断词。其他语言用美式英语模式断词并在控制台警告，使用英文文字。这类文档请设置hyphenation.enabled: false，并用该语言传入resourceTypes和tableStyle的续接文字。

#段首孤行、段末孤行、孤字与不拆分规则

这些缺陷值背后的机制见断词与两端对齐。本节是驱动它们的bodyText配置键的参考。

除了断词和间距上下限，正文配置还提供一组软规则，用来防止在结构上别扭的地方拆开段落。它们全部作为缺陷值（demerits）输入Knuth-Plass断行算法：让版面倾向于干净的断点，但从不强制执行硬性规则。把某个*Penalty值设为0，就相当于关闭对应的规则。

**关于孤字。**孤字是指段落的末行太短，不像一行正常的文字，通常是一两个短词孤零零地落在段落末尾。由于判断依据是这一行的像素长度与正常空格宽度之比，runtMinCharacters会自动适应当前字号。视觉宽度超过runtMinCharacters × spaceWidth的短词没有问题；比这窄（或真正单独一个）的词会招来孤字惩罚。阈值以词间空格计数，而词间空格约为字母宽度的一半：默认值20相当于大约8到12个字母的末行。每个孤字都承担完整的惩罚值，所以在两个都低于阈值的结尾之间，断行器会保留上面较紧的行；gradedRuntPenalty则按短缺程度给每个结尾定价，较长的结尾胜出。给对数学感兴趣的读者：在默认的runtPenalty为1000时，避免孤字的优先级高于任何需要大约r≈2.15以内词间距拉伸的其他断点组合。

**软规则，不是硬规则。**这些规则都不能阻止某个断点，引擎总会给出一个版面。它们是缺陷值：算法在一次全局优化中权衡劣度、断词代价、适配等级的平滑度和这些结构性惩罚，选出总代价最低的断点组合。如果需要更硬的保证，就提高惩罚值；如果某篇文档放宽惩罚后读起来更好，就降低它。

#标题

headings属性控制所有标题级别（H1–H6）的排版。你可以先设定适用于所有级别的通用默认值，再按级别覆盖其中的个别属性。

#通用默认值

诗歌或剧本各幕用的居中标题，不需要设计槽位：

headings: {
  textAlign: 'center',
  levels: [{ level: 2, textTransform: 'uppercase' }],
}

传入headings对象时，你没有重新声明的级别默认值都会保留，包括H1的分页（见按级别覆盖）。

#各栏齐底

出版方要求每一栏都从页面顶部开始、在页面底部平齐结束。分页规则（段首孤行和段末孤行保护、标题与正文不分离、不可拆分的图）自然会留下短栏，即栏底空着一个或多个基线网格行。启用齐底后，引擎会像排版工人那样处理，按编辑上的优先顺序使用以下手段：

1. 收尾的框：结束一个短栏的标注框整体下移，下移量正好等于其底部下方的空余，使它的下边缘落在页面最后一个网格位置上，与相邻栏的最后一行平齐。即使空余不足一行，只要没有内容移入另一栏，它也会占满这段空余。默认情况下这一手段先于其他所有手段执行，并占用整段空余，所以一个注释上方段落的框可能最后落在该段落下方好几行处；closingBox: 'last'让标题、列表结尾和其他间距手段先占用整行，框只占它们剩下的部分；closingBox: 'off'则从不移动它。
2. 标题：在短栏内各标题的上外边距中增加整数个网格行。需要多行且栏内有多个标题时，这些行分配给各个标题，最重要的标题总是分得最多（h2比h3多）。位于栏顶的标题从不加空，因此各栏始终从页面顶部开始。唯一的例外是：在文字流继续到下一页的页面上，紧接在栏首图或表下方的标题，空间会加在这个标题上方、图的下方。
3. 列表结尾：标题无法吸收全部空余时，在列表或编号列表结束处增加一个网格行（列表后的空白读起来很自然），每个列表结尾有上限。
4. 放松段落：作为最后手段，把栏内某一段重新断行，使其多出一行（即TeX的\looseness=+1），并选最长的段落，让增加的词间距分散得看不出来。只有每一行都保持在**bodyText.maxWordSpacing以下**时，放松后的方案才会被采用，文字灰度绝不超出你已配置的限度。需要启用bodyText.optimalLineBreaking。

只有当页面自然延续到下一页时，才会对该页最后一栏做齐底；一章的末页本来就可以短一截。这样的页面，以及由trailing截平的收尾区段，还会让各栏的栏首保持平齐：栏首为图或表时，不会在其下方加行（浮动体后手段）；在这样的图下方开栏的标题或框，无论stretchAfterFloats如何设置，都留在栏首。这样就不会为了让栏底对齐而让某一栏比旁边一栏起得更低。

哪个手段起了作用

排版会把它使用的每个手段记录在所作用的块上，即buildDocument返回的VDT中的block.balancing。校样、测试或报告可以据此说明某一栏为何平齐，以及哪些栏没有任何手段能补齐。齐底没有处理的块不带balancing，用enabled: false构建的文档则完全没有。

interface VDTBalancing {
  levers: BalanceLever[]; // 通常只有一个：列表后的段落可能既占用列表结尾那一行，又多排一行
  spaceAbove: number;     // 间距手段在块上方增加的px（只有looseParagraph起作用时为0）
  extraLines?: number;    // looseParagraph：段落多出的行数
  tracking?: number;      // looseParagraph：多出这些行所用的字距，单位为千分之一em（0 = 仅靠词间距）
}
type BalanceLever = 'trailingCallout' | 'heading' | 'listEnd' | 'afterDisplay' | 'afterFloat' | 'looseParagraph';

截平记录在被截的栏上：每个被截平的栏（通栏框留下的区段、收尾区段）上column.bandCapped都为true，column.trailingCap还额外标出一章或整个文档的收尾区段（trailing）。

import { buildDocument } from 'postext';
 
const doc = buildDocument(content, config);
for (const page of doc.pages) {
  page.columns.forEach((column, i) => {
    const levers: string[] = column.blocks.flatMap((block) => block.balancing?.levers ?? []);
    if (column.trailingCap) levers.push('closing band cut level');
    else if (column.bandCapped) levers.push('band cut level');
    if (levers.length > 0) console.log(`page ${page.index + 1}, column ${i + 1}: ${levers.join(', ')}`);
  });
}
// page 3, column 1: heading, heading
// page 3, column 2: listEnd, looseParagraph

#按级别覆盖

每个标题级别都可以通过levels数组覆盖通用默认值。默认情况下，各级别只有fontSize不同（另外还有下文说明的H1的breakBefore），其他属性都继承通用标题设置。

H1的默认值模拟图书的分章版面：每个一级标题都在新的右页（奇数页）开始，与前一章之间必有一个空白分隔页。如果你的文档层次比图书简单，可在levels[0].breakBefore上覆盖它。

级别的breakBefore按字段逐个合并到这个默认值之上，没有提到它的headings对象会保留默认值。H1上的{ parity: 'odd' }保留分页，只改变奇偶；{ enabled: false }让各章接排：

headings: {
  fontFamily: 'Merriweather',                               // H1仍然分页到新的右页（always-odd）
  levels: [{ level: 1, breakBefore: { parity: 'odd' } }],    // ……或者：右页开始，不强制空白页
}
 
headings: { levels: [{ level: 1, breakBefore: { enabled: false } }] } // 各章接排

postext 1.5起的变化。 postext 1.4及以前，任何headings对象都会关闭H1的分页，除非重新声明levels[0].breakBefore；不完整的breakBefore会用不分页的默认值补齐缺少的字段。因此，一份为1.4用代码写成、带有headings对象但没有H1分页的配置，现在会让每一章都从新的右页开始，必要时加入空白左页。要让各章继续接排，在levels的H1条目中加一个字段：

headings: { fontFamily: 'Merriweather', levels: [{ level: 1, breakBefore: { enabled: false } }] } // 与1.4的排法相同

如果配置是存储下来的，引擎能识别出来并替你处理：沙盒处理它当时保存的书和配置（见沙盒 → 持久化），openBundle / readBundle处理postext 1.4或更早版本写出的.postext文件包（见postext 1.4及更早版本写出的文件包）。你自己存储的配置可以交给postext/bundle中的migrateConfig(config)处理，它会写出1.4当时的分页方式（pinLegacyHeadingBreaks）：在没有分页的H1上写enabled: false，在H1和标题样式中未指定奇偶的enabled: true旁写parity: 'any'。它还会按1.4的设定固定以下各项：数学公式的字号、行内图周围的间距（框内也一样）、标题的行内标记、首字下沉的尺寸、引出列表的冒号行下方的空间、框截断后段落或列表项留下的行数、破折号处的断行、齐左文字的逐行断行、标题下段落的拆分、复合词连字符处的断行，以及:::paragraphs容器下方的间距。把书的Markdown作为第三个参数{ content }传入时，它会省去用不到的固定项：文本中没有$时省去数学固定项；没有一行嵌入资源时省去间距固定项（框内没有时省去框内间距固定项）；没有标题带标记时省去标题标记固定项；没有列表跟在以冒号结尾的行之后时省去冒号行固定项；文本中没有:::callout时省去框截断固定项；词与词之间没有紧排的破折号时省去破折号固定项；文本中没有标题时省去标题拆分固定项；文本中没有:::paragraphs容器时省去容器固定项；两个字母之间没有连字符时省去复合词固定项。齐左断行固定项只加给将某些正文设为齐左的配置，容器固定项只加给声明了段落样式的配置（见postext 1.4及更早版本写出的文件包）。如果只处理分页，调用pinLegacyHeadingBreaks(config)即可。

按级别覆盖支持与通用默认值相同的属性，即fontSize、lineHeight、fontFamily、color、fontWeight、marginTop、marginBottom、snapToGrid，另外还有以下仅限级别的字段：

headings: {
  fontFamily: 'Merriweather',
  levels: [
    // 标准图书预设：各章从右页（奇数页）开始。
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}

snapToGrid也可以按级别设置。未设置时，级别沿用headings.snapToGrid；设置后则覆盖它。这样同一份文档可以让H2与其正文之间隔一行半、在下一个对齐点之前偏离网格，同时让H3下方的空间向上取整为整数个网格行。标题样式也可以设置它，作用于使用该样式的标题。

headings: {
  marginBottom: { value: 1.5, unit: 'em' },
  levels: [
    { level: 2, snapToGrid: false }, // 每个H2下方正好1.5 em
    { level: 3 },                    // 继承headings.snapToGrid: true
  ],
}

#前置分页

breakBefore与编号控制相互独立：开启它会强制分页，但数字计数只在你明确插入:::numbering指令时才重置。为满足奇偶而加的空白页在页序中算作真实的页，并按正常的奇偶页规则显示页眉和页脚。

紧挨在这种标题前的:::pagebreak不会取代标题自己的分页：标题仍会在该指令所开的页之后执行奇偶约束，可能因此多出一个空白页。标题需要紧接在手动分页之后开始时，见标题样式。

奇偶取值

空白页的归属

breakBefore插入的空白页所带的章标题书眉，取决于它们为什么被插入：

• 为满足奇偶约束而插入的页（'odd'、'even'，或'always-*'中的奇偶部分）属于后面的一章。它们书眉中的{chapterTitle}占位符解析为新一章的标题，因为这个空白页只是为了把新的一章推到正确的奇偶页上。
• 'always-odd' / 'always-even'插入的强制前导分隔页属于前面的一章。它是章末有意留出的停顿，所以{chapterTitle}书眉仍显示上一章的标题。

带样式章节的书眉和调色板（见标题样式）在空白页上也遵循这两条规则。

文档开头的例外

当文档的第一个块是启用了breakBefore的标题，或源文件以:::pagebreak开头时，只要第一页仍为空，就不执行奇偶约束。标题照原样落在第1页，与所配置的奇偶无关，因此以# Chapter 1开头、配置为parity: 'odd'的文档不会多出一个多余的前导空白页。一旦放入了任何内容，奇偶约束就照常执行。

#通栏与高级设计

每个标题级别还接受两个字段，用于控制标题作为横跨整页的章首页时如何渲染。

与页面一样高的章首。 当保留高度超出栏底时（如minHeight等于页高的封面，或锚定在页面或出血框、一直延伸到裁切边的图片或框），章首占据本页余下部分：其后的文字从下一页开始，双栏和一栏半版式的每一栏都一样。所以封面之后不需要:::pagebreak（加了也无妨，不会多出空白页）。设计高于所在栏的栏内标题（span: 'column'）占据该栏，文字从下一栏栏首开始。标题的块随后一直延伸到它所占栏的栏底，设计按这个区段排布：锚定在顶部的元素留在锚定处，跟随区段的元素（锚定在区段中部或底部，或高度为'fill'）限制在标题占据的空间内，就像保留高度放得下时它们限制在保留高度内一样（postext 1.4及以前，块保持其文字的高度，所以这些元素是按只有一个标题高的区段排布的，其后的文字会接在设计下面继续排）。不应占据整页的版面装饰（贯穿整页的切口色条、页脚处的装饰）应放到页眉或页脚设计中：锚定到'page'或'bleed'，并以pages: 'opener'显示，它就只绘制在章首页上，不占用正文空间。

示例：一个简约的章首，在标题上方显示“Chapter N”：

{
  "headings": {
    "levels": [
      {
        "level": 1,
        "span": "page",
        "breakBefore": { "enabled": true, "parity": "always-odd" },
        "advancedDesign": {
          "enabled": true,
          "slot": {
            "elements": [
              {
                "kind": "text",
                "id": "chapterLabel",
                "placement": {
                  "anchor": { "to": "container", "edge": "top" },
                  "offset": { "y": { "value": 48, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "Chapter {numberRoman}",
                "fontSize": { "value": 10, "unit": "pt" },
                "align": "center",
                "overflow": "ellipsis-end"
              },
              {
                "kind": "text",
                "id": "chapterTitle",
                "placement": {
                  "anchor": { "to": "#chapterLabel", "edge": "below" },
                  "offset": { "y": { "value": 12, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "{titleText}",
                "fontSize": { "value": 24, "unit": "pt" },
                "fontWeight": 700,
                "align": "center",
                "overflow": "wrap",
                "hyphenate": true
              }
            ]
          }
        }
      }
    ]
  }
}

级别设计槽位中可用的标题占位符：

• {titleText}：标题的纯文本（不含编号前缀）。标题中的强制换行（\\）在这里是换行，章首区段和栏内设计都一样（postext 1.4及以前，栏内设计在那里输出一个空格，而高度却是按换行测量的）。隐藏标题在栏内折成的各行会按原写法重新连成标题：在自身连字符后断开的词保留连字符，后面不加空格；被栏宽断开的词重新连成整词，去掉断行时加上的连字符；由不换行空格连在一起、比栏还宽而在该空格处断开的词组，恢复其不换行空格（Capítulo XVIII，而不是CapítuloXVIII）；其他每个断行处都还原为一个空格。postext 1.4及以前，每个换行都变成空格，所以在连字符处折行的标题会输出Word- Book，这类标题中的强制换行也会被丢掉。
• {number}：按该级别numberingTemplate格式化的编号。
• {numberDecimal}、{numberRoman}、{numberRomanLower}、{numberAlpha}、{numberAlphaLower}：以其他数字格式表示的标题计数（该级别的当前计数，不管模板输出什么）：第三章给出3、III、iii、C、c，有没有numberingTemplate都一样。不编号的标题（样式设为numbered: false）让它们为空。
• {numberWords}、{numberWordsLower}、{numberOrdinalWords}、{numberOrdinalWordsLower}：用文字拼写的同一计数，首字母大写或全小写：Three / three、Third / third（见以文字书写的编号）。
• {numberHan}：用中文数字书写的同一计数，字形按文档locale的书写系统：用第{numberHan}回设置的章首，在第十二章输出第十二回，而目录列出的是12。
• {chapterNumber}、{chapterTitle}、{pageNumber}、{totalPages}、{bookTotalPages}、{title}、{subtitle}、{author}、{publishDate}：通用的元数据占位符。
• {attr.<key>}：写在标题行上的属性（# Title {author="I. Zango Martín"}），缺省时取当前章H1的同名属性。缺少的属性解析为空字符串，不给出警告。

{chapterNumber}输出的是书眉为该章输出的内容：H1的级别（或样式）有numberingTemplate时输出H1的编号，否则输出章的序号（1、2……接着本章之前已排的各章继续计数）；不编号的章或模板为''的样式则什么也不输出。标题设计读取其标题所属的章：一级标题读取自己，更低级别的标题读取它之前的最后一个一级标题。两章在同一页相遇时也是如此，而该页的书眉输出的是后一章。章首保留的高度也按同一个值测量。postext 1.4及以前，高度按标题的编号前缀测量（没有模板时为空），所以高度取决于{chapterNumber}的设计可能绘制得比所占空间更高；而且设计输出的是该页的章，所以共用一页的两章中，前一章显示的是后一章的编号。

计数占位符在逐章排版时跟随全书（即continuationAfter()传递下去的计数），标题的startAt属性会让它们重新开始（见文档格式 → 标题属性）。一个章首显示Chapter III，而文字流和目录中的标题编号为3.：

{
  level: 1,
  span: 'page',
  numberingTemplate: '{1}.',
  advancedDesign: {
    enabled: true,
    slot: { elements: [
      { kind: 'text', id: 'label', content: 'Chapter {numberRoman}', fontSize: { value: 10, unit: 'pt' }, overflow: 'ellipsis-end',
        placement: { anchor: { to: 'container', edge: 'top-left' }, size: { width: 'fill', height: 'auto' } } },
      { kind: 'text', id: 'title', content: '{titleText}', fontSize: { value: 24, unit: 'pt' }, overflow: 'wrap',
        placement: { anchor: { to: '#label', edge: 'below' }, size: { width: 'fill', height: 'auto' } } },
    ] },
  },
}

保留高度

带高级设计的标题像其他块一样在栏内占用空间：其后的正文从这段空间下方开始。这段空间取以下三个高度中最大的一个，都从标题顶部往下量（对于开新页的章首，从内容区顶部往下量）：

1. 标题本身的文字，按该级别的字体排版（它被设计遮住，但仍保留自己的行）；
2. 设计内容底部，即计入的元素（见下文）中最低的下边缘；
3. advancedDesign.minHeight。

其后加上标题的marginBottom（取自其标题样式、其级别或headings.marginBottom；默认0.5 em），标题对齐网格时，结果向上对齐到基线网格。对于章首（span: 'page'），页面每一栏都空出同样的区段。对于放得进所在栏的栏内标题，设计在标题的框内排布，框正好这么高。

哪些元素计入。 设计中的每个元素都计入，文字、线条、框和图片都一样（postext 1.4及以前，image元素从不计入，所以除非用minHeight挡住，文字可能从区段图片上面开始），以下情况除外：

• 设有reserve: false的元素：可以位于文字下方的装饰；
• 跟随区段本身的元素：锚定在容器中间一排（left、center、right）或底部一排（bottom-left、bottom、bottom-right）、高度为相对容器的'fill'的元素（没有设高度的框或竖线默认填满），以及锚定在这些元素上的任何元素。容器就是保留的区段，所以这些元素落在区段底部或纵贯区段：区段下方的一条线、标题后面的一块色底。它们跟随高度，从不决定高度。其中保持自身高度的文字仍需要空间：锚定在区段底部的标题会使区段至少与标题一样高，所以标题绝不会从标题块顶部之上开始。设minHeight: 36mm且标题锚定在bottom-left时，标题的框为36 mm加上其marginBottom，再向上对齐网格，标题位于该框底部，紧挨在后续文字上方；没有minHeight时，行数多于标题本身文字的标题会使区段与标题一样深。postext 1.4及以前，这样的标题会向上画到标题块上方的文字上。跟随区段的框、线条和图片不设这样的下限，所以锚定在底部的色底可以伸到标题上方。

锚定在页面和出血框上的元素，按它们伸到标题顶部以下多远来计入。横贯页面顶部、在标题上方就结束的色带不计入；越过标题的满版出血图片会把文字推到其下边缘之下。页面偏下的任何东西也是如此：距页脚25 mm的印章、整页高的侧边色带或边框，会把页面一直保留到其下边缘，文字通常就从下一页开始。把这类装饰标记为reserve: false（它仍会绘制，其他元素仍可锚定在它上面），再用文本元素或minHeight给标题留出所需的空间：

{
  "kind": "image", "id": "seal", "resourceId": "seal", "reserve": false,
  "placement": {
    "anchor": { "to": "page", "edge": "bottom-right" },
    "offset": { "x": { "value": -25, "unit": "mm" }, "y": { "value": -25, "unit": "mm" } },
    "size": { "width": { "value": 30, "unit": "mm" } }
  }
}

锚定在不保留空间的元素上的元素，除非也做了标记，仍会计入（放在印章上的说明文字需要自己的reserve: false）。

绘制位置。 章首的设计（span: 'page'）在正文之前绘制，所以不保留空间的装饰位于文字下层。栏内标题的设计与标题块一起绘制，压在栏内它上方的块之上、它之后的块之下，只要位于所在栏栏底以上，放在哪里都可以：两侧页边距、上页边距、出血区和相邻各栏都行。在Canvas和PDF中，栏底会把它裁掉，因为文字流在那里结束（见下文高于所在栏）。postext 1.4及以前，Canvas和PDF还会在栏顶裁切它，所以锚定在页面顶部或出血框顶部的色带能伸进两侧页边距，却在上页边距处截止。锚定在页面底部的装饰应放在章首中，或放在以pages: 'opener'显示的页脚设计中。

高于所在栏。 当所需空间超出栏底时（与页面一样高的minHeight、一直延伸到裁切边的图片或边框），标题占据本页余下部分（章首，在每一栏）或本栏余下部分（栏内标题），其后的文字从下一页或下一栏开始。标题的块随后延伸到栏底，绝不会缩回到其文字的高度，所以设计所依据的区段就是它占据的空间（包括minHeight，直到栏底）。比页面本身还高的设计（小屏页面上很长的导语）仍会在页面底部被裁掉（栏内设计则在其所在栏的栏底）：沙盒会在检查面板中列出它，标为Heading design cut off。排版本身不对此发出警告，因为占满整页的封面是常见情况，并不丢失任何内容；但任何宿主都可以对排好的版面做同样的检查：collectHeadingDesignCuts(doc)为每个设计文字超出页面裁切边底部（where: 'page'，章首）或所在栏栏底（where: 'column'）的标题返回一个{ kind: 'headingDesignCut', pageIndex, level, where, overflowPx, sourceStart, sourceEnd }，formatWarning可以描述每一项。另见通栏与高级设计下的与页面一样高的章首。

侧栏。 在侧栏放置浮动体的一栏半版式中（sideColumnRole: 'floats'），栏内标题的设计中位于侧栏里的元素（如教科书章首中锚定在页面外侧边栏里的章号数字）会让侧栏的浮动体堆叠避开它。该页在标题之后放置的每个span: 'side'图、表或框，都与每个这样的元素保持一个浮动体间距：放得进元素上方时就留在堆叠所放的位置，否则放到元素下方；侧栏余下部分放不下时，则等到下一页。所以，位于侧栏顶端的章号数字会让整个堆叠都在它下方；而挂在页面偏下的标题旁边、页边距中的节号，则把侧栏顶端留给该页引用的图（边栏图仍位于其所在页的顶部）。标题放置时侧栏中已有的内容不会被移动：本页较早堆叠、向下伸到标题元素处的图留在原处，位于该元素下面，所以元素在页中间位于侧栏的设计，最好在标题之后才引用它的图。设有reserve: false的元素不占用侧栏，就像它们不占用文字空间一样。章首（span: 'page'）不需要这种处理：它的区段在每一栏都保留，侧栏也包括在内。postext 1.4及以前，在这种章首上引用的侧栏图会放在侧栏顶端，压在章号数字上。

封面。 占满整页的封面标题（minHeight与页面一样高，或设计中有整页图片）因此会自行把其后的文字送到下一页，单栏和多栏版式都一样。紧接其后的:::pagebreak可有可无：在仍为空的页面上分页不起作用，所以绝不会多出空白页。只有当封面设计没有延伸到页面底部、而文字仍应从新页开始时，才需要它。

# Annual report 2026 {style="cover"}
 
:::pagebreak
 
# Letter from the chair

#以文字书写的编号

有两个编号模板后缀用文字书写计数，语言为文档语言（顶层的locale，否则用断词语言，见文档语言）：words表示基数，ordinal表示序数。后缀的大小写决定文字的大小写，就像字母编号的A / a一样：

英文、西班牙文和中文会用文字书写；其他语言采用英文词，与内置的表格续表字符串相同。中文按locale的书写系统采用simp-chinese-informal或trad-chinese-informal的小写数字（一万 / 一萬），序数前加“第”；汉字没有大小写，所以同一后缀的三种写法输出相同。英文遵循美式用法（one hundred five，不加and）。西班牙文用阳性形式，与capítulo或libro的编号方式一致（capítulo primero、tercero、veintiuno），13到29的序数按RAE推荐的写法连写为一个词（decimotercero、vigesimoprimero）。基数最多拼写到999 999，西班牙文序数最多到999；更大的数字以阿拉伯数字输出。

在标题设计中，{numberWords} / {numberWordsLower}和{numberOrdinalWords} / {numberOrdinalWordsLower}以同样方式拼写标题的计数，所以章首可以写Chapter One，而目录列出1。文本元素的textTransform: 'uppercase'可给出大写：

// 西班牙文小说：标题上方为“CAPÍTULO PRIMERO”，目录中为“1.”。
{ level: 1, numberingTemplate: '{1}.', span: 'page',
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'text', id: 'n', content: 'Capítulo {numberOrdinalWordsLower}', textTransform: 'uppercase', /* … */ },
    { kind: 'text', id: 't', content: '{titleText}', /* … */ },
  ] } } }

#无序列表

unorderedLists属性控制项目符号列表（-、*、+）和GFM任务列表（- [ ]、- [x]）的渲染方式。最多支持五层嵌套。

#无序列表默认值

#任务列表扩展

GFM任务项（- [ ] …、- [x] …）按无序列表项渲染，用复选框字形代替项目符号。以下字段只作用于任务项：

#无序列表的逐层覆盖

levels中的每一项针对一个层级（1–5），可以覆盖以下任意字段：

**缩进级联。**第1层总是从通用的indent值开始（默认0 em，项目符号贴住栏的边缘）。对第2–5层，如果不设indent，引擎把项目符号放在上一层文字的起点（上一层缩进 + 项目符号宽度 + gap）。在某一层显式设置indent，就会打断级联，把这一层固定在你想要的任何位置。

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#有序列表

orderedLists属性控制编号列表（1.、2)等）。最多支持五层嵌套，每一层可以使用不同的编号格式。

#有序列表默认值

#有序列表的逐层覆盖

levels中的每一项可以覆盖numberFormat、prefix、separator、fontFamily、fontSize、color、fontWeight、italic、indent、verticalOffset以及分隔符样式（separatorFontFamily、separatorFontWeight、separatorItalic、separatorColor、separatorGap），缩进级联规则与无序列表相同。某一层的分隔符样式沿用该层自己的编号样式，除非给出了整个列表的分隔符设置。

**右对齐。**排版流程会测量一个连续段中格式化后最宽的编号，并据此缩进该段的所有列表项，使编号的右边缘对齐。十项的列表渲染为1.–10.时，一位数编号的右侧会补齐，使分隔符保持在同一列。

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

得到的是经典的混合嵌套：

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

中文公文的层次序数（GB/T 15834—2011，附录B.3）共五层，依次为“一、”“（一）”“1.”“（1）”“①”：

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#数学公式

math属性控制如何解析和渲染写在$...$（行内）和$$...$$（独立）定界符之间的LaTeX公式。底层引擎是MathJax（mathjax-full包），以SVG模式输出，在Canvas上栅格化，在PDF中以可缩放的字形嵌入。

interface MathConfig {
  enabled?: boolean;        // 渲染LaTeX。为false时，公式片段按原样输出TeX源码。
  fontSizeScale?: number;   // × 周围文字的字号（独立公式以正文字号为准）。
  color?: ColorValue;       // 公式颜色；省略时沿用正文颜色。
  marginTop?: Dimension;    // 独立公式块上方的间距。
  marginBottom?: Dimension; // 下方的最小间距；对齐基线网格时可能变大。
  indentAfterDisplay?: boolean; // 独立公式之后的段落首行缩进。
  keepWithLeadIn?: boolean; // 让独立公式与引出它的那一行在一起。
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

**公式大小，postext 1.5起有变化。**MathJax以ex给出公式的框，而它的TeX字体的1 ex等于0.442 em。postext 1.4及以前，引擎把它当作半个em，所以每个公式都比bodyText.fontSize × fontSizeScale大约13%。现在公式按文档说明的大小排出，含公式的行和页面会重新排版。为1.4用代码写的配置，可以把它原样传给postext/bundle中的pinLegacyMathSize一次，保留1.4的公式大小：

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // 公式及独立公式周围的间距，按1.4的排法

1.5的其他规则变化也可能让页面移动：标题的断行、行内图周围的间距（正文中和框内）、标题的行内标记、首字下沉的大小、冒号行之下为它引出的列表保留的空间、框的切口在段落或列表项中留下的行数、破折号之后的断行、齐左文字的断行、标题下段落的拆分、复合词连字符之后的断行，以及:::paragraphs容器下方的间距。migrateConfig与配置所排的markdown一起运行一次，就会固定这段文字需要的那些规则，公式大小也包括在内（见postext 1.4及以前写出的文件包）：

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // 标题断行、公式、行内间距、标题标记、首字下沉、冒号行、框的切口、破折号断行、复合词断行、齐左断行、标题下的拆分和容器间距，按1.4的排法

这样能挡住这些规则变化会造成的移动，但不能保住1.4的每一页。1.5还修正了排版错误，而修正没有固定开关：旧配置和新配置一样会得到修正，所以受影响的页面仍可能移动。其中包括：没有自己版面设计的通栏标题按整页宽度测量，并用所在层级的行距排；标题版面设计中，首字下沉的基线下面不再预留空间；首字下沉采用该部分的调色板颜色，即使设计文字的overflow不是'wrap'也会排出，此时文字折行；框内的段落按测量时的字距绘制；拆分的框在每个片段上都保留图标栏；框内某一行如果要把空格拉宽到3倍以上，就改为齐左，与正文一样；松散段落的调节手段不会让两端对齐的行宽于maxWordSpacing所允许的宽度；浮动的框保留比浮动体间距更大的marginBottom（在顶部区域）或marginTop（在底部区域）；带字距的居中或右对齐设计文字（书眉、章首页标题）按字母定位，不计最后一个字母之后的字距；在通栏章首页之下，第二栏开头的文字从紧接章首页下方的文字所在位置开始，章首页后面跟着标题时也是如此；在会把连续圆点的字偶间距拉开的字体中，目录的引导点也停在页码之前；书眉按标题的原文读取，标题某一行在连字符或破折号之后结束、或结束在因宽度而切开的单词内部时，不留空格（MEDIOAMBIENTALES，而不是MEDIOAMBIENTALE S），标题版面设计的{titleText}也同样读取（thousand-colour，而不是thousand- colour）；锚定在标题版面设计色带底部或中部的文字，会让色带保持足够的高度来容纳它，不再压到标题上方的文字上；比所在行更宽、在自带的连字符旁被切开的单词，从这个连字符之后切开，不再加第二个连字符；嵌套在另一列表中的列表之后的那一项，用它自己所在列表的itemSpacing，而不是嵌套列表的；因比所在行更宽而被切开的单词，其余部分保留自己的断点，所以网址继续在连接处断开，复合词继续在连字符处断开，而不是按词典的音节断开。

pinLegacyMathSize把缩放比例乘以1.1312（0.5 ÷ 0.442），并把以em计的独立公式外边距除以同一系数。对含独立公式的书，只改缩放比例不够：它们的外边距是以公式自身大小计的长度，会同样增大13%，把下面的文字往下推。按默认外边距写出来，这三个值是：

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // 公式与1.4排出的一样大，周围留出1.4留的间距

对于已保存的配置，引擎能识别出来并替你完成这一步：openBundle / readBundle处理1.5之前写出的.postext文件包（见postext 1.4及以前写出的文件包），沙盒处理当时保存的书、工作副本和postext-config.json文件（见沙盒 → 持久化）。它们都经过migrateConfig读取，由它固定公式大小（pinLegacyMathSize）：fontSizeScale变为保存的缩放比例（未设置时为1）× 1.1312，以em或rem计的独立公式外边距（以公式自身大小计的长度）除以同一系数，所以独立公式周围的间距保持1.4的样子（默认的0.8 em变为0.7072 em）。以页面单位（pt、mm……）计的外边距保持不变，enabled: false的配置或书中没有$的配置也保持不变。这样旧书就按1.4的方式排版，它的math部分显示实际使用的大小。要按现在的大小排这样的书，就把这些值重置：在沙盒中是公式 → 缩放比例、独立公式上边距和独立公式下边距，在代码中是：

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // 现在的大小和外边距

**带编号的公式。**带\tag{…}的独立公式占满它的行长（所在的栏，或所在标注框的内宽）：公式居中，编号右对齐排在公式所在的行上，align中每个带标签的行都是如此。\tag*{…}按原样打印标签，不加括号。只有显式标签才打印编号；equation之类的环境本身不编号。比行长更宽的带编号公式向右溢出，与其他独立公式一样。（postext 1.4及以前，带\tag的公式根本不会绘制。）

解析函数和精简函数与其他部分一致：

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#启动公式引擎

MathJax按需加载，不随引擎的其他部分一起加载。在主线程上排版时，要在构建含公式的文档之前启动它：

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // 只加载一次MathJax；之后的调用立即完成
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• **引擎运行之前，公式是占位符。**每个公式排成一个估计大小的灰色框。如果在从未调用initMathEngine()的情况下排版含公式的文档，控制台会显示一条警告说明这一点。
• 排版工作线程会替你启动它。postext/worker中的构建在markdown包含$时会自行调用initMathEngine()。
• 先排版，就绪后再排一次。isMathReady()告诉你引擎是否在运行。onMathReady(fn)在引擎就绪后调用fn一次（已经就绪则立即调用），并返回一个取消这次调用的函数。编辑器可以先显示占位符，等MathJax加载完再重新排版；initMathEngine()加载期间不会打印警告。
• **失败。**MathJax无法加载时，initMathEngine()返回的Promise会被拒绝，之后再次调用会重试。
• **任何打包工具、Node或CDN。**MathJax作为一个预先打包的模块随包发布（压缩前约1.8 MB，只由initMathEngine获取）。直接写import { initMathEngine } from 'https://esm.sh/postext'就能用，不需要?bundle。mathjax-full包只在构建postext时需要，所以安装postext不会安装它。MathJax及其打包的mhchem解析器采用Apache-2.0许可证：它们的声明和许可证文本随模块一起发布，位于dist/math/THIRD_PARTY_LICENSES.txt。
• **一个页面一个引擎。**同一JavaScript realm中所有导入postext的代码共享引擎及其已渲染公式的缓存（见同一页面共享的全局状态）。

文档一侧的语法（$...$、$$...$$、转义美元符号本身）见文档格式。

#脚注

footnotes属性设置以[^id]引用的注释放在哪里、如何编号、外观如何。标记写法见文档格式。

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd'; // 引用所在栏的栏底，或章末。
  numbering?: 'chapter' | 'document';  // 每章重新开始，或连续编号。
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd：注释排在栏底，或紧接正文之下。
  fontSize?: Dimension;       // 注释字号；em为正文字号。
  lineHeight?: Dimension;     // 注释行距；em为注释字号。
  color?: ColorValue;         // 注释颜色；未设置时为正文颜色。
  textAlign?: TextAlign;      // 未设置时为正文的对齐方式。
  hangingIndent?: Dimension;  // 注释转行的缩进。
  spaceBetween?: Dimension;   // 两条注释之间的间距。
  spaceAbove?: Dimension;     // 正文与分隔线之间的间距；em为正文字号。
  spaceBelowRule?: Dimension; // 分隔线与第一条注释之间的间距。
  separator?: {
    enabled?: boolean;        // 画出分隔线。
    width?: number;           // 分隔线长度，占栏宽的比例。
    lineWidth?: Dimension;    // 分隔线粗细。
    color?: ColorValue;       // 未设置时为注释颜色。
  };
}

footnotes: {
  fontSize: { value: 7.5, unit: 'pt' },
  lineHeight: { value: 9.5, unit: 'pt' },
  hangingIndent: { value: 0.8, unit: 'em' },
  separator: { width: 0.25, lineWidth: { value: 0.4, unit: 'pt' } },
}

栏底注释的排版方式：

• **注释与引用同栏。**放置一行之前，版面会加上这一行首次引用的注释的高度（如果是该栏的第一条注释，还要加上分隔线）。一行的注释在它下面排不下时，这一行连同段落的其余部分移到下一栏，并遵守段首孤行和段末孤行规则。栏的文字区域缩小注释所占的高度，所以各栏齐底和章末收尾区域只计算正文。
• 多条注释在同一栏中按引用顺序堆叠在一条分隔线下。后面再次引用的注释保持原编号，不再重复排出。
• **底部浮动体。**注释排好之后才占据栏底的图，放在注释上方；图之后排的注释放在图的上方。
• **框。**在标注框（行内、浮动或固定）中引用的注释，放在框后正文继续的那一栏的栏底，通常就是同一栏。收尾整个文档的框，把它的注释留在正文结束那一栏的栏底。
• **限制。**注释从不拆分：比一栏还高的注释会溢出。题注、表格单元格和标题中的标记不会被识别（按原样打印）。
• **输出。**Canvas、HTML和PDF都会绘制注释、标记（上标数字）和分隔线。在PDF中，每个标记链接到对应的注释；带标签的PDF把每条注释设为Note元素，带有唯一的/ID，列在结构树的/IDTree中（PDF/UA-1）。注释是设置了footnoteNote的VDTBlock，位于page.floats中；分隔线位于page.footnoteAreas中。
• 警告。undefinedFootnote（标记没有定义：编号印在一条空注释上）和unusedFootnote（没有标记引用的定义：不会排出）。

解析函数和精简函数与其他部分一致：

import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults } from 'postext';

#东亚排版

cjk属性决定中文、日文和韩文的排版方式：遵循哪个地区的规范，行在哪里可以断开，标点排多宽、是否悬挂，汉字与拉丁字母之间的间距，版心的字格，以及文中的着重号、专名线、注音和夹注怎样印出。每个字段都是可选的；'auto'跟随文档语言（locale）所属的地区，因此locale: 'zh-Hant'的书无须任何其他设置，就会按台湾的做法断行和排标点。中文排版按地区逐一说明这些设置背后的规则，并给出两套完整的配置。

interface CjkConfig {
  region?: 'auto' | 'mainland' | 'taiwan' | 'hongkong';   // 地区规范。
  lineBreak?: 'auto' | 'none' | 'basic' | 'gb' | 'strict'; // 哪些标点不能出现在行首或行尾。
  punctuationWidth?: 'auto' | 'fullwidth' | 'kaiming' | 'lineEndHalf' | 'halfwidth';
  compressAdjacent?: 'auto' | boolean;      // 相邻的两个标点共占1.5 em。
  trimLineStart?: 'auto' | boolean;         // 位于行首或行尾的括号去掉外侧半个字的空白。
  hangingPunctuation?: 'none' | 'allow' | 'force';
  latinSpacing?: Dimension;                 // 汉字与拉丁字母之间；默认0.25 em。
  uprightDigits?: 0 | 2 | 3 | 4;            // 竖排：数字直立排进一个字格；默认2。
  grid?: { enabled?: boolean; charsPerLine?: number; linesPerPage?: number; show?: boolean };
  emphasis?: 'auto' | 'italic' | 'dots';    // *…*对汉字的效果。
  bookTitleMark?: 'auto' | 'brackets' | 'wavy' | 'none'; // :book[…]印出什么。
  annotationColor?: ColorValue;             // 着重号和专名线、书名线；默认为文字颜色。
  ruby?: { fontFamily?: string; fontSize?: Dimension; color?: ColorValue; position?: 'auto' | 'over' | 'under' | 'right' };
  warichu?: { fontSize?: Dimension; color?: ColorValue; open?: string; close?: string };
}

各级别共同的规则：

• ——和……是一个两字宽的整体，从不拆开；两个这样的整体连在一起时，二者之间可以断开。
• 数字与其符号和单位不分开（¥5,999、50%、50％、120㎡），中间隔着空格时也一样（−3 ℃、50 %）；拉丁单词也保持完整：夹在中日韩文字之间的西文作为一段不可在内部断行的文字排出，除非这段文字本身比行长还宽（这时在音节处加连字符断开，或在能排下的最后一个字符处断开；网址在其连接处断开）。单位组合字符㎡ ㎏ ㎞ ㏄（U+3371–337A、U+3380–33DF、U+33FF）属于其数字所在的那段文字，不会让拉丁文段落变成中日韩段落。
• 用全角数字和字母写的数字或单词（１２３４５６、５０％、￥５９９、３．１４、１２：３０、ＡＢＣ）同样不拆开；两端对齐的行仍像拉开汉字那样拉开这些字符。
• 词间空格只在规则允许的地方才是断行点：下一个字符不能出现在行首（参见图表 （ 第三章 ）绝不会让）排在行首），或者空格前的最后一个字符不能出现在行尾时，不在这里断行。
• 脚注标记、:ref以及上标、下标与前面的字符连在一起。
• 全角空格U+3000是一个一字宽的字符：可以在它之后断行，不能在它之前断行；它从不拉宽，在行首也不会被去掉。中文段落的首行缩进两字，请设置bodyText.firstLineIndent: { value: 2, unit: 'em' }，不要输入两个U+3000（解析器会去掉段落开头的全角空格）。

一个字符排不进本行、又可以出现在下一行行首时，它移到下一行，两端对齐的行把剩下的字符拉开。它不能出现在下一行行首时（逗号、闭括号、开括号后面的字符），本行先尝试挤压把它收进来（挤进，clreq §6.2.2.3）：如果能让出的空白（见标点宽度）足以抵消超出的部分，这个字符（连同必须跟着它的标点，例如句号后的闭引号）就留在本行，本行排满行长。否则本行让出字符（推出）：断行点退回规则允许的上一个位置，两端对齐的行把剩下的字符拉开。如果行比一个数字加上其后的句号还窄，行尾放什么都不合规则，最终还是在句号之前断行。

这些规则适用于哪些段落：中日韩字符（汉字、假名、注音符号、谚文）多于词间空格的段落，即使其中没有两个中日韩字符相连（第1条、第2条、价¥5,999。好）。紧挨着中日韩字符或标点的空格不算词间空格：2026 年 9 月 28 日与2026年9月28日排法相同。这些段落逐行排版，无格式和带格式的路径都一样，因此含有一个粗体词的段落与不带粗体的同一段文字断行完全相同。引用了中文书名或人名的拉丁文段落空格多于中日韩字符：它保留最优断行，在其中的中日韩字符旁按同样的规则断行。题注、表格单元格、注释和标注框也按文档设定的级别断行。词典断词不作用于中日韩段落中的拉丁单词。

两端对齐的中日韩行（段落最后一行除外）按以下顺序拉满行长（clreq §6.2.2.4）：先拉宽西文单词之间的空格，每处最多半个em；再拉宽汉字与拉丁字母之间的间距，每处最多半个em；然后把所有字符间隙和这些空格平均拉开。拉丁单词、数字和两字长的标点内部不加间距，连接号和斜线旁边也不加。间距按行中的片段设置（VDTLineSegment.tracking，每个字符之后的px值，计入片段的width），Canvas、HTML和PDF输出将其绘制为字距；后面带有间隙的拉丁单词，其最后一个字母单独成为一个片段。一个片段包含一段西文，或者样式、链接和间距相同、前进宽度一致的字符，因此沙盒放置光标时把片段宽度平均分配给这些字符，链接也只覆盖自己的字符。当一行字符之间需要超过半个em的间距（设置了bodyText.maxJustifyTracking时则为超过该值）时，这一行按该上限排出，达不到行长：该行标记为cjkLoose和ragged，构建时报告一条cjkLooseLine内容警告，附带该行文字。常见原因是一个无法移到上一行的长拉丁单词或网址。不含中日韩字符的行（长网址的开头部分）按左对齐不齐行排出，不报警告，与只有一个单词的拉丁文行一样。参见断词与两端对齐。

#标点宽度

一个全角中文标点由半个em的字形和半个em的空白组成，设置调整的是空白，从不调整字形（clreq §6.3.2）。开括号和开引号的空白在字形之前，闭括号和闭引号的空白在字形之后；大陆的点号、，。．；：？！位于字身框的一角，空白也在字形之后；台湾和香港居中的标点（、，。．；：）以及间隔号在两侧各留四分之一em。横排时，台湾和香港的？！仍占一个em；竖排时，各地的：；？！都占一个em。大陆的间隔号在任何样式下都是半个em，在两种书写方向上都居中（GB/T 15834，clreq §5.1）：全角字形两侧的空白都去掉，竖排时它的字格本来就是半个em。

开启compressAdjacent时，相邻的两个标点去掉二者之间的空白（clreq早期草案中的八条规则）：闭括号在另一个闭括号或大陆的点号之后（。」，但不在台湾和香港居中的标点之后），点号在闭括号之后（」，），开括号在上述任何标点或另一个开括号之后（，「、》（、「『），以及间隔号与其前的闭括号或其后的开括号之间去掉四分之一em。挤压后这一对最少也占1.5 em：开明式下。”本来就占1.5 em，保持不变，》（占一个em。无论是否开启compressAdjacent，开明式都把句号的空白移到紧随其后的闭引号之后：两个字形挨在一起，半个em排在引号后面（。”␣母，而不是。␣”母），位于行尾时与句号的空白一样处理。开启trimLineStart时，行首的开括号去掉前面的空白，墨迹与文字边缘对齐（段落第一行的开括号落在缩进内半个em处）；行尾的闭括号去掉后面的空白。居中的标点两侧各去掉四分之一em，从不在一侧去掉半个em。在两个标点之间断行时，二者都不再挤压：各自按行首或行尾的标点处理（全角，后面的「排到下一行行首时，这个，在本行行尾占满一个em）。

一行收进一个不能出现在下一行行首的字符（挤进）时，要看它还能让出的空白是否足以抵消超出的部分，按clreq的顺序：词间空格缩到四分之一em，然后是间隔号、括号、句内点号，汉字与拉丁字母的间距缩到八分之一em，最后是句末点号，每一步平均分摊。kaiming只允许句末点号缩到半个em，而且只在这种情况下：如果一行只是还差一个字才排满，就把这一行拉开，因此。？！在行内保持一个em。lineEndHalf允许每个标点缩到半个em；fullwidth的标点什么都不让出（全角式的书保持字格），halfwidth的标点已无可让。

拉丁文与中文共用的标点（“ ” ‘ ’ … — ·）在中文里占中文标点的字身框，与字体本身的前进宽度无关：LXGW WenKai把“ ”画成0.35 em宽，Noto Serif SC的破折号为0.89 em，·为三分之一em。当两侧最近的字符（跳过其他这类标点）有一个是中文，或者旁边没有西文时，它们就按中文标点处理。开引号的字形位于一em字身框的末端，闭引号的位于开头；间隔号、省略号和单个破折号居中；成对的省略号（……）按字体把两个连排的方式排出，并在两个em中居中。破折号（——）是一条不间断的线：每个破折号从字体自身的侧边距起拉伸到占满它的em，两笔在衔接处重叠，并升到字符的中线（VDTLineSegment.inkScale，仅作用于绘制的缩放）。之后样式像处理其他标点一样调整字身框。两侧都是西文时（他说：He said “yes” and left.），它们保留字体的前进宽度；本来就是一个em宽的字形不受影响。

渲染器不让浏览器自己的标点间距进入文字。Chrome在一次测量或绘制中遇到两个相邻标点时，会把前一个排成半宽（Noto Serif SC中的本）》录因此是3.5 em），所以相邻的两个标点分开测量和绘制；中日韩文字的HTML行带有text-spacing-trim: space-all和text-autospace: no-autospace，并关闭chws、halt和vchw特性。

在VDT中，让出了空白的标点单独成为一个片段，其width是它保留的前进宽度，并设置inkOffset（px）：渲染器在x + inkOffset处绘制它的字形，因此在字形之前让出空白的标点（行首的开括号）绘制在字身框之前那么远的地方（偏移为负）。排在中文字身框中的共用标点记录字形在框中的位置，减去它之前让出的空白，这个值可能为正。PDF用字符间距显示这样的字形，使其前进宽度在字身框结束处结束，阅读器因此不会看到它压到下一个字符上，并把所在行放进一个/ActualText区段（见汉字与拉丁字母间距）。标点的空白在哪一侧由地区决定，与字体无关：请用对应地区的字体排书（大陆用Noto Serif SC，台湾用TC，香港用HK）；在大陆标签下使用繁体字体，居中标点会压缩错误的一侧。

#标点悬挂

hangingPunctuation: 'allow'允许、，。．中的一个（大陆的标点位于字身框起始处，因此还包括；：？！）在本来要排到下一行行首、而挤压又收不进本行时，悬挂到行尾之外；横排的台湾和香港文字从不悬挂，因为居中的标点看起来会像被切掉（竖排时可以）。竖排时，悬挂的标点位于行的下端之外。'force'让这类标点只要位于行尾就悬挂（段落最后一行除外），排不下时立即悬挂。标点与另一个标点相接时从不悬挂（。」、，「）。悬挂的片段标记为hangs；行的bbox.width、两端对齐和对齐方式都不计入它，Canvas和PDF把栏的裁剪区加宽最宽的悬挂标点的宽度（hangingPunctuationOverhang），因此它不会被切掉。多数中文图书不使用标点悬挂；clreq只建议在使用字格时采用。

#汉字与拉丁字母间距

latinSpacing（默认四分之一em）在汉字（或假名）与相邻的拉丁字母或欧洲数字之间加入间距：用iPhone拍照和1999年排成用 iPhone 拍照和1999 年。行首和行尾不加，拉丁字符与中文标点之间不加（用iPhone，在逗号前不加任何间距），中文括号内侧不加（（iPhone）），紧挨着非字母非数字的符号时也不加（为¥5,999）。作者在这种边界处输入的空格（用 iPhone 拍照，许多网络文本都这样写）会被汉字与拉丁字母间距取代，而不是叠加，因此两种写法排出来一样；不换行空格和全角空格保持原样。在两端对齐的行上，它先增大到最多半个em，然后才拉开字符；在要收进一个不能出现在下一行行首的字符的行上，它缩小到最少八分之一em。以em以外的单位给出的长度按页面的dpi换算。0表示关闭，这时在该处输入的空格仍是词间空格。

这个间距是一个kind: 'space'的片段，标记为autospace，其text为空（或者是作者输入的空格）；它的width是最终值，渲染器自己的空格两端对齐不会改动它。它从不进入纯文本，因此搜索、复制粘贴和源文本范围读到的都是原文。PDF把每一个分段排出的行（拉开的字符、汉字与拉丁字母间距、让出空白或悬挂的标点）放进一个/Span，其/ActualText是该行的文字，因此文本提取读到的是用iPhone拍照，而不是用 iPhone 拍 照，含半宽标点的行也读成一行。

#竖排中的数字

竖排时，拉丁单词和较长的数字横倒排，较短的数字直立，各位数字并排放进一个一em的字格：即纵中横（縱中橫，clreq §2.1.3，CSS text-combine-upright）。uprightDigits设定这样的数字最多可以有几位：2（默认）、3、4，或0表示不使用。2026年9月28日在2之下：2026横倒，9直立，28直立并排在一个字格中。

• 整个数字要么全部直立，要么全部不直立：在2之下，三位数保持横倒，从不拆开。
• 与拉丁字母相接的数字（A4、mp3、3D）留在它的单词里，横倒排；带小数点或数字分组的数字（3.14、10,000）也一样。
• 拉丁文句子中的数字跟随句子：两侧都是拉丁单词时，它与单词一起横倒（printed in 49 and 32 copies、chapters 49, 32 and (7) of）。向两侧查看时，跳过空格、其他数字、注释标记、横倒文字中的标点（, . : ; ( ) ' " - /）、短破折号和长破折号以及弯引号（pages 3–5 of、the “49” copies），直到遇到第一个字母或汉字。其标点通向中文的数字直立（上午12:30:45开会、比分为3:2:1、见图(3)所示、他住在"12"号楼）；紧挨着汉字或中文标点的数字，无论有无空格，也直立（第 3 回、用iPhone 15拍攝、第3 copies）；旁边是直立符号的数字（a 30×40 print）以及位于段首或段尾、只有一侧有单词的数字（49 copies were printed、on page 7.：要让它横倒，请写:sideways[…]）同样直立。段落作为一个整体来读，跨越换行、强调和链接。
• 紧挨着Unicode规定直立排的符号时，每个数字各占一个字格：30×40是30、×、40，全部直立。
• 字符多到一个em放不下的字格会在横向压缩到一个em；字距和两端对齐从不进入字格内部，只作用于它之后。
• 断行和两端对齐时，这个字格算作一个汉字，周围不加汉字与拉丁字母间距。
• 测量器和每个渲染器找到的字格都相同：Canvas把数字转回直立并压缩后绘制，PDF用横排字体同样处理，HTML则用text-combine-upright: all包裹它们。

手动设置时，有三个行内标记在竖排中覆盖这一设置，在横排中不起作用（见文档格式 › 竖排中的文字方向）：

第:tcy[120]回、:upright[GDP]與:sideways[12]

:tcy[…]把其中的文字排进一个直立的字格，:upright[…]让每个字符各自直立占一个字格（拉丁字母在其中居中），:sideways[…]把整段文字横倒，包括汉字。在VDT中，:tcy文字是一个tcy: true的片段，一个em宽；:upright或:sideways文字带有orientation。由uprightDigits排进一个字格的数字不带标记：用verticalRuns(graphemes, region, uprightDigits)可以找到它们。在段落中，与拉丁单词一起横倒的短数字带有orientation: 'sideways'，如同写了:sideways[…]：它所在的片段不一定包含与它一起横倒的那些单词。

#字格

中文版心以字数来规定（clreq §7.1.1）：正文字号 × 每行字数 × 每页行数，再加上行间距，双栏时还有栏间距。grid就按这种方式设定：

cjk: { grid: { enabled: true, charsPerLine: 28, linesPerPage: 28, show: true } }

enabled时，配置在被读取之前就会改写：每栏宽为charsPerLine个bodyText.fontSize的em，版心高为linesPerPage行bodyText.lineHeight；layoutType: 'double'时，栏间距为layout.gutterWidth取整到整数个em，至少一个。page.margins中的页边距作为最小值：版心放在它们留出区域的正中，每个页边距在其方向上增加剩余空间的一半（镜像页边距的书保留内外页边距的差别，二者增加相同的量）。未设置时，charsPerLine和linesPerPage取能排下的最大值。超出能排下的数值会减小到能排下的值，并报告一条cjkGridClamped配置警告。字号和行距保持原值。在oneAndHalf版式中，charsPerLine指主栏；侧栏取最接近sideColumnPercent在所配置页边距内给出宽度的整数个em（至少一个），栏间距按双栏的方式取整，并改写sideColumnPercent，使两栏都按整数个em切分。竖排时（layout.writingMode: 'vertical-rl'），一行的字符沿页面向下排，各行横向排列，因此charsPerLine量的是页面高度，double版式得到上下叠放的两栏，叠加显示的字格立在字符居中的轴线上。

中文出版实践中的两种版式，五号字（10.5 pt），行间距6 pt（lineHeight: 16.5pt）：

• 大32开，140 × 203 mm，28 × 28：行长294 pt（103.7 mm），版心高462 pt（163 mm）；内外页边距16/20 mm、上下页边距18/20 mm的page.margins能容纳它。
• 16开，184 × 260 mm，双栏，每栏23字，小五（9 pt，行距13.5 pt），栏间距两个字：2 × 207 pt + 18 pt。

show在版心上绘制字格（稿纸）：在页面的每一栏（oneAndHalf的侧栏位于页面奇偶所决定的一侧）的每一行上，每个字位画一个浅灰色方格（即字符围绕基线的字身框），在Canvas和HTML中都显示。PDF只在renderToPdf收到characterGrid: true时才绘制它：它只是屏幕上的辅助工具。cjkGridGeometry(config)返回一份配置设定的字格（实际使用的数值、页边距、版心），applyCjkGrid(config)返回改写后的配置。

#着重号、注音与夹注

中文标记、注音与夹注的标记把文字留在段落中：搜索、目录、索引锚点和复制的文字读到的都是原文字符，只有字符周围绘制的内容取决于这些设置。

• 着重号（:dots[…]，以及emphasis: 'dots'下汉字上的*…*）每个字加一个点，居中于该字（不计两端对齐的间距），从不加在标点或空格上：横排时在字下，竖排时在字右（clreq §5.3.1）。style选择实心点、空心圆或芝麻点，fill="open"绘制轮廓，pos="over|under"选择一侧。
• 专名线和书名线（专名号:name[…]，bookTitleMark: 'wavy'下的书名号:book[…]）画在字身框下方（竖排时在左侧），跨过线内的空格。两段相接处，各自的端点让出八分之一em，因此:name[賈寶玉]:name[林黛玉]读起来是两个名字。着重号和线标在同一侧标注同一段文字时，线离文字更近。在'brackets'下，《》是参与断行的文字，像其他字符一样绘制和复制；它们不占纯文本或源映射中的字符（这些片段标记为inserted）。
• 注音排在行间空白中，贴着基字的字身框，居中于基字；含拉丁字母（拼音）且位于基字上方的注音，升高其字体下伸部（g、j、p、q、y）的深度再加正文的0.04 em，使其不碰到基字，同一行的所有注音保持同一条基线；比基字宽的注音会加宽基字的框，但减去它可以伸到相邻无注音字符上的四分之一注音em；两个注音之间至少相隔四分之一注音em（两个注音符号注音之间为四分之一符号em，因此两个字各配三个符号时仍留在各自的字格中）。单字注音（每个字一个读音）可以在字之间断行；词组注音从不断开。在行首或行尾，基字和注音对齐到边缘（clreq §5.5.4）。横排时，注音符号在每个字右侧排成一列，字的框随之加宽；竖排时，同样的一列沿字的右侧向下排。声调符号位于这一列右侧，其墨迹的一半高出最后一个符号的顶端（clreq §5.5.3.3），按墨迹定位，因为字体把这些符号排在字身框中偏高的位置；竖排时它直立，与第一个符号上方的轻声点一样。
• 夹注（双行夹注）按夹注字号折成两行，在本行中居中，两行之间没有间隙。上一行持续收字，直到至少容纳这一部分的一半，因此下一行永远不会更长；如果下一行会以不能出现在行首的标点开头，上一行再多收一个字。一行剩余空间排不下的夹注先填满本行，再接到下一行、下一栏或下一页；它的括号只排在第一行之前和最后一行之后。竖排时，上一行是右边的一行，先读。

行距从不改变：着重号、线标和注音都位于行间空白中。如果一个段落的行间空白（行距减去字号）在一侧有标注时不足半个em，或在两侧都有标注时不足八分之五em（clreq §5.6.1），会报告一条cjkMarksExceedLeading内容警告；注音高于行间空白（拼音注音连同其升高量一起计算）的段落报告rubyExceedsLeading。请给这样的段落一个行距更大的段落样式。

在VDT中，带标注的片段带有cjkMarks，排版把着重号和线标作为VDTLine.marks放在各行上（点、圆圈、芝麻点、直线和波浪线，位于该行的排版方向坐标系中），Canvas、HTML和PDF按原样绘制（PDF：Artifact /Layout；HTML：aria-hidden框，带着重号的文字放在<em>中）。注音基字的片段带有ruby（注音及其各段），注音把基字拉开时在inkOffset处绘制基字；夹注在一行上的部分是一个片段，其text先是上一行、再是下一行，其warichu保存渲染器实际绘制的两行。带标签的PDF把注音放进其基字Ruby的RT中，把夹注放进Warichu中，该行的/ActualText读出基字文字，夹注只读一次。着重号、注音和夹注在正文、标题、列表和标注框中绘制；题注、表格单元格和设计元素中的文字保留原文，但不绘制这些标注。

解析函数和精简函数与其他部分一致；setCjkLineBreak和setCjkComposition为在buildDocument之外进行的测量设定级别和排版方式（标点宽度、悬挂、汉字与拉丁字母间距；cjkCompositionOf(resolved.cjk, dpi)），buildDocument则根据配置设定它们。在构建之外，标点保留完整的前进宽度，也不加汉字与拉丁字母间距：

import { DEFAULT_CJK_CONFIG, resolveCjkConfig, stripCjkDefaults, cjkRegionOf, setCjkLineBreak, setCjkComposition, cjkCompositionOf } from 'postext';
 
resolveCjkConfig(undefined, 'zh-HK');
// { region: 'hongkong', lineBreak: 'basic', punctuationWidth: 'fullwidth', compressAdjacent: true,
//   trimLineStart: true, hangingPunctuation: 'none', latinSpacing: { value: 0.25, unit: 'em' }, uprightDigits: 2,
//   grid: { enabled: false, charsPerLine: 0, linesPerPage: 0, show: false },
//   emphasis: 'dots', bookTitleMark: 'wavy',
//   ruby: { fontSize: { value: 0.5, unit: 'em' }, position: 'auto' },
//   warichu: { fontSize: { value: 0.5, unit: 'em' }, open: '', close: '' } }

在沙盒中，这些设置位于版面设计 › 书写系统 › 东亚排版。

#资源类型

资源类型是可由用户定义的类别，如图、表、示意图、代码清单……它决定该类资源如何编号、如何加题注、如何被引用。类型列表存放在config.resourceTypes中；沙盒在设计 → 图与表 → 编号与位置中编辑它。

未设置config.resourceTypes时，Postext提供两个内置默认类型：图和表，二者都按{h1}.{n}编号（每遇到一级标题重新计数），计数器为十进制。它们的名称采用文档语言：先取config.locale，没有则取bodyText.hyphenation.locale，再没有则用英语（见文档语言）。

内置默认类型会随语言区域变化。导出的defaultResourceTypes(locale = 'en')把类型名称、简写标签和题注前缀本地化为文档的语言区域：英语得到Figure/Fig.和Table/Tab.；西班牙语得到Figura/Fig.和Tabla/Tabla；法语、德语、意大利语、葡萄牙语、加泰罗尼亚语和荷兰语也各有对应名称（列在文档语言的表中）。es-ES这类带地区的标签按语言解析，没有译名的语言区域回退到英语。编号行为（numberingTemplate: '{h1}.{n}'、resetOn: 'h1'、十进制计数器）与语言无关。每次调用都返回新对象，因此可以随意修改结果：

import { defaultResourceTypes } from 'postext';
 
const types = defaultResourceTypes('es');
// => [{ id: 'figure', name: 'Figura', shortLabel: 'Fig.', captionPrefix: 'Figura',
//       numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal', … },
//     { id: 'table',  name: 'Tabla',  shortLabel: 'Tabla', captionPrefix: 'Tabla', … }]