配置：资源与表格

#资源类型

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

未设置config.resourceTypes时，Postext提供三个内置默认类型：图、表和视频，各自独立按{h1}.{n}编号（每遇到一级标题重新计数），计数器为十进制。列表中没有video类型时（例如在有视频之前保存的书），类型为video的视频资源照样编号：引擎为它们补上内置的视频类型（effectiveResourceTypes(config, resources)），defaultVideoResourceType(locale)则单独返回这个类型。它们的名称采用文档语言：先取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', … },
//     { id: 'video',  name: 'Vídeo',  shortLabel: 'Vídeo', captionPrefix: 'Vídeo', … }]

type ResourceCounterFormat =
  | 'decimal'
  | 'roman-lower'
  | 'roman-upper'
  | 'alpha-lower'
  | 'alpha-upper';
 
type ResourceCounterReset = 'never' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
interface ResourcePlacement {
  position?: 'auto' | 'top' | 'bottom' | 'here'; // 浮动体可占用哪种空位；'here' = 在::resource指令处行内嵌入
  span?: 'column' | 'page' | 'side';             // 一栏、整个内容宽度，或只放浮动体的侧栏
  rotate?: 'ccw' | 'cw';                         // 旋转四分之一圈：横排的表单独占一页
  width?: number;                                // 栏宽或页宽的比例（0 < width < 1）；默认占满整个宽度
  align?: 'left' | 'center' | 'right';           // 比所在栏窄的浮动体放在哪里；默认'left'
  captionSide?: boolean;                         // 题注放在图旁，位于oneAndHalf版式的侧栏中（仅限栏内浮动体）
  columns?: number;                              // 'column'浮动体横跨的相邻栏数（1.18起）
  wrap?: 'none' | 'left' | 'right' | 'start' | 'end'; // 正文排在资源旁边，资源在栏的这一侧（1.24起）
  wrapGap?: Dimension;                           // 绕排资源与正文之间的距离（1.24起）
}
 
interface ResourceType {
  id: string;                          // 稳定的id，由Resource.typeId引用
  name: string;                        // 单数显示名称，例如"Figure"
  namePlural?: string;                 // 可选的复数形式，例如"Figures"
  shortLabel: string;                  // 行内引用用的简写标签，例如"Fig."
  numberingTemplate: string;           // "{h1}.{n}"或"{n}"
  resetOn: ResourceCounterReset;       // {n}计数器何时重新计数
  counterFormat: ResourceCounterFormat;// {n}的格式
  captionPrefix: string;               // 加在题注前面，例如"Figure"
  defaultPlacement?: ResourcePlacement;// 该类型资源的后备位置
}

ResourcePlacement与资源自身的placement形状相同。position选择浮动体可占用的空位种类：auto（默认）取第一次引用之后的第一个空位，top / bottom把范围限定在该种版带，here把资源行内嵌入。span设定浮动体的宽度范围：一栏、整个内容宽度，或一栏半版式中只放浮动体的侧栏。rotate把资源旋转四分之一圈，并使它成为单独占一页的通栏浮动体。width把浮动体收窄为所在栏宽的一个比例（通栏浮动体则为页宽的比例），比如宽栏里的一张小表。align说明这种较窄的浮动体放在哪里（默认靠左，也可居中或靠右），也说明比空位窄的图片在空位中的位置：比栏窄的位图，或被layout.fitFiguresToPage缩小的图像。题注和注释保持空位的行长。（postext 1.4及以前，这类图片总是左对齐排放。）captionSide把题注放在图旁，位于一栏半版式中只放浮动体的侧栏（layout.sideColumnRole: 'floats'），与图的顶边平齐（底部浮动体则与底边平齐）；它只作用于栏内浮动体，没有这种侧栏的页面仍把题注放在图下。资源和它的类型都没有设定位置时，内置默认值为auto / column。shrink（'never'、'page'、'slot'）和minScale（未设时为0.7）把浮动图片缩小到所在位置的空间，而不是移到后面；captionMeasure: 'body'让比所在位置窄的图片的题注和说明与图片同宽（见文档格式 › 位置）；layout.floatShrink给出前两项的文档级默认值。wrap把行内嵌入或宽一栏的浮动体放在栏的一侧，正文排在旁边，相隔wrapGap；layout.wrap存放默认值（见文档格式 › 文字绕排）。citingPage让top或auto浮动体置于其引用行所在页或栏的顶部，而不是引用行之后的第一个空位；layout.floatsAtCitingPage给出文档默认值，layout.maxTopFraction给出它可以占用的栏高比例（参见文档格式 › 位置）。

columns（postext 1.18起）让span: 'column'浮动体在多栏页面上横跨这么多相邻的栏，例如报纸五栏中横跨两栏的照片。它的宽度是这些栏加上其间的栏间距。它占用一组顶端平齐的空栏的栏首，或者引用它的那一栏及其后空栏的栏脚；栏数等于或大于页面的栏数时，它就是通栏浮动体。'page'和'side'跨度、旋转的资源（rotate）以及行内嵌入（here）忽略此项；captionSide只对一栏宽的浮动体有效。

#模板标记

numberingTemplate与标题编号使用同一个渲染器（见标题）。它识别两类标记：

• {n}：该类型的计数器，按counterFormat格式化。每个资源使它递增一次，并按resetOn清零。
• {h1} … {h6}：第一次引用处生效的各级标题编号，总是显示为十进制。{h1}是当前一级标题的编号，{h2}是二级标题的编号，依此类推。

其他文字按字面输出。反斜杠用来转义字面的{、}或\。某个标题标记在当前范围内没有值时（例如在第一个一级标题之前的{h1}），它会连同相邻的分隔符一起省去，所以{h1}.{n}会自然退化为单独的计数器。

空模板（''）不输出编号，但该类型仍会为资源计数：题注为Do. Lines at 0°，:ref只输出标签（Do）。postext 1.4及以前，这样的题注显示为Do .Lines at 0°，引用末尾还多一个不间断空格。

#编号与引用

资源类型生成的编号就是:ref输出的内容，也是题注前缀后面跟的编号。:ref{id}是主要写法：按阅读顺序的第一次引用会纳入该资源，资源浮动到这次引用之后的第一个空位：引用所在栏的底部、下一个空栏的顶部或底部，或下一页的某个版带（依其解析后的位置而定：position: 'auto' | 'top' | 'bottom' | 'here'和span: 'column' | 'page' | 'side'，外加rotate、width、align和captionSide，先按资源自身解析，再取类型的defaultPlacement，最后取内置的auto / column；'top' / 'bottom'把搜索限定在该种空位）。::resource{id}块级嵌入是可选的，只在placement.position: 'here'时需要，即在文字流中某个确切位置行内嵌入、不浮动。文档一侧的完整语法（两种写法，以及:ref的style和text选项）见文档格式 › 资源，其中也说明了第一次引用的顺序如何决定计数。

这与标题编号相对应：标题级别带有numberingTemplate，资源类型也带有一个；不同的是资源计数器（{n}）按第一次引用递增，而不是按标题递增，resetOn再把它与标题层级联系起来。

#哪些资源会编号

正文引用了的资源才编号，无论是用:ref还是::resource嵌入，编号顺序就是这些第一次引用的顺序，与位置无关：浮动的、行内（here）的、在侧栏的或旋转的都一样。只由版面设计绘制的资源（章首页、书眉或篇首页的image元素），或者没有任何引用的资源，不编号，也不推进其类型的计数器。因此在一篇摄影随笔中，如果满版出血的图版都是章首页图像，只有一张较小的图版是被引用的浮动体，那么这张浮动体就是图版I，不管前面的章首页已经展示了多少图版；章首页的图版应在其版面设计中编号（用{attr.plate}这样的属性），计数器留给正文引用的图版。

逐章排版的书（沙盒、buildBundle，或用continuationAfter()传递计数器的buildDocument）中，以全书的第一次引用为准：资源保留它在首次引用它的那一章得到的编号，也只由那一章放置它。后面章节的:ref输出这个编号，但不放置任何东西；在那里对浮动资源的::resource嵌入也只是又一次引用（行内的here嵌入仍排在写它的位置）。当图与引用在同一份输出中时，引用会链接到图：整本书的PDF会把它链接到前面章节的那一页。单独渲染的一章，无论HTML还是PDF，都把它排成链接颜色的普通文字，因为它的图不在该文档里。宿主若把各章的HTML拼在同一页上，可以把各章锚定的资源作为refTargets传给renderToHtml，这样的引用就又会链接到前面章节的图：

import { anchoredResourceIds, buildBundle, renderToHtml } from 'postext';
 
const docs = buildBundle(bundle);
const refTargets = new Set(docs.flatMap((d) => [...anchoredResourceIds(d)]));
const html = docs.map((d) => renderToHtml(d, { refTargets })).join('');

postext 1.5的变化：1.4及以前，每个引用了某张图的章节都会再浮动一次这张图，而且每个:ref在HTML中都是链接，不管它的图是否在该页面上。

{h1}是一级标题的连续计数：每个H1都会使它递增，除非该标题的样式设了numbered: false；空的numberingTemplate只是隐藏标题的编号，并不停止计数。因此一篇只有标题是H1的文章，用内置的{h1}.{n}类型时，图的编号是1.1、1.2……要输出图1、2……有两种办法：

• 使用按{n}编号、resetOn: 'never'的类型（若用resetOn: 'h1'，每个H1都会重新计数）；
• 给标题以及其他不应计数的H1加上numbered: false的标题样式：这样的标题不推进{h1}，而是保持原值（在第一个计数的H1之前为空，此时{h1}.{n}退化为单独的计数器），也从不触发resetOn: 'h1'，所以计数会越过它继续。在# Introduction及其图1.1之后，未编号的# Appendix下的第一张图是1.2，而不是2.1。

// 单篇文章文档中的图1、2、3……
resourceTypes: defaultResourceTypes('en').map((t) => ({ ...t, numberingTemplate: '{n}', resetOn: 'never' })),

#表格样式

tableStyle属性控制表格资源的字体排印和装饰，作用于每张表，除非该表选用了某个命名表格样式。正文单元格和表头单元格分别设定样式。字体、字号和颜色未设置时继承解析后的正文，因此没有tableStyle的文档会用正文的字体排印来渲染表格。

const config: PostextConfig = {
  tableStyle: {
    headerBold: true,
    headerBackground: { hex: '#f0f0f0', model: 'hex' },
    borders: true,
    borderWidth: { value: 0.75, unit: 'pt' },
  },
};

边框粗细保留小数：0.5pt的线在PDF和屏幕上都画成细线，而不会向上取整到整像素（最小为0.25px）。

#斑马纹

长数据表每隔一行着色，横向阅读时更容易跟行。bodyAlternateBackgroundEnabled打开条纹，bodyAlternateBackground设定条纹颜色：

const config: PostextConfig = {
  tableStyle: {
    bodyBackgroundEnabled: true,
    bodyBackground: { hex: '#ffffff', model: 'hex' },
    bodyAlternateBackgroundEnabled: true,
    bodyAlternateBackground: { hex: '#eef3fa', model: 'hex' },
  },
};

行从表头行之后的第一行开始计数（表头行由TableModel.headerRowCount给出，或者是由表头单元格组成的开头几行）：这一行保持bodyBackground（bodyBackgroundEnabled关闭时则无填充），下一行取交替填充色，依此类推。计数依据表格模型而不是页面，所以跨页拆分的表在每一页上都保持各行原有的条纹，跨行合并的单元格取其第一行的条纹。表头单元格保持表头填充色，单元格自身的background优先于两者，与调色板关联的颜色随调色板变化。命名表格样式可以像设定其他字段一样设定这两个字段，因此一个样式可以带条纹，而文档中的其他表不带；在沙盒中它们是正文单元格下的斑马纹行开关及其颜色。

在VDT中，交替行的单元格带有alternate: true，表格版面带有bodyAlternateBackground。tableCellFill(table, cell)返回单元格实际绘制的填充色（它自己的、表头的、交替的或正文的），Canvas、HTML和PDF后端绘制的都是这个值。相邻的填充色之间没有接缝：浏览器在非整数像素比下、PDF阅读器在显示时，会分别对每块填充做抗锯齿，两个单元格之间就会透出一条细线，露出页面底色。所以HTML和PDF后端绘制的是tableCellFillRects(table)：每个单元格的填充色都在它与后绘单元格共用的每条边上多出一条窄带，再由后绘的单元格盖住；Canvas则把填充对齐到设备像素。

#三线表

期刊和教材里的表格通常只用三条线，不画竖线：表格上方一条粗线，表头下一条细线，末行下一条粗线；表头中跨几列的分组标题下另有短线（LaTeX 的booktabs宏包：\toprule、\midrule、\cmidrule、\bottomrule）。rules: 'booktabs'画的就是这种样式：

const config: PostextConfig = {
  tableStyle: {
    rules: 'booktabs',
    borderColor: { hex: '#000000', model: 'hex' },
    headerBackgroundEnabled: false,
  },
};

• 表格上方的线和末行下方的线粗heavyRuleWidth（0.08em），表头行下的线粗lightRuleWidth（0.05em）。没有表头行的表格不画表头线。
• 在最后一行表头之上、跨多列的表头单元格下画一条粗spanRuleWidth（0.03em）的线。spanRules: 'trimmed'（默认）时，这条线两端各缩短spanRuleTrim（0.5em），相邻两个分组标题下的线因而互不相接；'full'让它贯穿整个单元格，'none'则不画。
• groupRules: true在每个作为分组标题的表体行（一个单元格横贯全表，或一整行表头单元格）上方加一条细线；该行位于表格开头或页首时除外，那里已有表头线。
• 各线宽以正文单元格字号（bodyFontSize）换算，表头字号较大也不会加粗表头线。线宽为0时不画该线。
• 线的颜色取borderColor（关联调色板的颜色随调色板和:::part palette变化），borders: false关闭所有线。borderWidth不起作用，borderRadius也不起作用：线保持直线，单元格填充色仍按圆角外框裁切。表头填充、斑马纹和单元格自己的background与其他线型一样有效，画在线的下面。
• 跨页拆分的表格每部分都重复表头行，所以每部分都以粗线和表头线开头。末行下的粗线只收尾最后一部分；延续到下一页的部分以continuedFootRule收尾：细线（'light'，默认）、粗线（'bottom'）或不画（'none'）。

排版只计算一次这些线。VDT 中的表格以strokes（{ x1, y1, x2, y2, widthPx }，相对于表体左上角）携带它们，画布、HTML 查看器、PDF 和固定版式 EPUB 照此绘制；在带标签的 PDF 中它们是版面工件。流式 EPUB 把它们写成表格和表头的 CSS 边框，两端缩短的线用背景线绘制。在 Sandbox 中，于线条下拉框选择三线表（booktabs）会显示这些字段，并隐藏边框宽度和圆角半径。

#命名表格样式

一份文档里的表很少全都一个样：清单用藏青色网格加圆角外框，选项行只用外框围起来，数据表只用横线。tableStyles声明命名的变体，表格资源用table.styleId选用其中一个。样式没有设定的字段先从tableStyle读取，再从正文读取，所以一个样式只需写明它与众不同的地方。没有styleId的表，或者styleId指向未声明样式的表，仍用tableStyle；没有tableStyles的文档渲染结果与以前完全相同。

const config: PostextConfig = {
  tableStyle: {
    borderColor: { hex: '#163a76', model: 'hex' },
    borderWidth: { value: 1.3, unit: 'pt' },
    borderRadius: { value: 10, unit: 'pt' },
  },
  tableStyles: [
    {
      id: 'option',
      name: 'Option row',
      rules: 'outer',
      borderColor: { hex: '#7a9cc6', model: 'hex' },
      borderWidth: { value: 1, unit: 'pt' },
      borderRadius: { value: 8, unit: 'pt' },
      headerBackgroundEnabled: false,
    },
  ],
};
 
// 在资源中：这张表用"option"样式排。
const resource: Resource = {
  id: 'choices', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
  table: { model: { rows: [/* … */] }, styleId: 'option' },
};

每个条目接受tableStyle的所有字段，外加id（供table.styleId引用）和可选的name（供编辑器显示，默认为id）。样式能设定的一切都按表生效：字体排印、填充色、边框、线型、圆角半径、内边距，以及溢出行为和它的续表文字。resolveTableStylesConfig(styles, tableStyle, resolvedBodyText, locale?)返回解析后的列表，pickTableStyle(resolved, styleId)返回某张表所用的样式，stripTableStylesDefaults去掉未设定的字段（等于内置默认值的字段会保留，因为它仍会覆盖tableStyle中不同的值）。在流式 EPUB 中，命名样式是表格上的一个类（pt-table-<id>），由书的样式表设置样式。

#比页面还高的表

浮动表如果放不进为它提供的新页面，既不会被压缩，也不会溢出：在overflow: 'split'（默认）下，引擎在放得下的最后一条行边界处把它按行切开，在后续页面上接续，需要几页就接几页。每个续表部分都重复表头行（TableModel.headerRowCount，未设置时为由表头单元格组成的开头几行），并再次带上题注，在描述之后加上continuedSuffix，如“Table 6-4. Title (cont.)”。每个还要接续的部分下方都有右对齐、用注释字体排的continuesMarker；表的注释留到最后一部分。切分点从不穿过合并单元格（跨行单元格整体移到下一部分）；统领下面各行的一行（横跨整张表的单个单元格）会被带到下一部分，而不是孤零零地留在页面底部。三线表的每个延续部分以continuedFootRule收尾（见三线表）。

第一部分在哪里结束。如果在引用之后为表提供的是某个空栏的顶部，表就取那里放得下的行，余下的接到下一个空位。当它独占该栏时，会一直排到栏底：若某部分下方只剩不到三行正文的空间，它就把这些空间也占上，而不留下一小截文字。当该栏已有另一条浮动版带时（比如页顶横跨整页的通栏图），这一部分会在栏底之前至少留出三行正文的位置就停下，这是浮动体与其他浮动体共用一栏时都要留给文字的空间，于是该栏在表下仍有一些文字，而不是只有浮动体。要让长表一直排到栏底，应在起始页没有其他浮动体的地方引用它（例如在通栏图那一页之后），或者调整它的行使其适合栏高。

'clip'保留放得下的开头几行，不声不响地丢掉其余部分（注释仍在该部分末尾）；'hide'则整张表都不排。二者只在表比一页还高时起作用：放得下的表在任何模式下都整体放置。

排在正文中的表。自postext 1.25起，排在here（用::resource嵌入）的表也遵循同样的规则（splitInline，默认开启）。它放不进本栏剩余空间时，就在行与行之间切开：第一部分保留上方的浮动体间距，至少带表头行和两行表体（若不够，整张表照旧从下一栏开始）；之后每一部分都在下一栏顶部开头，上方不留间距，按该栏的宽度排（一栏半版式把某一部分排进窄栏时，按窄栏的宽度排）；::resource那一行之后的文字接在最后一部分后面。重复表头、带后缀的题注、续接标记、最后一部分下的注释、至少三行的尾部，以及避开合并单元格和分组标题行的切分，都与浮动表相同。表体不足五行的表从不切开。'clip'保留比一栏还高的行内表放得下的开头几行，排在某一栏的顶部；'hide'不排这样的表；较矮的表在这两种模式下都整体移到下一栏。行内表开启的页面，只为表的第一部分保留不被该页浮动体占用的空间，因此等待中的通栏图仍排在该页顶部，表接在图下继续。竖排页面上的行内表以及框内的表不切开。splitInline: false把行内表整体移到下一栏，与postext 1.24及以前相同。

续表文字的默认值随文档语言而定（locale，否则取断词语言区域）：英语为(cont.) / Continued，西班牙语为(cont.) / Continúa，法语、德语、意大利语、葡萄牙语、加泰罗尼亚语和荷兰语也同样有对应文字（列在文档语言中）。

单元格内容是行内Markdown，单元格中的换行（换行符，或者像题注和注释中那样用\\）开始一个新段落。以项目符号或短横（•、-、*、–）或者数字（1.、1)）加空格开头的段落排成列表项：标记按原样绘制，文字以文档的unorderedLists.gap为距悬挂在标记之后，折行与文字对齐，开头两个空格表示嵌套一级。所以写成• Ofrece elección\n• Acomoda a personas diestras y zurdas的单元格会排成两项的列表。只有普通空格的一行不产生任何内容；含不间断空格（U+00A0）的一行则算作单元格的一行，与CommonMark一致，所以1\n后面跟一个不间断空格会使这一表格行占两行高。单元格文字末尾的不间断空格保留其宽度：760加一个不间断空格，右对齐在(231)上方时，会在离边缘一个空格处结束，使0靠近1。只有空格与括号等宽时数字才完全对齐，而大多数字体里空格更窄。（postext 1.4及以前两者都会被丢掉。）

列宽属于表格模型，而不属于样式：TableModel.columnWidths是可选的相对权重数组，每列一个值，在排版时归一化，[2, 1, 1]让第一列占一半宽度。缺少数组、长度不对或权重不为正时，退回平均分配。表格编辑器在增删列时会保持该数组与列对应。

#构建表格模型

TableModel是按行优先排列的网格，每个单元格按它在网格中的位置排版：rows[r][c]位于第c列。因此合并单元格所覆盖的单元格仍留在网格中，每个都用hiddenBy指向其主单元格；这与HTML表格不同，HTML表格会把它们省去。从postext导出的模型辅助函数保持这种结构；它们都是纯函数，返回新模型：mergeCells(model, { start, end })和unmergeCell(model, at)、addRow、addColumn、removeRow、removeColumn、setCellContent、setCellImage、setCellBackground以及setAlignment。四个行列辅助函数保持合并区域完整：在合并块内部添加的行或列会使它变宽，在它之前添加的会使它移位，从中删除的会使它缩小（失去第一行或第一列的合并块把内容保留在新的左上角单元格中），每个hiddenBy始终指向其主单元格。

parseTSV(text, options?)从制表符分隔的文本构建模型，即从电子表格粘贴来的区域：按换行拆行，按制表符拆单元格，较短的行会补齐，使网格成为矩形。headerRows把开头几行变成表头行：其单元格获得isHeader，模型获得headerRowCount，这样跨页拆分的表会重复它们。

import { parseTSV, mergeCells } from 'postext';
 
let model = parseTSV('Part\tQty\tNote\nBolt\t4\tM6\nNut\t8\t', { headerRows: 1 });
// model.headerRowCount === 1；model.rows[0][0]为{ content: 'Part', isHeader: true }
model = mergeCells(model, { start: { row: 2, col: 1 }, end: { row: 2, col: 2 } });
// rows[2][1]获得colSpan: 2；rows[2][2]留在网格中，带hiddenBy: { row: 2, col: 1 }

tableGridIssues(model)检查网格。对于完好的模型，它返回空列表；否则按行序返回网格出问题的每一处：spanOverlap，即位于另一个单元格的colSpan / rowSpan之下的可见单元格（coveredBy指出那个单元格），像HTML那样省去被覆盖的单元格就会出现这种情况，因为其后的每个单元格都会移到合并区域上；以及missingCells，即在最后一列之前就结束、又没有合并单元格覆盖其余部分的行，这会留下空洞。

import { tableGridIssues } from 'postext';
 
tableGridIssues({
  rows: [
    [{ content: 'A', colSpan: 2 }, { content: 'C' }],
    [{ content: '1' }, { content: '2' }, { content: '3' }],
  ],
});
// => [{ kind: 'spanOverlap', row: 0, col: 1, coveredBy: { row: 0, col: 0 } },
//     { kind: 'missingCells', row: 0, col: 2 }]

文档使用的表若网格存在这类问题，会在doc.contentWarnings中报告为raggedTableGrid（见文档中的警告）。

#题注样式

captionStyle属性控制资源题注（图像、SVG和表格下方或上方的Figure 1 — …那一行）。带编号的标签和描述共用同一字体和字号，这是引擎的限制，但标签可以有自己的字重、斜体和颜色。字体、字号和颜色未设置时继承正文。题注可以放在资源上方（表格的通常做法），也可以排在横跨整个块宽的彩色色条上；可选的较小注释（来源、出处，即Resource.note）通过note子对象设定样式。资源类型可以通过ResourceType.captionStyle为本类型的资源覆盖其中任何字段（见资源类型）。

const config: PostextConfig = {
  captionStyle: {
    align: 'center',
    labelBold: true,
    labelColor: { hex: '#295AA3', model: 'hex' },
    descriptionItalic: true,
    position: 'above',
    backgroundEnabled: true,
    padding: { value: 0.35, unit: 'em' },
    note: { italic: true, align: 'left' },
  },
};

note子对象为Resource.note设定样式，这是排在资源下方、字号较小的一小段文字（来源、出处、附注）。它接受与题注相同的行内格式和:ref标记，并继承题注的字体。题注在下方时，注释放在题注下面；题注在上方时，注释放在资源主体下面。注释的高度计入整个块，所以带注释的资源作为一个整体浮动。

按类型的覆盖设置用mergeCaptionStyle(resolvedCaptionStyle, override, palette?)合并；导出这个函数是为了让宿主在管线之外也能得到相同的解析结果。

#图示样式

diagramStyle属性控制嵌入的SVG图示（kind: 'svg'资源）如何着色，以及其中的文字用什么字体排。单色模式是一步重新着色，把图示中的每种颜色映射为同一种油墨的某个浓淡，文档用单一专色印刷时，图也能如实还原。内嵌字体把每个SVG的文字所指定的字体嵌入该SVG，使其中的标注在Canvas、HTML和EPUB中都以文档的字体排出（见SVG文字中的字体）。

const config: PostextConfig = {
  diagramStyle: {
    singleInk: true,
    inkColor: { hex: '#295AA3', model: 'hex' },
  },
};

#单色模式的工作原理

启用singleInk后，SVG标记中的每种颜色都会改写为inkColor的一个浓淡，其浓度为1 − 相对亮度（Rec. 709系数作用于经伽马编码的通道，这是一种感知上的近似，用于浓淡映射绰绰有余）。这种映射保留了感知明度：白色映射为纸白，黑色映射为满版油墨，浅色填充无论原来是什么色相都保持浅色。浅黄色背景变成油墨的浅淡色；深色描边接近满版油墨。

重新着色由导出的applySingleInkToSvg(svgText, inkHex)完成，它不依赖DOM，把SVG标记当作文本处理：

• #rgb / #rgba / #rrggbb / #rrggbbaa十六进制字面量、rgb() / rgba()函数和hsl() / hsla()函数，无论出现在哪里都会改写：表现属性、内联style、渐变、<defs>。这些函数的通道可以是整数、小数或百分比，可以用逗号语法或空格语法，因此rgb(11.37%, 20%, 50.59%)（Cairo的写法）和rgb(51 102 153 / 50%)同样会重新着色。着色后的函数写回为rgb(…)或rgba(…)。
• 关键字white和black只在作为绘制值（fill、stroke、stop-color、flood-color、color，无论是属性还是内联样式属性）出现时才替换，文本内容或标签中的不会替换。
• none、transparent和currentColor保持不变，其他命名颜色（red、steelblue……）以及未设置填充的形状或文本的默认黑色也不变。要让这些元素重新着色，就给它们指定明确的颜色。
• Alpha通道保留不变（#rgba / #rrggbbaa中的半字节和rgba(…)的alpha分量原样保留；百分比形式的alpha写成数字）。
• inkHex无法解析时，原样返回输入。
• 结果的根<svg>上带有data-postext-single-ink="#…"（即所用油墨）；已带有这一标记的标记文本原样返回，不管它标明的是哪种油墨。这种映射不是幂等的：第二遍会让每种颜色变浅，黑色大约变成油墨的三分之二，所以一张图只着色一次，由你的代码和各后端中先处理到它的那一方完成。（这个标记从postext 1.5开始才有；由1.4重新着色的标记文本不带它。）

import { applySingleInkToSvg } from 'postext';
 
const recoloured = applySingleInkToSvg(svgText, '#295AA3');
applySingleInkToSvg(recoloured, '#295AA3') === recoloured; // true：绝不着色两次

单色模式在三个后端中都起作用：PDF后端在把resourceBytes交给它的SVG字节作为矢量绘制之前先重新着色；Canvas和HTML后端在你要求时为所绘制的SVG图片着色（见Canvas与HTML中的单色模式），因此导出的PDF与屏幕预览一致。

解析函数和精简函数与其他各节一致，另有DiagramStyleConfig / ResolvedDiagramStyleConfig类型：

import {
  DEFAULT_DIAGRAM_STYLE_CONFIG,
  resolveDiagramStyleConfig,
  stripDiagramStyleDefaults,
  applySingleInkToSvg,
} from 'postext';
import type { DiagramStyleConfig, ResolvedDiagramStyleConfig } from 'postext';
 
const resolved = resolveDiagramStyleConfig(config.diagramStyle);
// => { singleInk: false, inkColor: { hex: '#295AA3', model: 'hex', paletteId: 'main-color' } }
 
const minimal  = stripDiagramStyleDefaults(config.diagramStyle);
// => 全部与默认值相同时为undefined

#Canvas与HTML中的单色模式

Canvas和HTML后端拿到的图片是已解码的（registerResourceImage）或URL（resourceImageUrl），而不是SVG标记。在你要求时，它们对所绘制的内容应用同样的映射：

• Canvas（renderPage、renderPageToCanvas、renderToCanvas）。凡是适用着色的SVG图片（图、表格单元格中的图片、设计图像、框的图标或标记），都按其放置尺寸栅格化，再把像素着色为油墨色，无论它是以<img>还是ImageBitmap注册的。着色后的位图和其他矢量栅格一样会被缓存。位图图片从不着色。
• HTML（renderToHtml、renderToHtmlIndexed）。每个SVG <img>都会加上filter: url(#pt-ink-…)，它指向所在页面携带的feColorMatrix：一个零尺寸的<svg>，内含<filter>，放在页面最前面，在索引输出中属于页面的decorationHtml。单色模式生效时，每一页都带有它，不管该页有没有图片，这样逐块修补的宿主就不会引入缺少滤镜的图片。

绝不着色两次。在postext 1.4及以前，Canvas和HTML后端按原样绘制图片，所以宿主先用applySingleInkToSvg自行重新着色标记，再交给后端。文件包适配器和沙盒现在仍然这样做，因为标记层面的处理能得到与PDF完全相同的颜色（见下文最后一段）。因此每张图片只着色一次，由以下三条规则保证，三个后端都遵循：

• 已带标记的标记文本保持原样。PDF后端用applySingleInkToSvg重新着色resourceBytes，所以已经重新着色过的SVG字节按原样绘制。在Canvas和HTML中，从SVG data URI加载、且标记文本带有该标记的图片也从不着色。
• 在postext 1.x中，不要求就不着色。对于注册时没有自带标志的SVG图片，Canvas只在渲染时传入singleInk: true（RenderPageOptions）才着色；以registerResourceImage(id, img, { singleInk: true })注册的图片则在任何渲染中都着色。HTML后端在renderToHtml收到singleInk: true，或其resourceImageUrl解析函数带有singleInk: true时着色。为1.4编写的宿主会重新着色标记文本，并在注册解码后的图片时不带标志，它的输出保持不变。下一个主版本将默认着色。
• singleInk: false从不着色。通过blob或网络URL无法读回标记文本，所以你自己重新着色、又以这种方式解码的图片要以singleInk: false注册，registerBundleImages和沙盒就是这样做的。bundleImageUrl(bundle)返回一个带有singleInk: false的解析函数，而bundleResourceBytes把文件包自己的字节交给PDF，由PDF后端重新着色一次。

两个后端都从VDT得知每张图片的类型：图和单元格图片带有其资源的类型，设计图像块带有imageKind（'svg'或'bitmap'），在排版时从其资源取得。对于imageKind出现之前构建的VDT，Canvas把以矢量源注册的设计图像视为SVG，HTML后端则把URL为SVG data URI或以.svg结尾的设计图像视为SVG。

要么自己重新着色标记，要么让后端为原始图片着色，两者不要同时用：

import { applySingleInkToSvg, registerResourceImage, renderPage, renderToHtml } from 'postext';
 
// 原始SVG：diagramStyle.singleInk开启时着色……
registerResourceImage('diagram.svg', rawImg, { singleInk: true });
// ……或者直接注册，在每次渲染时提出要求。
registerResourceImage('diagram.svg', rawImg);
const canvas = renderPage(doc.pages[0], doc, { singleInk: true });
 
// 解码前已重新着色（postext 1.4的宿主就是这样做的）：按原样绘制。
const inked = applySingleInkToSvg(svgText, ink);
registerResourceImage('diagram.svg', await decode(inked), { singleInk: false });
 
// HTML后端，使用指向原始标记的URL。
const html = renderToHtml(doc, { resourceImageUrl: urlFor, singleInk: true });

renderToHtml的singleInk默认值取自解析函数自身的标志，所以bundleImageUrl(bundle)无需额外选项。

对于标记层面处理会改写的每种颜色（十六进制、rgb()和hsl()值、white和black；见单色模式的工作原理），像素映射给出相同的结果，抗锯齿边缘和渐变也不例外。两者的差别在于标记处理不改动的颜色：white和black以外的命名颜色、currentColor、没有填充的形状和文本（以默认黑色绘制），以及嵌入SVG中的位图，在屏幕上会着色，在PDF中却保留原色。给图示的每个元素指定明确的十六进制、rgb()或hsl()颜色，就能得到完全一致的输出。Canvas无法读回像素时（来自其他源、未启用CORS加载的<img>），图片不着色绘制。

#SVG文字中的字体

SVG图片是通过图像显示的：在Canvas、HTML和EPUB中都是一个<img>。图像文档看不到页面的网络字体，所以<text font-family="IBM Plex Sans">会退回到系统字体。自postext 1.25起，引擎在图片解码或作为URL交出之前，把文字指定的字体嵌入标记：每个字体文件一条@font-face规则，字节写成data URI，放在紧跟根<svg>标签的<style>中。PDF不需要这一步：它把SVG文字作为真正的文字，用其嵌入的字体排出（见资源字节与印刷母版）。

文字要求什么字体，从font-family、font-weight、font-style和font读取，无论它们写成属性、写在style属性中，还是从外层的组继承；<style>中指定了字体族的规则也算在内。通用字体族（serif、sans-serif……）以及<title>或<desc>中的文字不计入；SVG自己用@font-face声明的字体族保持不动。一段文字沿着它的font-family列表往下找，用第一个有字体可用的字体族。先做单色重新着色，再嵌入字体。

字体来自一个提供函数，其约定与postext-pdf的PdfFontProvider相同，因此一个提供函数可以两处共用：调用时传入字体族、字重和样式，以及SVG用这种字体排出的字符，它返回一个或多个文件。以unicode-range切片提供的字体族（Fontsource、Google Fonts）只返回这些字符所需的切片，所以标注全是拉丁字母的SVG只带latin文件。默认的提供函数读取引擎的字体注册表：loadBundleFonts把文件包的字体注册在那里，宿主则用registerFontBytes(family, weight, style, bytes, { unicodeRange })注册自己的字体，或者用registerFontUrl(…)注册一个在SVG首次需要时才获取的文件。注册表中没有的字体族，会到页面可读样式表的@font-face规则中查找。从字节添加到document.fonts的FontFace不保留字节，引擎无法把它读回，所以这些字体也要注册。

import { registerFontBytes, registerSvgImage, renderPage } from 'postext';
 
registerFontBytes('IBM Plex Sans', 700, 'normal', plexBoldWoff2);
await registerSvgImage('chart.svg', svgText);   // 重新着色、嵌入字体、解码、注册
const canvas = renderPage(doc.pages[0], doc);

在哪里进行：

• Canvas。registerSvgImage(fileId, svgText, options)对图片重新着色（inkHex）、嵌入字体（fonts，一个提供函数；inlineFonts: false跳过这一步）、解码，并把它注册为矢量源，返回的Promise给出每种字体的处理结果。registerBundleImages(bundle)对文件包中的SVG做同样的事，优先使用文件包自己的字体。prepareSvgMarkup(svgText, options)返回处理好的标记，供自行解码的宿主使用。
• HTML。bundleImageUrl(bundle)提供已嵌入文件包字体的SVG标记。renderToHtml(doc, { inlineSvgFonts: true })把注册表在内存中持有的字体嵌入resourceImageUrl返回的SVG data: URI（也可写成inlineSvgFonts: { fonts, maxBytes, withhold }）。对象URL无法同步读取，所以提供blob URL的宿主要在生成URL之前嵌入。
• EPUB。postext-epub在写出SVG之前，先从书的fonts、再从svgFonts.provider取字体嵌入（见EPUB电子书）。
• PDF。SVG文字作为真正的文字，用嵌入的字体排出。只含@font-face规则的<style>（作者嵌入的字体）不再使图退回栅格。图确实退回栅格时（滤镜、渐变），其栅格图用从PDF的fontProvider取来的字体嵌入后生成。

较底层的函数也已导出：svgFontRequests(svgText)列出每段文字的字体族、字重、样式和字符；inlineSvgFonts(svgText, provider, options)和inlineSvgFontsSync(svgText, syncProvider, options)返回标记；inlineSvgFontsDetailed另外报告每种字体的结果（inlined、declared、unavailable、withheld、tooLarge）。

退出。diagramStyle.inlineFonts: false让每个SVG保持存储时的样子；资源上的svg.inlineFonts: false让这一个SVG逐字节保持原样，适用于自带字体或不得改动的SVG。文件包把资源的退出写在preset.json中，即"inlineFonts": false。

许可证。嵌入会把字体文件放进可能离开应用的图片中（HTML导出、EPUB）。它只在图片显示或导出时进行，从不写入存储的资源字节；withhold则把许可证不允许转交的字体族挡在外面：EPUB写出器扣下标记为redistributable: false的字体，沙盒扣下标记为不可再分发的自定义字体族。

#视频样式

videoStyle属性设定视频资源如何印出：封面上的播放标记和二维码，以及封面是否链接到视频；还设定它们的播放器在HTML查看器和EPUB中提供哪些功能。

const config: PostextConfig = {
  videoStyle: {
    playMark: { shape: 'rounded', position: 'top-left', size: { value: 10, unit: 'mm' } },
    qr: { position: 'bottom-right', size: { value: 20, unit: 'mm' }, errorCorrection: 'Q' },
    player: { download: false, privacy: true },
  },
};

#播放标记

#二维码

二维码由引擎自己编码（encodeQr(text, level)：字节模式、UTF-8、版本1到40，选罚分最低的掩码），并以矢量绘制：Canvas填充一条由模块段组成的路径，PDF用一次drawSvgPath，HTML用一个带shape-rendering="crispEdges"的<path>，所以无论印多大都保持清晰。

#播放器选项

VideoPlayerOptions，用在videoStyle.player和每个视频的video.player中。文件的HTML5播放器支持全部选项；YouTube和Vimeo的播放器支持其嵌入参数所允许的那些。

EPUB只保留其规范认识的属性：文件播放时带controls、autoplay、muted、loop、playsinline和preload，另加data-pt-alongside标记，其余由阅读系统决定。

不独占的视频在HTML输出中带有data-pt-alongside。coordinateVideoPlayback(root)让root（容纳renderToHtml输出的元素）下的播放器遵守这一规则：开始播放独占的视频会暂停其他所有正在播放的视频，开始播放同时播放的视频只暂停独占的视频。它返回一个停止监听的函数。playsAlongside(el)和videosToPause(started, videos, alongside)为自带播放器的宿主提供同样的规则。在Folio中，自动播放且与其他视频同时播放的视频（autoplay加exclusive: false）每次翻到它所在的页面时都静音开始，翻走时停止，几段可以同时播放；loop让它播完后从头再播。EPUB中，有视频需要协调的页面或章节（两段或以上，其中至少一段独占）以一个小脚本scripts/videos.js（即导出的VIDEO_PLAYBACK_SCRIPT）引入同一规则，包文件把该文档声明为scripted。运行脚本的阅读系统让该文档中的视频遵守这一规则，但对面的页面是另一个文档，不受影响；不运行脚本的阅读系统按自己的规则播放每段视频，YouTube和Vimeo播放器也始终如此。

解析函数和精简函数与其他各节一致，另有VideoStyleConfig / ResolvedVideoStyleConfig类型：

import {
  DEFAULT_VIDEO_STYLE_CONFIG,
  DEFAULT_VIDEO_PLAYER_OPTIONS,
  resolveVideoStyleConfig,
  resolveVideoPlayerOptions,
  stripVideoStyleDefaults,
} from 'postext';
 
const resolved = resolveVideoStyleConfig(config.videoStyle);
const player = resolveVideoPlayerOptions(resource.video?.player, resolved.player);
const minimal = stripVideoStyleDefaults(config.videoStyle); // 全部与默认值相同时为undefined