配置：正文与标题

#正文

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' } },
}

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

#诗歌

各行不带半行分隔符的:::verse诗逐行排（见文档格式 › :::verse）。bodyText.verse给出这类诗的默认值；诗的开始标记上同名的属性只对该诗生效。

bodyText: {
  // 转行靠右并加方括号；短歌不拆分。
  verse: { turnover: 'right', keepStanzas: 5 },
}

在这些设置出现之前保存的配置（configVersion为8或更早），如果其中有不带分隔符的诗，读取时使用layout: 'bayt'，诗保持postext 1.22给出的居中排法。用postext 1.23保存的配置（configVersion为9），如果其中有逐行排的诗，读取时使用tighten: false，诗行仍在1.23转行的地方转行。

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

#制表位

bodyText.tabStops列出制表符可去的制表位：:tab，或设有制表位的段落中的制表符字符（标记写法和一行如何排，见文档格式 › 制表符与制表位）。段落样式的tabStops在它的段落中替换这些制表位，标注框样式的body.tabStops在它的框内替换；空列表表示不设制表位。每个制表位是一个TabStop：

bodyText: {
  tabStops: [
    { position: { value: 30, unit: 'mm' } },
    { position: 'end', align: 'end', leader: '.', leaderGap: { value: 2, unit: 'pt' } },
  ],
  tabInterval: { value: 10, unit: 'mm' },
}

tabInterval在列表的最后一个制表位之后，从版心起始边起每隔一个间隔再加一个制表位；没有它时，越过最后一个制表位的制表符是词间空格。文字中输入的制表符字符只在样式（它自己的或正文的）设了制表位或间隔的段落中才是制表符；在其他地方，它仍是原来的词间空格，所以保存过的文档版面不变，不需要锁定版本。

制表位与配置的其余部分一起检查（见配置警告）：制表位中的未知键（leaders）报告为unknownConfigKey，并给出最接近的键；不属于四个取值的align报告为unknownConfigValue，该制表位按'start'排；既不是长度、'end'也不是百分比的position报告为unknownConfigValue，used: 'none'，该制表位被略去。

前导符的颜色和字体取段落的，目前还没有单独的设置。

#首字下沉

正文段落可以以首字下沉开头：第一个字母放大，排在段落的前几行旁边，这几行让出字母的宽度和一段间隙，其余照常排（用Knuth-Plass断行、两端对齐、断词）。段落样式给样式中每个:::paragraphs组的第一段加上首字下沉（设each: true时每一段都加，适合条目式的目录）；标题级别或标题样式给标题后的第一个正文段落加上首字下沉（见按级别覆盖、段落样式和标题样式中的dropCap字段）。标题后的这一段与indentAfterHeading的找法相同，会越过容器围栏、指令、离开文字流的框和浮动图；框、列表项、引文、诗或注释中的段落从不带首字下沉。在文字中，写在标题行或:::paragraphs围栏上的{dropcap}、{dropcap=false}和{dropcap=N}为该章或该组开启、关闭首字下沉，或设定它的行数（见文档格式 › 首字下沉）。自postext 1.23起。

headings: {
  levels: [
    { level: 1, dropCap: { lines: 3, fontFamily: 'Libre Bodoni', fontWeight: 700, color: { hex: '#8b2e2a', model: 'hex', paletteId: 'accent' }, leadIn: { words: 3 } } },
  ],
},

首字的排法：

• 字号：文字和首字的大写字母高度都从各自的字体中测量（取H的墨迹；在中文或日文文字中取首字本身的墨迹），不提供墨迹度量的字体按字号的0.72计算大写字母高度。默认字号适合任意一对字体，所以不需要逐个字体修正。设计文本的dropCap仍按固定的0.72计算（见文本元素）。
• 首字与它所在的词：首字取完整的字素簇。第一个词的其余部分紧接在它之后，不加空格；单字母词（A、Y）在第一行开头保留它的词间空格。段落自身的首行缩进取消。复制、搜索、源映射和沙盒的光标都按原文读这一段：块的纯文本包含这个字母，第一行的plainStart从它之后计数，VDTBlock.dropCap在含第一行的片段上记录它的范围和几何信息。
• 升起首字（lines: 1配上更大的fontSize，或sink小于lines）高出第一行，段落在上方为高出的部分留出整条网格线的空间，所以不会压到上方的文字。
• 断开：段落从不在第sink行之前断开，而是整段移到下一栏或下一页；只有当它单独位于一个放不下这几行的空栏中时，才照样断开，并引发dropCap警告。与正文保持在一起的标题会把这几行留在自己下面。在下一栏接排的部分不带首字，各行排满全宽；如果为另一宽度的栏再次断开，前几行保留缩进。各栏齐底可以像对待其他段落一样把这一段排松或排紧，但从不在缩短的行之间加空白。
• 文字：各行在起始一侧缩短：拉丁文字在左边，阿拉伯文和希伯来文在右边。与下一个字母相连的字母（阿拉伯文、叙利亚文、N'Ko）不单独排出，段落引发dropCap警告；横排的中文和日文取一个字的首字（首字下沉）。竖排文字不带首字下沉（给出警告）。不以字母或数字开头的段落（引用、公式、注释标记）也不带（给出警告）。
• 输出：Canvas、HTML查看器和固定版式EPUB把首字画在各行旁边；HTML把它写在第一行文字的紧前面，中间不隔任何东西，所以屏幕阅读器把这个词作为一个整体读出。在带标签的PDF中，首字属于段落的P，并与它所在词的其余部分组成一个Span，其/ActualText就是这个词：提取文字时读出Long before，而不是L ong before。流式EPUB把它排成CSS的initial-letter（行数、下沉），阅读系统不支持时改为浮动。

这些设置与配置的其余部分一起检查（见配置警告）：首字下沉或其引导词中的未知键报告为unknownConfigKey；不属于其取值的punctuation或shortParagraph，以及不是从1起的整数的lines、sink或characters，报告为unknownConfigValue，并使用默认值。首字下沉默认关闭，所以已保存的文档都不会改变。

#每个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为中国大陆）。日文接受ja、ja-JP、ja-Jpan以及其他任何ja标签（isJapaneseLanguage(tag)）；从postext 1.16起，它有自己的内置文字和自己的地区japan，其排版默认值遵循JLReq（见日文排版）。字符串表中没有日文条目时，给出的是英文，而不是中文。localeScript(tag)、cjkRegionOf(tag)、stringsKeyOf(tag)和sameContentLocale(a, b)给出这些判断结果，DOCUMENT_LANGUAGES列出带内置文字的语言，每种语言都用它自己的语言命名（日本語排在各个中文条目和العربية之间），与沙盒“文档语言”下拉框中的显示一致。

题注前缀是类型的名称（Figure 1.1.）。中文类型在章内编号，用连字符连接，即{h1}-{n}（图 1-1）；配合题注设置labelNumberGap: ''和labelSeparator: '　'，题注显示为“图1-1　标题”（见题注样式）。索引同样跟随语言：简体中，交叉引用前用“见”和“另见”，符号和数字条目上方的标题为“符号”和“数字”；繁体中则为“見”“另見”“符號”和“數字”。日文类型同样这样编号，不必设置这两项，题注就排成図1-1　題，交叉引用写作第3章、2.3節和12ページ，参考文献标题为参考文献；索引在符号和数字条目上方用“記号”和“数字”作标题，交叉引用用箭头写出：见写作→夏目漱石，另见在页码之后写作→夏目漱石、森鷗外も見よ，竖排时这些标签直立。阿拉伯文类型同样按{h1}-{n}编号（شكل 2-3），交叉引用写作الفصل 3、القسم 2-1和ص 12，参考文献标题为المراجع，索引使用انظر / انظر أيضًا、رموز和أرقام，并用阿拉伯文逗号和分号（، ؛）。

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

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

文档数字

顶层的numerals决定引擎输出的所有数字所用的数字系统：页码，以及目录、索引和页码引用中的页码标签；有序列表和脚注的编号；标题和章的计数，{chapterNumber}；图号及其引用中的{h1}与{n}；{totalPages}、{bookTotalPages}和{numberDecimal}。'latn'输出0–9，'arab'输出阿拉伯-印度数字٠–٩，'arabext'输出波斯数字۰–۹。只有十进制格式受影响——decimal、列表的arabic或保持默认的设置——作者指定的格式照原样输出：lower-roman仍是i、ii、iii，拉丁文文档中的arabic-indic仍输出١、٢、٣。文档正文从不改写。

默认值'auto'取locale的数字（defaultNumeralsFor(tag)）：不带地区或地区不在马格里布的阿拉伯语（ar、ar-EG、ar-SA、ar-AE……）为'arab'；ar-MA、ar-DZ、ar-TN、ar-LY、ar-MR和ar-EH为'latn'；波斯语（fa）、普什图语（ps）和印度乌尔都语（ur-IN）为'arabext'；其他语言，包括巴基斯坦乌尔都语，均为'latn'。CLDR对不带地区的ar和ar-AE给出latn；马什里克和海湾地区的阿拉伯文图书印的是٠–٩，Postext以图书为准。标签中注明数字系统的（ar-MA-u-nu-arab）照其所注。以文档数字编号的页面把arabic-indic或persian记为pageNumberFormat，PDF页码标签因此显示相同的数字。未知的值按语言处理，并报告为unknownNumerals。

作者输入的数字三种数字系统都能读取：列表项٣.从3开始，{startAt=٥}、:::numbering{startAt=٥}、:::space{lines=٢}和:::part{number="٣"}（用于{numberDecimal}）都能读出其值。

const config: PostextConfig = { locale: 'ar' };                     // ١، ٢، ٣
const maghreb: PostextConfig = { locale: 'ar-MA' };                 // 1, 2, 3
const forced: PostextConfig = { locale: 'ar', numerals: 'latn' };   // 1, 2, 3

文本方向

顶层的direction设定文档的基本方向：'ltr'、'rtl'或'auto'（默认值）。'auto'在locale的文字从右到左书写时（阿拉伯文、波斯文、乌尔都文、希伯来文、叙利亚文、塔纳文、恩科文、阿德拉姆文等，由directionOf(tag)判断）为'rtl'，否则为'ltr'。从右到左的文档在镜像的版框中排版：各行从右边开始，第一栏在右边，缩进、列表标记、浮动体、脚注和框都位于右侧，page.binding: 'auto'让它在右侧装订。只有这样的文档，解析后的配置才带有direction: 'rtl'，所以从左到右的文档解析结果与以前相同。未知的值按'auto'读取，并报告为unknownConfigValue。Unicode双向算法（UAX #9）在两种方向中都安排每行各段的顺序：英文书中的阿拉伯文引文在原位从右到左读。

在文档内部，标题或:::容器可以带{dir=ltr}或{dir=rtl}，行内的:ltr[…]和:rtl[…]把一段文字隔离开（见标记中的文本方向）；表格资源可以设table.direction。与文档方向相反的块保留自己的起始侧：它的缩进、列表标记和末行的齐边都移到其文字开始的一侧。

凡是指明某一侧的设置，指的都是文字或文字流的一侧，而不是纸面的一侧，所以为英文书做的设计在书改为阿拉伯文后照样可用。'start'和'end'可以作为明确的名称使用：

placement.rotate在镜像页面上保持物理含义：顺时针旋转的图在纸面上也是顺时针旋转。读取版面的宿主程序可以在每页找到镜像版框（带direction: 'rtl'的VDTPage.flow，pageIsMirrored(page)），在VDTLine.order中找到每行各段的视觉顺序；flowToPage和pageToFlow在文字流与纸面之间换算。见阿拉伯文排版。

const arabic: PostextConfig = { locale: 'ar' };                        // 从右到左，右侧装订
const english: PostextConfig = { locale: 'en', direction: 'rtl' };     // 强制设定；很少需要

#语言与文字

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

• 中文：段落中的CJK字符多于词间空格时，由CJK排版器处理：行在字符之间断开，遵守cjk.lineBreak的避头尾规则（行首不出现。、」或ー，行尾不出现「或（），——和……不拆开，数字连同其符号、拉丁文单词都保持完整；两端对齐的行在字符之间均匀分配空白以填满行长。标点宽度、标点悬挂、汉字与拉丁文之间的间距、字符网格、着重号、专名号和书名号、注音以及割注，都按locale的地区处理，横排（沿行）和竖排（layout.writingMode: 'vertical-rl'）都一样。只引用少量CJK词语的拉丁文段落保持最优断行，并可以在这些词语旁边断行；拉丁文中引用的CJK括号、间隔号或全角符号（〈h〉、％）不影响任何处理。
• 日文：使用同一个排版器，从postext 1.16起有自己的规则，即W3C《日文排版需求》（JLReq）和JIS X 4051的规则：ja语言区域得到japan地区，其auto值设定JLReq的禁则级别（小假名和ー从不出现在行首）、带相邻标点挤压的全角标点、？！之后的一个字宽、占缩进后半个字宽的段首括号、文字上方的芝麻点、『』书名号、按1:2:1排开的振假名、日文编号、注释以及按读音排序的索引。更早的版本按中国大陆中文的默认值排日文。
• 韩文：使用同一个排版器，不断词，但采用中国大陆中文的默认值：它自己的规范（KLREQ）尚未实现。韩文除了在空格处断行，也在音节之间断行。
• 阿拉伯文及其他从右到左的文字（波斯文、乌尔都文、希伯来文等）从右到左排，具体做法见阿拉伯文排版。文档的direction由locale的文字决定，Unicode双向算法安排每行中拉丁词和数字的顺序，书在右侧装订、第一栏在右边，引擎生成的每个数字都采用该地区的数字。含阿拉伯字母的词从不断词、加字距或切开，两端对齐的阿拉伯文行在空格处和用卡希达（kashida）拉伸。元音符号、强调、脚注和阿拉伯文的内置文字见阿拉伯文。波斯文、乌尔都文和希伯来文有方向、数字和整词规则，但没有自己的内置文字。

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

#阿拉伯文

以下设置服务于阿拉伯字母文本；对用其他文字书写的文档，它们都不起作用。阿拉伯文排版把它们与阿拉伯文书籍的其余部分（方向、装订、数字、诗体、目录和索引）放在一起说明。

• 元音符号与行距。 标注元音的文本中，元音符号（fatḥa、kasra、shadda、tanwīn、短竖alif、《古兰经》符号）叠在字母上下，位于行距之中，而行距不会为它们增高。每个带元音符号的行都会记下笔画伸到多远（VDTLine.markInk），渲染器的栏裁剪会把每栏首行和末行的符号包含在内。某个词上方的符号碰到上一行正上方那个词下垂的字母或符号时，构建会报告该段落（arabicMarksExceedLeading，显示在沙盒的检查面板中）。只比较上下相叠的词。部分标注元音的文本宜用约1.7–1.85 em的lineHeight，全部标注元音的诗句宜用1.9–2.1 em。
• 强调。 阿拉伯文字体没有斜体，所以在locale用阿拉伯字母书写的文档中，*…*默认排成粗体（bodyText.emphasis: 'auto'）。'color'把它排成正体并用italicColor，'overline'在词上加一条线，即阿拉伯文书籍中的khaṭṭ fawqī。该设置作用于所有用正文字体排的文本：段落、列表、引用块、段落样式、提示框正文、注释和标题。图注、表格单元格、目录和索引保留各自的斜体设置。无论选哪种，引擎都不会把阿拉伯字母排斜：斜体片段中的阿拉伯文词排成正体，其中的拉丁文词保持斜体。在这类文档中，引用块默认为正体。
• Tashkīl。 bodyText.tashkil: 'strip'从排版文本中去掉元音符号和《古兰经》符号，用于由标注元音的底本制作不标元音的版本：fatḥa、ḍamma、kasra及其tanwīn、sukūn、shadda、短竖alif（هٰذا变成هذا），以及U+0656–U+065F和U+06D6–U+06ED的符号。'strip-vowels'保留shadda，大多数现代书籍就是这样印的。hamza和madda保留（أ إ آ是字母，用组合符号输入时也一样）。源文本保留其符号；行、标题和目录不带符号排出，每个排出的字符仍对应它在源文本中的位置。
• 脚注。 footnotes.markerTemplate: '({n})'用文档数字写出注码「(١)」，numbering: 'page'让编号每页重新开始，noteNumberPosition: 'inline'把注文自己的编号排在行内。分隔线和注文编号位于栏的起始一侧，在从右到左的书中即右侧。
• 整词。 含阿拉伯字母的词从不断词、切开或加字距，无论是在阿拉伯文书中还是被其他语言的书引用。为阿拉伯文文本设置letterSpacing的样式会被报告（joiningScriptLetterSpacing），比所在行还宽的词会溢出该行并被报告（unbreakableWordOverflow）。见阿拉伯文排版。
• 卡希达与诗体。 两端对齐的阿拉伯文行除了在空格处，还用卡希达拉伸（bodyText.kashida，见阿拉伯文的卡希达）；古典诗用:::verse排成每行一联、两个等宽的半行（见:::verse）。
• 索引。 阿拉伯文索引按字母顺序排序，并忽略冠词ال（index.ignoreArticle）、元音符号和hamza的承载字母；见索引。

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

这些缺陷值背后的机制见断词与两端对齐。本节是驱动它们的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. 有安全区的图片：设了安全区（Resource.safeArea，见文档格式 › 安全区）的图片，如果以行内方式排在短栏里，或者作为只占这一栏的浮动体排在栏顶或栏底，就按整数个网格行增高，在安全区以内裁切，直到这一栏排满，或者裁切到了安全区为止。图片变高不会在页面上留下空洞，所以这一手段在增加任何空白之前执行；在栏首要保持平齐的页面或区段上（见下文），位于栏顶的浮动体不会增高。记录为flexFigure。这一手段没有单独的设置：只有资源标出了安全区的图片才会增高。
3. 标题：在短栏内各标题的上外边距中增加整数个网格行。需要多行且栏内有多个标题时，这些行分配给各个标题，最重要的标题总是分得最多（h2比h3多）。位于栏顶的标题从不加空，因此各栏始终从页面顶部开始。唯一的例外是：在文字流继续到下一页的页面上，紧接在栏首图或表下方的标题，空间会加在这个标题上方、图的下方。
4. 列表结尾：标题无法吸收全部空余时，在列表或编号列表结束处增加一个网格行（列表后的空白读起来很自然），每个列表结尾有上限。
5. 放松段落：作为最后手段，把栏内某一段重新断行，使其多出一行（即TeX的\looseness=+1），并选最长的段落，让增加的词间距分散得看不出来。只有每一行都保持在bodyText.maxWordSpacing以下时，放松后的方案才会被采用，文字灰度绝不超出你已配置的限度。需要启用bodyText.optimalLineBreaking。

在字符网格上（cjk.grid，见中文排版 › 字符网格），每个字占一个一em宽的格子，每一行都落在网格的行距上，这个行距同时也是基线网格。和竖排一样，网格上默认不做齐底：在网格上逐行排的页面，就像GB/T 9704按每页22行、每行28字计数那样，短栏就保持短栏。配置中设了enabled: true时，使用的是保持网格的手段：标题、列表结尾、行间公式和图都按整数个网格行加空，其下的文字整行下移；对于没有空行可让的标准，gridLines: 'off'把这些手段排除在外。中文或日文段落只有在任意两个字之间的间距都不超过maxTracking时才多排一行，也不对其中的字符另加字距：少一个字的行要把一个em分摊到各个字间，远超默认的0.01 em，所以在由整格组成的网格上，放松段落的手段通常找不到可用的段落。结束一栏的框和有安全区的图片本来就不受网格约束，在这里与在别处一样起作用。

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

哪个手段起了作用

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

在字符网格上，文档会说明某一栏为何可能短一截：页面在网格上、配置又没有开启齐底，因而齐底关闭时，doc.gridBalancing为{ off: true }；齐底运行但不带整行手段时，它为{ gridLines: 'off' }。仍然偏短的栏带有column.gridRefused，即网格不允许它使用的手段（段落只有把字匀开到格子之外才能多排一行时为'looseParagraph'，在gridLines: 'off'下则是各个整行手段）。不在网格上时两者都不存在。

interface VDTBalancing {
  levers: BalanceLever[]; // 通常只有一个：列表后的段落可能既占用列表结尾那一行，又多排一行
  spaceAbove: number;     // 间距手段在块上方增加的px（只有looseParagraph或flexFigure起作用时为0）
  bodyGrowth?: number;    // flexFigure：图片增高的px，在安全区以内裁切
  extraLines?: number;    // looseParagraph：段落多出的行数
  tracking?: number;      // looseParagraph：多出这些行所用的字距，单位为千分之一em（0 = 仅靠词间距）
}
type BalanceLever = 'trailingCallout' | 'flexFigure' | '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；更大的数字以阿拉伯数字输出。

阿拉伯文数词与所计名词的性一致，因此后缀可加修饰：阴性名词用-feminine（或-f），阳性名词用-masculine（-m，默认）；-classical把百写作مائة（布拉格版和多数埃及版的写法），而不是现代的مئة。{1:ordinal}输出标题所用的带冠词主格序数词：الفصل {1:ordinal}输出الفصل الأول、الفصل الحادي عشر、الفصل الحادي والعشرون；الليلة {1:ordinal-feminine}输出الليلة الأولى、الليلة الحادية عشرة、الليلة الحادية والعشرون、الليلة المئتان，超过一百时采用古典的“在……之后”格式：الليلة الخامسة والأربعون بعد الثلاثمئة、الليلة الحادية بعد الألف。{1:words}输出基数词（واحد وعشرون；阴性为إحدى عشرة、واحدة وعشرون）。序数词拼写到9 999，基数词到99 999；修饰可以组合（{1:ordinal-f-classical}），其他语言忽略修饰。阿拉伯文没有大小写，因此后缀的大小写不起作用。设计占位符{numberWords}和{numberOrdinalWords}输出阳性形式；阴性的章首请把序数词放在该级的模板中，再用{number}输出。

在标题设计中，{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; // 让独立公式与引出它的那一行在一起。
  equationNumbering?: {      // 为带\label的独立公式编号。
    enabled?: boolean;           // 默认true
    numberingTemplate?: string;  // '{n}'；'{h1}.{n}'按章编号
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})'：公式和\eqref印出的形式
  };
}

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 } // 现在的大小和外边距

带编号的公式。带编号的独立公式占满它的行长（所在的栏，或所在标注框的内宽）：公式居中，编号右对齐排在公式所在的行上，align中每个带编号的行都是如此。编号来自\label{eq:x}（postext 1.19起）：带标签的公式，以及align、gather、alignat、flalign或eqnarray中带标签的行，按阅读顺序依equationNumbering编号，除非该行写了\nonumber或\notag。equation之类的环境本身不编号：没有标签的公式就没有编号。\tag{…}把你给的标签加上括号打印出来，\tag*{…}按原样打印；两者都不参与计数，与它并列的\label为它命名。比行长更宽的带编号公式向右溢出，与其他独立公式一样。（postext 1.4及以前，带\tag的公式根本不会绘制；1.18及以前，只有\tag能为公式编号。）

正文中的\eqref{eq:x}按format印出编号(3)，\ref{eq:x}印出不带括号的编号；:ref{id="eq:x"}和@eq:x也是如此（见交叉引用）。在公式内部，\eqref把编号作为文字印出。逐章排版的书中，计数器接着上一章继续：continuationAfter通过LayoutContinuation.statementCounters（equation）把它带过去，全书大纲为每个标签给出编号（OutlineEntry.numberLabel），所以对另一章中公式的引用也能印出编号。

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1)、(1.2)……(2.1)
}

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

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的代码共享引擎及其已渲染公式的缓存（见同一页面共享的全局状态）。

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