简单来说
一本香港儿童识字课本的几页。示例演示怎样在每个汉字上方标注拼音,并配上练字用的田字格。
成品一览
《蒙學誦讀》的两个跨页。这是一本虚构的香港启蒙读本,孩子们用普通话朗读《三字经》。每页是一课,四联,用一号楷体(26 pt)排,每个字上方是它的拼音音节。音节用Andika排,因为它的a和g是单层写法,和中文课本印的一样。一条浅色色带上有红色课次标签、一幅小水彩画和初号(42 pt)的标题,标题也带读音。正文下方,六个田字格放着要临写的字,一段说明告诉家长这几句是什么意思。与之对应的西班牙语食谱是带音节标签的识字课本,那里每个音节是一个彩色标签,而不是标在字上的读音。
识字课本有意不守中文图书的规矩。孩子一次只读几个大字,所以26 pt时一行只排十二个字,而图书用10.5 pt排25到40个字;行距略大于字号的两倍,以容纳读音。每一联单独成行、居中,既不两端对齐,也不缩进。正文用楷体,也就是依循毛笔笔意的字体,因为它显示孩子要学写的笔画;图书则会用宋体。
这道食谱解答
- 怎样在汉字上方加拼音?
简短回答
// {人之初|rén zhī chū} gives each character its own syllable (mono ruby): three readings for
// three characters, split on the spaces. The reading sits in the line gap, centred on its
// character; a syllable wider than the character widens that character's box by what the
// reading needs, less the quarter of the reading's size it may lend a neighbour.
const cjk = {
// The type area in characters: 12 per line, 11 lines of 54 pt. The margins grow to centre it.
grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11 },
ruby: {
fontFamily: PINYIN, // one-storey a and g, as a Chinese primer prints them
// 9.9 pt over the text, 16 pt over the title: the widest syllables (xiāng, zhuān) still fit
// over one character, so every couplet is 8 em long and keeps to the grid.
fontSize: em(0.38),
color: col('pinyin'),
},
};
// The line pitch never changes for a reading: the gap between lines (54 − 26 = 28 pt) must
// hold it, or the build warns rubyExceedsLeading.
const text = {
fontFamily: KAI, fontSize: pt(TEXT), lineHeight: pt(LINE),
textAlign: 'center', firstLineIndent: pt(0), // one couplet to a line, centred
};
用料
- 类型
- LXGW WenKai TC, Noto Sans TC, Andika(SIL OFL 1.1)
- 素材
brush-800.jpgjade-800.jpgshuttle-800.jpgsprout-800.jpg- The writing squares, drawn in code in the page’s palette (Postext Cookbook, CC BY 4.0)
- Lesson 1’s vignette: a seedling, a watercolour (Generated With Diffusion Models, 原创)
- Lesson 2’s vignette: the shuttle of a loom, a watercolour (Generated With Diffusion Models, 原创)
- Lesson 3’s vignette: a brush and its first stroke, a watercolour (Generated With Diffusion Models, 原创)
- Lesson 4’s vignette: a jade disc on a red cord, a watercolour (Generated With Diffusion Models, 原创)
做法
#1 · 每个字上方一个音节
代码见上文的简短回答。{人之初|rén zhī chū}给三个字三个读音,按空格拆分:每个音节居中排在自己那个字的上方,行也可以在它们之间断开。读音本身不占位置,它位于行间空隙中,这里是54 − 26 = 28 pt;空隙比读音窄时会报告rubyExceedsLeading。比所注汉字更宽的音节则要占位置:它会撑宽这个字的字框,在居中的行里,后面的字就会偏离网格。读音的字号取在这里最宽的音节xiāng和zhuān仍能放在一个字上方的大小,即0.38 em(9.9 pt):每一联都是八个字长,每个字都保持方正。若用0.45 em,性相近,習相遠会被撑到八个半字宽,并在相字周围留出空隙。
#2 · 标题保留读音
const BAND = 68; // mm from the top edge
// Heading designs ignore parity: a place for the drawing on each side, 14 mm from the outer
// edge, named {left="…"} on a verso and {right="…"} on a recto. A missing attribute draws nothing.
const picture = (side, x) => ({ kind: 'image', id: `picture-${side}`,
resourceId: `{attr.${side}}`, decorative: true, reserve: false,
placement: { anchor: { to: 'page', edge: `top-${side}` }, offset: { x: mm(x), y: mm(14) },
size: { width: mm(42), height: mm(42) } } });
const opener = { enabled: true, slot: { elements: [
{ kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('tint') },
placement: { anchor: { to: 'page', edge: 'top-left' },
size: { width: mm(184), height: mm(BAND) } } },
picture('left', 14), picture('right', -14),
{ kind: 'text', id: 'lesson', content: '{titleText}', fontFamily: HEI, fontSize: pt(11),
fontWeight: 700, letterSpacing: pt(2), color: col('paper'), align: 'center', overflow: 'wrap',
placement: { anchor: { to: 'container', edge: 'top' } },
box: { backgroundColor: col('red'), borderRadius: mm(3.5),
padding: { top: mm(1.2), right: mm(3.6), bottom: mm(1.2), left: mm(3.6) } } },
] } };
设计文字不印读音,所以标题不能来自章首页的版面设计。一级标题第一課画出色带、插图和红色标签;标题是它下面的二级标题,一个初号的普通标题,由正文排版器连同拼音一起排出。reserve: false把色带和插图排除在标题的高度之外,span: 'page'把它们画在正文之下。
标题的版面设计不理会parity,所以插图在页面两侧各有一个元素:{attr.left}距左边缘14 mm,{attr.right}距右边缘14 mm。排在左页的课写# 第一課 {left="sprout"},排在右页的课写{right="shuttle"},这样每幅插图都位于跨页的外侧;缺少对应属性的元素什么也不画。
#3 · 一个属性生成六个田字格
// Design text prints no readings, so the squares hold the characters alone. A Han character
// is one em wide, so tracking of (pitch − em) sets one in the middle of each square.
const [SQ, GAP, WRITE] = [15, 3.4, 30]; // mm, mm, pt
const ROW = 6 * SQ + 5 * GAP; // mm
const X0 = (MEASURE - ROW) / 2; // the row is centred on the measure
const EM = WRITE * 25.4 / 72; // mm: one character at 30 pt, 10.6 mm wide
const squares = { enabled: true, slot: { elements: [
{ kind: 'text', id: 'label', content: '{titleText}', fontFamily: HEI, fontSize: pt(10),
fontWeight: 700, letterSpacing: pt(1.5), color: col('red'), align: 'left', overflow: 'wrap',
placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { x: mm(X0) } } },
...Array.from({ length: 6 }, (_, k) => ({ kind: 'image', id: `square${k}`, resourceId: 'tian',
decorative: true, placement: { anchor: { to: 'container', edge: 'top-left' },
offset: { x: mm(X0 + k * (SQ + GAP)), y: mm(7) },
size: { width: mm(SQ), height: mm(SQ) } } })),
{ kind: 'text', id: 'chars', content: '{attr.write}', fontFamily: KAI, fontSize: pt(WRITE),
lineHeight: 1, letterSpacing: mm(SQ + GAP - EM), color: col('ink'), align: 'left',
verticalAlign: 'middle', overflow: 'clip',
placement: { anchor: { to: 'container', edge: 'top-left' },
offset: { x: mm(X0 + (SQ - EM) / 2), y: mm(7) },
size: { width: mm(ROW + GAP), height: mm(SQ) } } },
] } };
### 我會寫 {write="人之本不相以"}用一个属性把六个字交给版面设计。LXGW WenKai TC的每个汉字都是一个em宽,所以把字距设为田字格间距减去一个em(18.4 − 10.6 mm),字就一格一格地排过去,一个文字元素就能填满一行。田字格是用代码画的SVG:一个红框加一个虚线十字。
#4 · 每款字体只加载自己的字
// Fontsource cuts a Chinese face into about a hundred files by character range
// (gotcha: cjk-fonts-slices). The Kai sets the whole sample; the Hei only the headings'
// labels and the footer's series line, so it fetches a few files.
const labels = (markdown.match(/^#{1,3} [^{\n]*/gm) ?? []).join('') + '蒙學誦讀 第一冊';
await loadFonts(FONTS, markdown); // the latin files, and Andika's latin-ext for ǎ ǐ ǒ ǔ
await Promise.all([loadCjkFonts({ [KAI]: FONTS[KAI] }, markdown),
loadCjkFonts({ [HEI]: FONTS[HEI] }, labels),
loadSvg('tian.svg', tian), ...VIGNETTES.map((fileId) => loadImage(fileId, asset(fileId)))]);
Fontsource把每款中文字体按字符范围切成大约一百个文件。楷体排整个示例,只加载包含所用汉字的文件。黑体只排标签、说明文字和页脚,所以只拿到这些文字,下载几个文件。Andika来自loadFonts,当文字里有Latin-1以外的字母(如ǎ和ǐ)时,它会加上latin-ext文件。
#5 · 由语言区域决定香港标点
// Punctuation at full width, where LXGW WenKai TC centres it as Hong Kong and Taiwan print
// it, and the basic line-breaking rules. Written out, never LANG (gotcha: cjk-locale-tag).
locale: 'zh-HK',
zh-HK采用香港的规则:标点占全角,以及基本的避头尾规则,不过这里没有哪一联用得上。LXGW WenKai TC把逗号和句号画在字格正中,和香港、台湾的印法一样,这也是这本识字课本设定在香港的原因。大陆的启蒙读本同样用楷体排,但用简体字,逗号和句号位于字格左下。然而Fontsource没有简体中文的楷体正文字体,繁体那款又会让这些标点挤着下一个字,所以本排版食谱中的大陆页面用Noto Serif SC,即大陆小说页面所用的宋体。
完整食谱
// ═══ Postext Cookbook · Nº 076 · A pinyin primer: readings over every character ═══
// https://postext.dev/en/cookbook/pinyin-primer
// Code: MIT · Text: 三字經 (PD); pinyin, notes: CC BY 4.0 · Vignettes: diffusion models
// Fonts: LXGW WenKai TC, Noto Sans TC, Andika (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'pinyin-primer';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a primer's colours, every one linked by id
const palette = {
ink: '#29241f', // the characters: a warm near-black
pinyin: '#355a4d', // the readings, a shade off the ink so the two layers part
red: '#bf3a2b', // lesson badges and the writing squares
jade: '#2f7a5e', // the folio discs
tint: '#edf4ea', // the band behind each lesson's title
cream: '#faf3e4', // the note for families
muted: '#6d665e', // series line, colophon
paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the red.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.red })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [KAI, HEI, PINYIN] = ['LXGW WenKai TC', 'Noto Sans TC', 'Andika'];
const TEXT = 26; // pt: 一号, the size of a first reader's text
const LINE = 54; // pt: 2.1 × the size, so a reading fits between two lines
const CHARS = 12; // characters per line: the measure is 12 × 26 pt = 110 mm
const MEASURE = CHARS * TEXT * 25.4 / 72; // mm
// #region answer: one reading per character, in Andika, in a line gap wide enough to hold it
// {人之初|rén zhī chū} gives each character its own syllable (mono ruby): three readings for
// three characters, split on the spaces. The reading sits in the line gap, centred on its
// character; a syllable wider than the character widens that character's box by what the
// reading needs, less the quarter of the reading's size it may lend a neighbour.
const cjk = {
// The type area in characters: 12 per line, 11 lines of 54 pt. The margins grow to centre it.
grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11 },
ruby: {
fontFamily: PINYIN, // one-storey a and g, as a Chinese primer prints them
// 9.9 pt over the text, 16 pt over the title: the widest syllables (xiāng, zhuān) still fit
// over one character, so every couplet is 8 em long and keeps to the grid.
fontSize: em(0.38),
color: col('pinyin'),
组合好的script.js可以直接运行:把它粘贴到任何页面的模块脚本中,或在CodePen上打开这道食谱。 GitHub上的食谱文件夹 ↗ (在新标签页中打开)
变化
常见问题
易错点
注音印在正文中,不印在设计元素、题注或单元格中
注音会绘制在段落、标题、列表项、引文和框中。设计文本元素(章首页、书眉、徽标)、题注、脚注和表格单元格只印出基字,不带注音。需要拼音的标题应当是一个没有自身设计的标题:把它周围的内容(色带、课次编号)画在它前面那个标题的设计里,该设计中reserve: false的元素会画在span: 'page'章首页的文字下层。 注音:拼音与注音符号 →
易错点
各地区的标点要用该地区的字体排
标点宽度调整会把每个标点旁的空白移到文档所属地区规定的一侧,而不是字体绘制时的那一侧:在zh-Hans下,开明式的逗号保留字框的左半部分(简体字体把字形画在这里),让出右半部分。繁体字体把,。画在字框中央,所以让出的那一半含有部分字形,逗号就挤到了下一个字上。LXGW WenKai TC是Fontsource上唯一的楷体正文字体,在简体文字中就会这样。大陆的正文、注释和引文用Noto Serif SC或Noto Sans SC排,TC字体留给zh-Hant,简体毛笔字体(Ma Shan Zheng)只用于展示行,因为设计文本不做标点宽度调整。LXGW WenKai TC还会画出大陆和台湾标准都不采用的传承字形:為用爲的爫头,令(在冷、領中)用卩底。要检查页面上用它排的字。 中文标点宽度 →
易错点
中文字体通过cjk块分片加载
Fontsource把一个中文、日文或韩文字体家族按每个字重约一百个文件提供,每个文件覆盖一段字符范围。loadFonts只获取latin文件,所以屏幕上的汉字来自系统字体,测量不准;fontsourceProvider交给PDF的也是这个latin文件,汉字印出来是空框。列出kit中的cjk块,在loadFonts之后调用loadCjkFonts(FONTS, markdown)(书中用到几种CJK字体时,每种字体调用一次,并传入它所排的文字),并给renderToPdf传fontProvider: cjkPdfProvider:两者都会取用包含文中字符的那些文件。 中日韩字体 →
易错点
用zh-Hans或zh-Hant标记文档,不要用LANG
食谱的版本是en和es,但中文示例在两个版本里都是中文:`locale: LANG`会把它标记为英文或西班牙文,给其中的拉丁文词断词,把图标注为Figure或Figura,并给PDF标上错误的语言。postext 1.30起,这个标记也是文字成形所用的语言(测量、绘制和嵌入都按它进行),所以标记成英文或西班牙文时,中文字体的数字和与拉丁文共用的标点会换成另一套字形,断行的位置也随之改变。自己写出标记:'zh-Hans'(大陆规范:GB断行规则、开明式标点)或'zh-Hant'(台湾:全角居中标点);香港用'zh-HK'。单写'zh'按简体、大陆规范处理。日文示例写'ja'(见gotcha ja-locale-tag)。 中文断行 →
版面警告 · rubyExceedsLeading
注音挤到相邻的行
原因. 在文字上方或下方带注音的段落,行间空隙比注音还窄:注音位于行距之中,碰到相邻的行。
解决. 给该段落设更大的行距(至少为正文字号加上`cjk.ruby.fontSize`),或把注音缩小。 文档 →
-
本食谱不提供PDF。工具包的
fontsourceProvider只嵌入字体的latin文件,而声调字母ā ǎ ǐ ǒ ǔ在latin-ext里,所以PDF会丢失它们,postext-pdf会把每个都报告为missingGlyph。如果需要PDF,就用中文字体排读音,cjkPdfProvider会逐字挑选这类字体的文件。 -
对照当地的标准字形检查田字格里的每个字。LXGW WenKai TC的為用的是爲的爫字头,这种旧字形在正文里可以接受,比如这里的老何為和為人子,但不能放进香港孩子临写的田字格。所以第三课练的是幼。
致谢
- 文本
- The Three Character Classic (三字經), lines 1–32: the text of the Harvard-Yenching Library’s 新刊三字經 as transcribed on zh.wikisource (revision 10344699), with today’s punctuation and 隣 written 鄰 · Traditionally attributed to Wang Yinglin (13th century); transcription by Wikisource editors · 公有领域
- The pinyin, the notes for families and the translations · Postext Cookbook · CC BY 4.0
- 图片
- The writing squares, drawn in code in the page’s palette · Postext Cookbook · CC BY 4.0
- Lesson 1’s vignette: a seedling, a watercolour · Generated With Diffusion Models · 原创
- Lesson 2’s vignette: the shuttle of a loom, a watercolour · Generated With Diffusion Models · 原创
- Lesson 3’s vignette: a brush and its first stroke, a watercolour · Generated With Diffusion Models · 原创
- Lesson 4’s vignette: a jade disc on a red cord, a watercolour · Generated With Diffusion Models · 原创
- 字体
- LXGW WenKai TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1) · Andika (SIL OFL 1.1)


