# 配置：标题

> 标题的默认值、各级覆盖、标题前分页、通栏的章首页，以及以文字书写的编号

- HTML版本: https://postext.dev/zh/docs/configuration-headings
- 最后更新: 2026-10-16
- 阅读时间: 22分钟
- 其他语言: [en](https://postext.dev/en/docs/configuration-headings.md), [es](https://postext.dev/es/docs/configuration-headings.md), [ca](https://postext.dev/ca/docs/configuration-headings.md), [de](https://postext.dev/de/docs/configuration-headings.md), [fr](https://postext.dev/fr/docs/configuration-headings.md), [it](https://postext.dev/it/docs/configuration-headings.md), [pt](https://postext.dev/pt/docs/configuration-headings.md), [ja](https://postext.dev/ja/docs/configuration-headings.md), [ar](https://postext.dev/ar/docs/configuration-headings.md)

## 简单来说

本页讲标题的设置。你可以给所有标题设定字体、字号和颜色，也可以只改某一级，比如章标题。你可以决定一个标题是否另起一页，以及这一页必须在左边还是右边。章标题可以用自己的设计横跨整个页面宽度。标题编号可以用文字书写，比如“第一章”。

## 标题

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

### 通用默认值

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `fontFamily` | `string` | `'Open Sans'` | 所有标题的字体。 |
| `lineHeight` | `Dimension` | `1.2 em` | 标题的行距，比正文更紧。 |
| `color` | `ColorValue` | 主色（`#295AA3`） | 标题文字颜色。它绑定到默认调色板的`main-color`条目，换掉调色板里的这个颜色，所有标题都随之改色。 |
| `textAlign` | `'left' \| 'justify' \| 'center' \| 'right' \| 'start' \| 'end'` | `'left'` | 所有标题级别的对齐方式（没有按级别设置的值）：齐左、两端对齐、居中或齐右。两端对齐的标题像段落一样把最后一行排成齐左，所以单行标题看起来与`'left'`相同。Canvas、HTML和PDF以同样方式放置各行，编号前缀也包括在内。没有高级设计的`span: 'page'`标题，其默认章首区段也遵循这一设置（两端对齐时排成齐左）；高级设计则用各文本元素自己的`align`对齐。 |
| `fontWeight` | `number` | `700` | 标题的字重（100–900）。 |
| `marginTop` | `Dimension` | `1.5 em` | 标题上方的间距。开栏的标题会去掉这段间距（见`columnHeadSpace`）。 |
| `marginBottom` | `Dimension` | `0.5 em` | 标题下方的间距。 |
| `keepWithNext` | `boolean` | `true` | 为`true`时，标题绝不会成为一栏或一页的最后一个元素。如果标题之后的空间放不下后续块的至少`bodyText.widowMinLines`行（`bodyText.avoidWidows`为`false`时为一行），标题就被推到后面，与正文保持在一起。它与`bodyText.keepColonWithList`相互配合：如果那条规则必须把以冒号结尾的段落整段推走，栏末的标题会随它一起移动，不会被孤零零地留下。 |
| `keepWithNextSpread` | `boolean` | `false` | 与`keepWithNext`同时使用时，仍允许标题位于偶数页最后一栏正文的末尾，因为它的正文从同一跨页对面的奇数页开始（JLReq §4.1.7）。跨页的划分是：第1页单独一页，然后是2–3、4–5……，按`pageIndexOffset`计数，左侧装订和右侧装订的书都一样。从postext 1.16起提供。 |
| `keepWithNextSplit` | `'rules' \| 'fill'` | `'rules'` | 当标题落在栏底、而把其下段落整段推走会把标题留在原处时，该段落如何拆分。`'rules'`：放得下多少行就放多少行，前提是标题下至少留`bodyText.widowMinLines`行，且至少有`bodyText.orphanMinLines`行转入下一栏；没有同时满足两者的拆法时，标题随段落一起移走，空出的位置由各栏齐底来填补。`'fill'`：放得下多少行就放多少行，不管转入下一栏的有多少，所以一个四行段落在有三行空间时拆成3 + 1。postext 1.4及以前，所有标题都这样拆分，`configVersion` 8之前保存的配置也保持这种方式（见[postext 1.4及更早版本写出的文件包](https://postext.dev/zh/docs/configuration-bundles.md#postext-14及更早版本写出的文件包)）。关闭`avoidWidows`或`avoidOrphans`时，规则中相应的一侧就不再适用。 |
| `snapToGrid` | `boolean` | `true` | 标题之下的文字流是否重新对齐基线网格。为`true`时，标题的`marginBottom`向上取整为整数个网格行；为`false`时保留精确的间距，标题下的文字可能偏离网格，直到下一个对齐点（列表结束处、`:::paragraphs`的末尾、行间公式）。许多书在标题下留一行半，就是这种排法。级别（`levels[].snapToGrid`）或标题样式可以设置自己的值，这里的值是它们继承的默认值。 |
| `columnHeadSpace` | `'none' \| 'remainder'` | `'none'` | 对齐网格的标题在开栏时（位于页首，或位于栏首的图或表之下）保留多少上方空白。`'none'`：去掉全部空白，标题排在该栏第一行，与旁边一栏的栏首平齐；对齐网格时所需的不足一行的空白放在标题下方，因此正文与它的距离可能比段落之后的标题更远。`'remainder'`：只去掉整数个网格行的空白，剩下不足一行的部分留在标题上方，正文与它的距离同段落之后的标题一样；标题比栏首略低一些开始，正文各行都不移动。适合单栏的书，因为旁边没有栏首可以比出差别。其他取值都按`'none'`处理。不用于通栏章首之下的栏，也不用于`span: 'page'`、带`lineSpan`、隐藏或带设计（`advancedDesign`）的标题。自postext 1.28起。 |
| `inlineMarks` | `boolean` | `true` | 标题是否像段落一样识别行内标记：`*italic*`、`**bold**`、`^superscript^`、`~subscript~`、`:smallcaps[…]`和链接。斜体片段会翻转标题的倾斜，所以在斜体标题中它显示为正体；粗体片段采用`bodyText.boldFontWeight`，若标题自身的字重更重则采用标题字重。目录也会列出粗体和斜体片段；书眉和PDF书签只输出文字。为`false`时去掉标记，文字按标题自身的样式输出，与postext 1.4及以前一样。没有设计的`span: 'page'`标题，其默认章首区段也会排出粗体、斜体、上标和下标片段；标题设计（带设计的章首区段或栏内`advancedDesign`）都把`{titleText}`作为纯文本输出，除非其文本元素读取行内标记（`inlineMarks: true`）：此时`{titleText}`保留标题的粗体、斜体与上下标片段（postext 1.19 起）。更早保存、且标题中带有标记的配置按`false`读取（见[postext 1.4及更早版本写出的文件包](https://postext.dev/zh/docs/configuration-bundles.md#postext-14及更早版本写出的文件包)）。 |
| `balancing` | `ColumnBalancingConfig` | 启用 | 纵向的各栏齐底：在标题上方加空，使各栏底端与页面底部平齐。见下文。 |

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

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

传入`headings`对象时，你没有重新声明的级别默认值都会保留，包括H1的分页（见[按级别覆盖](https://postext.dev/zh/docs/configuration-headings.md#按级别覆盖)）。

### 按级别覆盖

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

| 级别 | 默认字号 | 默认`breakBefore` |
| --- | --- | --- |
| H1 | `18 pt` | `{ enabled: true, parity: 'always-odd' }` |
| H2 | `15 pt` | `{ enabled: false, parity: 'any' }` |
| H3 | `12 pt` | `{ enabled: false, parity: 'any' }` |
| H4 | `10 pt` | `{ enabled: false, parity: 'any' }` |
| H5 | `9 pt` | `{ enabled: false, parity: 'any' }` |
| H6 | `8 pt` | `{ enabled: false, parity: 'any' }` |

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

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

```ts
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条目中加一个字段：

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

如果配置是存储下来的，引擎能识别出来并替你处理：沙盒处理它当时保存的书和配置（见**沙盒 → 持久化**），`openBundle` / `readBundle`处理postext 1.4或更早版本写出的`.postext`文件包（见[postext 1.4及更早版本写出的文件包](https://postext.dev/zh/docs/configuration-bundles.md#postext-14及更早版本写出的文件包)）。你自己存储的配置可以交给`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及更早版本写出的文件包](https://postext.dev/zh/docs/configuration-bundles.md#postext-14及更早版本写出的文件包)）。如果只处理分页，调用`pinLegacyHeadingBreaks(config)`即可。

按级别覆盖支持与通用默认值相同的属性，即`fontSize`、`lineHeight`、`fontFamily`、`color`、`fontWeight`、`marginTop`、`marginBottom`、`snapToGrid`，另外还有以下仅限级别的字段（[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)也可以使用它们）：

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `italic` | `boolean` | `false` | 以斜体渲染标题，在`fontWeight`之上叠加。 |
| `textTransform` | `'none' \| 'uppercase'` | `'none'` | 把标题文字转为大写（编号前缀保持原样，其中的行内标签和`:ref`的标签也一样）。转换不改变长度，使编辑器的源码映射保持一一对应：大写形式会变长的字符（`ß` → `SS`）保持不变。转换后的标题也用于高级设计和章首页的`{titleText}`占位符。PDF书签保留原写法的标题，即*Author contributions*而不是*AUTHOR CONTRIBUTIONS*，就像CSS的`text-transform`不改变文字本身一样（postext 1.4及以前书签用的是大写）。 |
| `letterSpacing` | `Dimension` | `0` | 标题每个字形之后的字距，包括空格和编号前缀，等同于CSS的`letter-spacing`。正值拉开字母（用`textTransform: 'uppercase'`排的大写字母通常需要一点：`{ value: 0.12, unit: 'em' }`），负值收紧大字号标题。`em`值相对于该级别的`fontSize`。标题各行按加了字距的文字测量，所以在加字距后的文字结束处换行，Canvas、HTML和PDF的绘制结果相同。字距从不改变字形：字体的合字（fi、fl）在所有输出中都保留。居中或齐右的行按字母定位：像设计文本一样不计最后一个字形后的字距，因此居中标题与`span: 'page'`标题的默认章首区段对齐。由`advancedDesign`绘制的级别会忽略它，与此处其他排版字段一样：每个设计文本元素有自己的`letterSpacing`。[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)也可以设置它，作用于使用该样式的标题。postext 1.4及以前标题没有字距设置，这个键会被悄悄丢弃。 |
| `lineSpan` | `number` | 未设置 | 占行（行取り，JLReq §4.1.6）：标题排在由这么多正文行组成的带中，文字在带中居中，取代`marginTop`和`marginBottom`；`3`就是3行取り的标题。标题对齐网格时，带从一条正文行开始，其后的文字仍留在网格上，两种书写方向都是如此，使用`cjk.grid`时也一样；标题本身需要更多行时，取下一个整数行。居中的是字符的中心（基线减去字体的表意字中心），这是JLReq的量法，而不是行框的中心。不用于章首页标题（`span: 'page'`）、由`advancedDesign`绘制的标题、隐藏的标题和标注框内的标题。标题样式可以设为`0`来取消其级别的设置。从postext 1.16起提供。 |
| `indent` | `Dimension` | `0` | 标题从行首缩进的距离（字下げ），`em`指**正文**字号，因为日文书按正文字数计算标题缩进（JLReq §4.1.3）：`{ value: 6, unit: 'em' }`就是6字下げ，与标题的字号无关。行长相应变窄，居中的标题在剩余部分中居中。从postext 1.16起提供。 |
| `firstLineIndent` | `Dimension` | `0` | 只缩进标题的第一行，从`indent`处算起，与它一样以**正文**字号的 em 计：长标题转行后的各行从`indent`处起排（未设时从行首起排），正如 GB/T 9704 让各级标题空两字、回行顶格：`{ value: 2, unit: 'em' }`。开启`cjk.grid`时，两个正文 em 就是网格的两格。带编号的标题在缩进之后印出编号，所以编号模板不必写全角空格，否则这些空格也会印进目录和 PDF 书签。竖排（从行首即行的上端算起）、CJK 排版器（标题开头的前括号与段落一样遵守行首规则）和 Knuth–Plass 断行都适用。居中的标题像居中的段落一样处理：第一行在缩进之后余下的宽度里居中。在标题文字后写`{firstLineIndent=N}`只设定这一个标题，`{firstLineIndent=0}`取消其级别的设定。从postext 1.24起提供。 |
| `jidori` | `number` | 未设置 | 均排（字取り）：比标题**自身**字宽的这么多倍窄的单行标题，均匀拉开到恰好这个宽度，所以`3`把序章排作序　章。更宽的标题和多行标题保持原样。在标题文字后写`{jidori=N}`只设置这一个标题，`{jidori=0}`关闭其级别的均排。从postext 1.16起提供。 |
| `dropCap` | `ParagraphDropCap \| false` | 无 | 该级别标题之后第一个正文段落开头的首字下沉（见[首字下沉](https://postext.dev/zh/docs/configuration-text.md#首字下沉)）：设一次，每一章都有首字。标题用`{dropcap=false}`关闭它，或用`{dropcap=2}`设定它的行数。自postext 1.23起。 |
| `numberingTemplate` | `string` | `''` | 该级别自动编号的模板。标记`{1}` … `{6}`输出对应标题级别的当前计数，可以加后缀指定格式：`{1:I}`大写罗马数字，`{1:i}`小写罗马数字，`{1:A}` / `{1:a}`字母，`{1:01}`补零，`{1:words}`用文字拼写（*twenty-one*），`{1:ordinal}`序数词（*twenty-first*），`{1:一}`中文数字（日文文档中为日文数字：第百一章），`{1:〇}`逐位书写，`{1:壹}`大写数字，`{1:①}`带圈数字，或者[编号格式写法](https://postext.dev/zh/docs/configuration-page-layout.md#编号格式的写法)中的任一名称。其他文字按字面输出（`'Chapter {1}. '`、`'{1}.{2}'`、`'第{1:一}回'`输出第一百二十回；反斜杠转义字面的花括号）。计数仍为空的标记会连同相邻的分隔符一起省略。为空（默认）表示没有自动编号。生成的编号在文字流中加在标题前，用于高级设计槽位的`{number}`占位符（那里不再在前面加前缀），并显示在目录中。文字写法见[以文字书写的编号](https://postext.dev/zh/docs/configuration-headings.md#以文字书写的编号)；若某一级别中部分标题要用自己的模板，见[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)。 |
| `numberSeparator` | `string` | `' '` | 编号与标题之间的内容，用于栏内、`span: 'page'`级别的默认章首区段、输出标题行的书眉，以及PDF书签。一级标题的分隔符还用于在默认的篇页和目录默认的篇条目中连接篇的编号和标题。中文章回标题用全角空格或不用分隔符（`'　'`：第一回　甄士隱夢幻識通靈）。目录保留自己的编号列（`toc.levels[].numberGap`）。[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)可以设置自己的分隔符。像中文小说的对句回目那样用`\\`把标题分成两半时，单行形式（栏内、目录、书眉）在两侧都是中文或日文字符时用全角空格连接两半，否则用空格。 |
| `numberPosition` | `'before' \| 'replace'` | `'before'` | 生成的编号放在哪里。`'before'`：放在标题前，用`numberSeparator`连接。`'replace'`：编号就是整个标题，源文本里写的标题不印出，所以在`numberingTemplate: 'الليلة {1:ordinal-feminine}'`下，`# Night`印成الليلة الثانية。目录把编号列为该条目的标题（没有编号栏），页眉（`{chapterTitle}`、`{titleText}`）和PDF书签也读作编号；这样的标题`{number}`为空。只对有模板（级别的或其样式的）的编号标题生效，其他标题保留原标题。[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)可以设置自己的值，设为`'before'`可保留其级别会替换掉的标题。 |
| `breakBefore` | `HeadingBreakBeforeConfig` | H1：`{ enabled: true, parity: 'always-odd' }` H2–H6：`{ enabled: false, parity: 'any' }` | 在该级别每个标题前强制分页。`parity: 'odd'` / `'even'`进一步限定标题在跨页的哪一侧开始，必要时插入一个空白填充页（仍计入页码）。`'always-odd'` / `'always-even'`还保证在前面的内容与新标题之间至少有一个强制的空白分隔页（分隔页属于前一章；此外为满足奇偶而加的填充页属于新的一章）。当标题是文档的第一个块、且第一页仍为空时，不执行奇偶约束，标题照原样落在第1页。未设置的字段保留该级别的默认值：H1的`{ parity: 'odd' }`仍然分页。 |
| `hidden` | `boolean` | `false` | 结构性标题：它不输出任何内容，在栏内或标注框中不占空间（没有文字、没有外边距、没有章首区段），但其他作用与标题完全相同。它的`breakBefore`仍会开新页，它开启其样式的章节，它参与计数（除非其样式设为`numbered: false`），并会被`:::toc`列出、被`{chapterTitle}`书眉引用、在PDF中生成书签。适用于献词、题词页或版权页这类需要出现在目录和读者书签中、但页面上不显示标题的内容。应在[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)上设置，而不是作用于整个级别；单个标题可以用`{hidden="true"}` / `{hidden="false"}`覆盖。 |

```ts
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下方的空间向上取整为整数个网格行。标题样式也可以设置它，作用于使用该样式的标题。

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

### 前置分页

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

紧挨在这种标题前的`:::pagebreak`不会取代标题自己的分页：标题仍会在该指令所开的页之后执行奇偶约束，可能因此多出一个空白页。标题需要紧接在手动分页之后开始时，见[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)。

#### 奇偶取值

| 取值 | 行为 |
| --- | --- |
| `'any'`（默认） | 没有奇偶约束，标题直接从下一页开始。 |
| `'odd'` | 确保标题从奇数页（右页）开始。只有当自然的下一页为偶数页时，才插入一个空白页。 |
| `'even'` | 同上，但针对偶数页（左页）。 |
| `'always-odd'` | 保证前面的内容与新标题之间**至少有一个强制的空白分隔页**，然后确保从奇数页开始。适用于每一章都必须从新的跨页开始的情况。 |
| `'always-even'` | 同上，但针对偶数页。 |

#### 空白页的归属

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

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

带样式章节的书眉和调色板（见[标题样式](https://postext.dev/zh/docs/configuration-styles.md#标题样式)）在空白页上也遵循这两条规则。

#### 文档开头的例外

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

### 通栏与高级设计

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

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `span` | `'column' \| 'page'` | `'column'` | 为`'page'`时，标题被视为章首，其高级设计（如果启用）作为正文上方的章首区段附加到页面上。请与`breakBefore.enabled: true`搭配使用，确保章首总是开新页。没有自己的设计时，标题由默认章首绘制，横跨整个内容区，使用该级别的字体和行距，并带有粗体、斜体和上下标片段（`headings.inlineMarks`），区段也按这个宽度测量。区段容纳章首绘制的每一行：章首占用的行数多于标题本身按栏宽测得的行数时（两端对齐的标题本可压缩空格排成一行，或有强制换行`\\`），区段也把这些行包括在内。postext 1.4及以前，区段按栏宽折行的标题来测量，所以在内容区一行就放得下的标题会占两行高的区段，那一行居中其中。其他各栏与标题所在栏一样从区段下方开始。在这些栏开头的正文，与紧接在章首下方的正文起点相同，不论章首所在栏接下来是什么内容：即章首标题或设计下方的`marginBottom`，该级别对齐网格时取到下一个网格行。在这些栏开头的标题、行间公式或目录行，与章首下方第一个标题或行间公式平齐，外边距也按那里的计算；章首所在栏接下来是其他内容时，它们与那段文字的起点平齐。章首下方的隐藏标题不计入，[各栏齐底](https://postext.dev/zh/docs/configuration-page-flow.md#各栏齐底)在章首下方标题上方加的空间也不会在其他栏中重复。这些栏中对齐网格的内容落在页面的网格上。postext 1.4及以前，它们的第一个块紧贴区段底部：区段在两行之间结束时偏离网格；章首后面跟着标题时，则紧挨区段、没有外边距（区段结束在网格上时比现在高一行），那里的标题还丢掉了第一栏的标题所保留的上外边距。 |
| `spanBreak` | `boolean` | `true` | `span: 'page'`标题是否另起一页。`true`另起下一页（左右页由`breakBefore`决定）。`false`且`breakBefore.enabled: false`时，标题在正文排到之处展开，如同跨页框：上方各栏齐平收束（启用`headings.balancing.trailing`时对该区段做平衡），标题的设计或默认章首区段在其下方按版心全宽排出，正文在下方各栏继续：例如简报中的第二篇文章紧接在第一篇结尾之下。若剩余空间放不下标题及其下方的寡行最少行数，则与`true`一样另起下一页。页面角色仍由其第一个块决定。对`span: 'column'`标题无效。标题样式中也可设置。postext 1.19 起。 |
| `advancedDesign` | `HeadingAdvancedDesignConfig` | `{ enabled: false, slot: { elements: [] } }` | 该级别的自由组合设计槽位。`enabled`时，由槽位中的元素组成章首。在文本元素中用`{titleText}`输出标题文字；用`{number}`、`{numberRoman}`等插入格式化后的标题编号。 |
| `advancedDesign.minHeight` | `Dimension` | — | 在栏内文字流中为标题保留的最小高度。标题占用`max(design content bottom, minHeight)`，其下再加标题的`marginBottom`（取自其标题样式、其级别或`headings.marginBottom`；默认为标题字号的0.5 em），标题对齐网格时，总和向上取整到基线网格。因此，即使章首的元素很矮，或锚定在标题上方的页面或出血框上，章首也能把正文往下推（或占满整页）。要让区段正好高`minHeight`，把那个`marginBottom`设为0，并让`minHeight`为整数个网格行。只要`enabled`为true就生效，槽位为空也一样。设计内容底部如何计算，见[保留高度](https://postext.dev/zh/docs/configuration-headings.md#保留高度)。 |

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

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

```json
{
  "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*（见[以文字书写的编号](https://postext.dev/zh/docs/configuration-headings.md#以文字书写的编号)）。
- `{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.`：

```ts
{
  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`给标题留出所需的空间：

```json
{
  "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`可以描述每一项。另见[通栏与高级设计](https://postext.dev/zh/docs/configuration-headings.md#通栏与高级设计)下的**与页面一样高的章首**。

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

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

```md
# Annual report 2026 {style="cover"}

:::pagebreak

# Letter from the chair
```

### 以文字书写的编号

有两个编号模板后缀用文字书写计数，语言为文档语言（顶层的`locale`，否则用断词语言，见[文档语言](https://postext.dev/zh/docs/configuration-language.md#文档语言)）：`words`表示基数，`ordinal`表示序数。后缀的大小写决定文字的大小写，就像字母编号的`A` / `a`一样：

| 标记 | 英文（21） | 西班牙文（21） | 中文（21） |
| --- | --- | --- | --- |
| `{1:words}` | twenty-one | veintiuno | 二十一 |
| `{1:Words}` | Twenty-one | Veintiuno | 二十一 |
| `{1:WORDS}` | TWENTY-ONE | VEINTIUNO | 二十一 |
| `{1:ordinal}` | twenty-first | vigesimoprimero | 第二十一 |
| `{1:Ordinal}` | Twenty-first | Vigesimoprimero | 第二十一 |
| `{1:ORDINAL}` | TWENTY-FIRST | VIGESIMOPRIMERO | 第二十一 |

英文、西班牙文、法文、意大利文、德文、加泰罗尼亚文、葡萄牙文、中文、日文和阿拉伯文会用文字书写；其他语言采用英文词，与内置的表格续表字符串相同。中文按`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；更大的数字以阿拉伯数字输出。

法文采用传统拼写（*vingt et un*、*soixante et onze*、*quatre-vingts*、*deux cent un*），“一”的序数写作*premier*（*Chapitre premier*，但*vingt et unième*）；意大利文把每个数写成一个词（*ventuno*、*ventitré*、*duemilaventiquattro*；*primo*、*ventunesimo*），德文也一样（*einundzwanzig*、*hunderteins*；*erste*、*einundzwanzigste*），瑞士德文（`de-CH`）以*ss*代替*ß*；加泰罗尼亚文遵循IEC（*vint-i-u*、*dos-cents*；*primer*、*cinquè*、*vint-i-unè*）；葡萄牙文默认采用巴西用法（*dezesseis*），`locale`指明其他地区时采用欧洲用法（`pt-PT`：*dezasseis*），序数用拉丁式（*vigésimo primeiro*）。加泰罗尼亚文和葡萄牙文的序数与西班牙文一样，最多拼写到999。

罗曼语族各语言读取性的修饰：`-feminine`（或`-f`）使数词与阴性名词一致（意大利文`Parte {1:ordinal-f}`输出*Parte prima*，法文`{1:Ordinal-f} partie`输出*Première partie*；同样有*veintiuna*、*vint-i-una*、*duzentas*），`-masculine`（`-m`）为默认。德文基数不变（*Kapitel eins*），序数则会变化：不加修饰时用冠词后的词尾，三种性相同（`Das {1:ordinal} Kapitel`输出*Das erste Kapitel*）；在不带冠词的名词前，`-masculine`输出*Erster Teil*，`-feminine`输出*Erste Lektion*，`-neuter`（`-n`）输出*Erstes Kapitel*。德文数词按该语言的规则小写（`Kapitel {1:words}`输出*Kapitel eins*）；`{1:Words}`把首字母大写，用于位于标题开头的词，`{1:WORDS}`把ß写作SS。

阿拉伯文数词与所计名词的性一致，因此后缀可加修饰：阴性名词用`-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'`可给出大写：

```ts
// 西班牙文小说：标题上方为“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}', /* … */ },
  ] } } }
```