简单来说
一本台湾的小学国语课本,竖排。每个汉字右边都标着注音符号,孩子不认识的字也能读出来。
成品一览
《國語》第九册第十二课,这是一本虚构的台湾五年级课本:两则出自《韩非子》的寓言,一则是守在树桩旁等下一只兔子的宋国农夫,一则是宁可相信量好的尺码也不相信自己脚的郑国人。台湾的课本竖排,用楷体,每个字的注音符号排成一列放在字的右侧,孩子在学会写一个字之前就能读出它。这一课从一个右侧装订的跨页开始。上层放图片、注释、作者介绍和生字;下层是正文,用16 pt的Iansui,每行23字。对应的拉丁文字版本是带边栏的教科书,那里只放浮动体的侧栏,在这里转了九十度,成为上层。
这道食谱解答
- 怎样在竖排中文的每个字旁边加注音符号?
- 怎样把中文书排成竖排、右侧装订?
简短回答
const layout = {
writingMode: 'vertical-rl', // lines run down the page, read from the right; bound on the right
layoutType: 'oneAndHalf', // two tiers: the text below, pictures and notes above
sideColumnRole: 'floats', sideColumnSide: 'left', // 'left' is the top tier in vertical text
sideColumnPercent: 34,
gutterWidth: pt(2 * SIZE),
};
const cjk = {
// The lower tier: 23 characters down, 13 lines across the page.
grid: { enabled: true, charsPerLine: 23, linesPerPage: 13 },
// Readings at half the text size; zhuyin sets its symbols at 60 % of that, 0.3 em,
// so three symbols fit beside one character, and beside each of two in a row.
ruby: { fontFamily: ZHUYIN, fontSize: em(0.5) },
};
// The line pitch is twice the size: a gap of one em, which the zhuyin and its tone
// marks half fill. clreq asks for 1.5 em; one em keeps 13 lines of 23 on the page.
const LINE = 2 * SIZE;
const bodyText = {
fontFamily: KAI, fontSize: pt(SIZE), lineHeight: pt(LINE), color: col('ink'),
boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
textAlign: 'justify', firstLineIndent: em(2), indentAfterHeading: true,
};
用料
- 类型
- Iansui, LXGW WenKai TC, Noto Serif TC, Noto Sans TC(SIL OFL 1.1)
- 素材
plate-1-1500.jpgplate-2-1500.jpg- The farmer waiting by the stump, a brush painting (Generated With Diffusion Models, 原创)
- The man of Zheng hurrying home from the shoe stall, a brush painting (Generated With Diffusion Models, 原创)
做法
#1 · 每个字旁边一列注音
代码见上文的简短回答。{宋人|ㄙㄨㄥˋ|ㄖㄣˊ}给每个字各自的读音,以|分隔,一字一个;标点放在花括号外,所以。和,不标注音。竖排时,注音符号放在字行的右侧,符号上下叠排,声调符号在最后一个符号的右边,轻声的点在第一个符号上方。cjk.ruby.fontSize设为正文字号的一半时,符号为0.3 em,于是三个符号正好排在一个字的旁边;像就像这样连续两个这样的读音,相互之间至少隔开四分之一个符号,又不会撑宽任何一个字;如果是0.6 em,ㄇㄧㄥˊ就比明高,明明两字会被撑开。32 pt的行距留出一个字宽的空隙,注音和声调符号填满其中一半。clreq要求竖排行间标注音时留1.5 em,那样行距是40 pt,每页只有十行,所以这一页保留一个字宽,得到每页13行、每行23字,每个读音与旁边一行保持约8 pt的距离。
#2 · 图片和注释放在上层
const resourceTypes = [{ id: 'plate', name: '插圖', shortLabel: '圖', numberingTemplate: '{n}',
resetOn: 'never', counterFormat: 'decimal', captionPrefix: '' }]; // no prefix, no caption
const box = (id, title, body) => ({ id, title, background: col('tint'),
padding: { top: mm(3), right: mm(3), bottom: mm(3), left: mm(3) },
titleStyle: { fontFamily: HEI, fontSize: pt(11), fontWeight: 700, color: col('accent') },
body: { color: col('ink'), firstLineIndent: pt(0), textAlign: 'left', boldColor: col('ink'),
italicColor: col('ink'), ...body } });
// Zhuyin is 0.3 em of the text it reads: at 13 pt the notes' readings are 3.9 pt.
const calloutStyles = [ // fenced :::callout{type="notes" span="side"} in the text
box('notes', '注釋', { fontFamily: MING, fontSize: pt(13), lineHeight: pt(24) }),
box('author', '作者', { fontFamily: MING, fontSize: pt(13), lineHeight: pt(24),
textAlign: 'justify', firstLineIndent: em(2) }),
box('chars', '生字', { fontFamily: KAI, fontSize: pt(22), lineHeight: pt(40),
textAlign: 'center' }),
];
竖排时,oneAndHalf版面的栏变成上下层,sideColumnSide: 'left'把只放浮动体的那一栏放到上方。正文中的::resource{id="plate-1"}把第一幅图送到那里;plate类型没有题注前缀,图片也没有题注,所以图下什么都不印。用span="side"围起的框,会从它在正文中被围起的那一行开始落入上层,其文字在上层中自上而下排列。两则寓言的注释合为一个框,全课连续编号,围在第一则原文之后,而这则原文在第86页结束:注释填满第87页的上层,因此两则寓言的注释都和它们的原文在同一个跨页上。注音是所注文字的0.3 em,而cjk.ruby是全书统一的设置,所以注释和作者介绍的方框用13 pt,让其中的注音保持3.9 pt。
#3 · 四种字体,各自加载自己的文字
// {株|ㄓㄨ}: the characters are the text, the readings go to the zhuyin face.
const BOXES = /^:::callout\{type="(?:notes|author)"[^}]*\}\n([\s\S]*?)^:::$/gm;
const bases = (md) => md.replace(/\{([^|{}]+)((?:\|[^|{}]+)+)\}/g, '$1');
const readings = [...markdown.matchAll(/\{[^|{}]+((?:\|[^|{}]+)+)\}/g)].map((m) => m[1]).join('');
await loadFonts(FONTS, markdown);
await loadCjkFonts({ [KAI]: ['400'] }, bases(markdown.replace(BOXES, '')), { vertical: true });
const notesText = [...markdown.matchAll(BOXES)].map((m) => m[1]).join('\n');
await loadCjkFonts({ [MING]: ['400'] }, bases(notesText), { vertical: true });
await loadCjkFonts({ [ZHUYIN]: ['400'] }, readings.replaceAll('|', ''), { vertical: true });
await loadCjkFonts({ [HEI]: ['400', '700'] }, LABELS, { vertical: true });
await Promise.all(Object.values(plates).map((fileId) => loadImage(fileId, asset(fileId))));
// Lesson 12 of a reader: page 86 is a verso, so the lesson opens on a spread.
const continuation = { pageIndexOffset: 1, pageNumbering: { startAt: 86 } };
const doc = await withLoadedFonts(
() => buildDocument({ markdown, resources, continuation }, config()),
{ ...kitFonts(FONTS), text: markdown });
showBook(doc, { title: t({ en: 'A vertical reader with zhuyin',
es: 'Un libro de lectura vertical con zhuyin' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: cjkPdfProvider, resourceBytes: imageBytes }),
`${RECIPE}.pdf`);
课文用Iansui,这是一种以Klee One为基础、按台湾标准字形绘制的楷体,也就是孩子们学写的字形。注音用LXGW WenKai TC,它的轻声圆点在4.8 pt下仍保持圆形;注释用Noto Serif TC,标签用Noto Sans TC。每种字体只加载包含它所排文字的文件:读音与所注的字分开统计,注释框只交给明体。vertical: true加入竖排字形,所以「」和、在字行中立得正确。pageIndexOffset: 1让第86页成为左页(偶数页),这一课就从一个跨页开始。
#4 · 外侧边缘的书边标签和页码
// The verso lies on the right of the spread, so even pages carry both at the right edge.
const tab = (parity, edge) => [
{ kind: 'box', id: `tab-${parity}`, parity, pages: 'all',
placement: { anchor: { to: 'page', edge }, offset: { y: mm(24) },
size: { width: mm(9), height: mm(64) } }, style: { backgroundColor: col('accent') } },
{ kind: 'text', id: `unit-${parity}`, content: '第三單元 寓言故事', parity, pages: 'all',
writingMode: 'vertical-rl', fontFamily: HEI, fontSize: pt(9), fontWeight: 700,
color: col('paper'), align: 'center', verticalAlign: 'middle',
placement: { anchor: { to: `#tab-${parity}`, edge: 'align-top' },
size: { width: mm(9), height: mm(64) } } },
];
const foot = (id, parity, edge, x, content, extra = {}) => ({
kind: 'text', id, content, parity, pages: 'all', fontFamily: HEI, fontSize: pt(8),
color: col('muted'), placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(-9) } },
...extra,
});
const folio = { fontSize: pt(9), fontWeight: 700 };
const header = { elements: [...tab('even', 'top-right'), ...tab('odd', 'top-left')] };
const footer = {
elements: [
foot('folio-even', 'even', 'bottom-right', -16, '{pageNumber}', folio),
foot('book', 'even', 'bottom-right', -26, '國語 第九冊'),
foot('folio-odd', 'odd', 'bottom-left', 16, '{pageNumber}', folio),
foot('lesson', 'odd', 'bottom-left', 26, '{chapterNumber} {chapterTitle}'),
],
};
在右侧装订的书中,左页(偶数页)位于跨页的右边,所以偶数页在右边缘放单元标签和页码,奇数页放在左边缘。标签是一个方框,上面叠一个文本元素;元素上的writingMode: 'vertical-rl'让第三單元 寓言故事在标签上竖排,页码和页脚的文字仍然横排。课次和寓言的编号由标题的numberingTemplate生成(第{1:一}課和{2:一},numberSeparator为一个全角空格,课题上写{startAt=12}),编号与标题分开,寓的注音仍只标在寓旁;{chapterTitle}不含编号,所以奇数页页脚写作{chapterNumber} {chapterTitle}。
完整食谱
// ═══ Postext Cookbook · Nº 080 · A vertical reader with zhuyin to the right ═════════
// https://postext.dev/en/cookbook/zhuyin-vertical-reader
// Code: MIT · Text: Han Feizi, zh.wikisource (CC BY-SA 4.0) · Pictures: diffusion models
// Fonts: Iansui, LXGW WenKai TC, Noto Serif TC, Noto Sans TC (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage, loadVerticalAlternates,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'zhuyin-vertical-reader';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: semantic colours, every one linked by id
const palette = {
ink: '#2b2520', // text and zhuyin
accent: '#b83f28', // lesson title, labels, the unit's tab (4.9:1 on the tint)
tint: '#f7efdf', // the boxes of the upper tier
muted: '#72675b', // lead, folios, colophon
paper: '#ffffff', // the lettering on the tab
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
{ id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// #endregion
const KAI = 'Iansui'; // 楷: the lesson, drawn to Taiwan's standard forms (為, not 爲)
const ZHUYIN = 'LXGW WenKai TC'; // the readings: a round dot for the neutral tone
const MING = 'Noto Serif TC'; // 明: notes and the author box
const HEI = 'Noto Sans TC'; // 黑: labels, folios, the tab
const SIZE = 16; // the text size (三號)
// #region answer: vertical text with a zhuyin column right of every character
const layout = {
writingMode: 'vertical-rl', // lines run down the page, read from the right; bound on the right
layoutType: 'oneAndHalf', // two tiers: the text below, pictures and notes above
sideColumnRole: 'floats', sideColumnSide: 'left', // 'left' is the top tier in vertical text
sideColumnPercent: 34,
gutterWidth: pt(2 * SIZE),
};
const cjk = {
// The lower tier: 23 characters down, 13 lines across the page.
grid: { enabled: true, charsPerLine: 23, linesPerPage: 13 },
// Readings at half the text size; zhuyin sets its symbols at 60 % of that, 0.3 em,
// so three symbols fit beside one character, and beside each of two in a row.
ruby: { fontFamily: ZHUYIN, fontSize: em(0.5) },
};
组合好的script.js可以直接运行:把它粘贴到任何页面的模块脚本中,或在CodePen上打开这道食谱。 GitHub上的食谱文件夹 ↗ (在新标签页中打开)
变化
常见问题
易错点
注音印在正文中,不印在设计元素、题注或单元格中
注音会绘制在段落、标题、列表项、引文和框中。设计文本元素(章首页、书眉、徽标)、题注、脚注和表格单元格只印出基字,不带注音。需要拼音的标题应当是一个没有自身设计的标题:把它周围的内容(色带、课次编号)画在它前面那个标题的设计里,该设计中reserve: false的元素会画在span: 'page'章首页的文字下层。 注音:拼音与注音符号 →
易错点
竖排时侧栏变成一层,'left'是最上面一层
当layout.writingMode为'vertical-rl'时,页面相当于把横排页面转了四分之一圈,所以oneAndHalf版式的侧栏变成横贯页面的一层:sideColumnSide 'left'把它放在页头,即眉批的位置,'right'则放在页脚。'outer'和'inner'分别按'right'和'left'处理(一层没有外侧边),所以教科书边栏的'outer'会把注释送到页脚。sideColumnPercent是页面高度的比例。 放浮动体的边栏 →
易错点
中文字体通过cjk块分片加载
Fontsource把一个中文、日文或韩文字体家族按每个字重约一百个文件提供,每个文件覆盖一段字符范围。loadFonts只获取latin文件,所以屏幕上的汉字来自系统字体,测量不准;fontsourceProvider交给PDF的也是这个latin文件,汉字印出来是空框。列出kit中的cjk块,在loadFonts之后调用loadCjkFonts(FONTS, markdown)(书中用到几种CJK字体时,每种字体调用一次,并传入它所排的文字),并给renderToPdf传fontProvider: cjkPdfProvider:两者都会取用包含文中字符的那些文件。 中日韩字体 →
易错点
右装订的书用showBook显示跨页
在右装订的书中(阿拉伯文、希伯来文或波斯文,竖排中文,或page.binding 'right'),第1页仍是奇数页(recto),但它位于书脊左侧,跨页读作[3 | 2]。showPages把所有书都按左装订排列;book块中的showBook(cjk块中也有同一个函数)读取doc.binding,把跨页左右镜像。capture.hero仍按阅读顺序[偶数页, 奇数页]指定跨页:[2, 3]。 右翻书 →
易错点
用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)。 中文断行 →
-
读音要依据台湾的辞典。基于大陆辞典的工具,包括pypinyin,给出的是度 duó、寧 nìng、時候 shíhou和市場 shìchǎng;台湾课本所依据的教育部《重编国语辞典修订本》读作ㄉㄨㄛˋ、ㄋㄧㄥˊ、ㄕˊ ㄏㄡˋ和ㄕˋ ㄔㄤˊ,并把故事、家裡和過來的第二个音节标为轻声。moedict.tw可以逐词查询这部辞典。它把一和不标作本调,这一课也是如此。
-
混用字体之前,先在每种字体里写几个字看看。LXGW WenKai TC采用传承字形,把為(U+70BA)画成爲,所以用它排的一课在同一个跨页上,正文印着爲宋國笑,明体的注释里却是為宋國笑。Iansui画的是标准的為。
-
Iansui只有一种字重。标题靠字号突出,成语词目靠颜色突出:
idiom样式设boldFontWeight: 400,并以强调色作为boldColor,所以**…**改变的是颜色而不是字体。
致谢
- 文本
- Han Feizi, chapter 49, “Wu du” (The five vermin): the man of Song who waited by the stump · Han Fei; transcription and punctuation by Wikisource editors (爲 set as 為, the Taiwan standard form) · CC BY-SA 4.0
- Han Feizi, chapter 32, “Wai chu shuo zuo shang”: the man of Zheng who went to buy shoes · Han Fei; transcription and punctuation by Wikisource editors · CC BY-SA 4.0
- The zhuyin (checked against the Ministry of Education's Revised Mandarin Chinese Dictionary), the modern Chinese versions, the notes, the author box, the lead and the exercises, written for this recipe · Postext Cookbook · CC BY 4.0
- 图片
- The farmer waiting by the stump, a brush painting · Generated With Diffusion Models · 原创
- The man of Zheng hurrying home from the shoe stall, a brush painting · Generated With Diffusion Models · 原创
- 字体
- Iansui (SIL OFL 1.1) · LXGW WenKai TC (SIL OFL 1.1) · Noto Serif TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1)


