Em poucas palavras
Páginas de uma cartilha infantil de Hong Kong. Mostra como imprimir a pronúncia em letras latinas acima de cada caractere chinês, com quadriculados para treinar a escrita.
O que você vai compor
Duas páginas duplas de 《蒙學誦讀》, uma cartilha inventada de Hong Kong, onde as crianças leem em voz alta o Clássico dos Três Caracteres em mandarim (putonghua). Cada página é uma lição de quatro dísticos em Kai de 一号 (26 pt), cada caractere sob a sílaba de pinyin. As sílabas estão em Andika porque ela desenha o a e o g de um só bojo que os livros escolares chineses imprimem. Uma faixa clara traz o selo vermelho da lição, uma pequena aquarela e o título em 初号 (42 pt) com a própria leitura. Abaixo do texto, seis quadriculados de escrita (田字格) trazem os caracteres para copiar, e uma nota explica à família o que os versos querem dizer. A equivalente em espanhol é a cartilha de sílabas em chips, em que cada sílaba é um chip colorido em vez de uma leitura sobre um caractere.
Uma cartilha foge de propósito das regras do livro chinês. Uma criança lê poucos caracteres grandes por vez, de modo que a linha leva doze de 26 pt, quando um livro põe de 25 a 40 de 10,5 pt, e a entrelinha passa um pouco do dobro do corpo para caberem as leituras. Cada dístico fica centralizado numa linha própria, sem justificação nem recuo. O texto está em Kai, a letra que segue o pincel, porque ela mostra os traços que a criança aprende a escrever; um livro o comporia em Song.
Esta receita responde a
- Como coloco pinyin sobre os caracteres chineses?
A resposta curta
// {人之初|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
};
Ingredientes
- Funcionalidades
- Rubi: leituras em pinyin e zhuyinFontes chinesas, japonesas e coreanasGrade de caracteresLargura da pontuação chinesaTipografia do textoAberturas desenhadasAtributos de títuloImagens nos designs de páginaTextos, fios e caixas nos designs de páginaBoxesPaleta de cores semânticaCabeços e fólios
- Também usa
- Quebra de linha em chinêsSair da grade de propósitoFaixa de capítulo em largura totalEstilos de parágrafoFiguras e tabelas como recursos
- Tipografia
- LXGW WenKai TC, Noto Sans TC, Andika (SIL OFL 1.1)
- Materiais
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, original)
- Lesson 2’s vignette: the shuttle of a loom, a watercolour (Generated With Diffusion Models, original)
- Lesson 3’s vignette: a brush and its first stroke, a watercolour (Generated With Diffusion Models, original)
- Lesson 4’s vignette: a jade disc on a red cord, a watercolour (Generated With Diffusion Models, original)
Preparo
#1 · Uma sílaba sobre cada caractere
O código é a resposta curta logo acima. {人之初|rén zhī chū} dá três leituras a três caracteres, separadas pelos espaços: cada sílaba fica centralizada sobre o caractere, e a linha pode quebrar entre eles. A leitura não ocupa espaço próprio. Ela fica no vão entre as linhas, aqui 54 − 26 = 28 pt, e um vão mais estreito que a leitura gera o aviso rubyExceedsLeading. Já uma sílaba mais larga que o caractere ocupa espaço: ela alarga a caixa desse caractere, e numa linha centralizada os caracteres seguintes saem da grade. As leituras usam o corpo em que as sílabas mais largas da amostra, xiāng e zhuān, ainda cabem sobre um caractere, 0,38 em (9,9 pt): cada dístico tem oito caracteres e cada caractere mantém o quadrado. Com 0,45 em, 性相近,習相遠 se esticaria até oito caracteres e meio e abriria vãos em volta de 相.
#2 · O título mantém a sua leitura
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) } } },
] } };
O texto de um design não imprime leituras, por isso o título não pode vir do design da abertura. O título de nível 1, 第一課, desenha a faixa, a ilustração e o selo vermelho; o título da lição é o título de nível 2 logo abaixo, um título simples em 初号 que o compositor de texto compõe com o pinyin. reserve: false deixa a faixa e a ilustração fora da altura do título, e span: 'page' as pinta por baixo do texto.
O design de um título ignora parity, por isso a ilustração tem um elemento de cada lado da página: {attr.left} a 14 mm da borda esquerda e {attr.right} a 14 mm da direita. As lições em páginas pares escrevem # 第一課 {left="sprout"} e as das ímpares {right="shuttle"}, de modo que cada ilustração fica do lado externo da página dupla; o elemento cujo atributo falta não desenha nada.
#3 · Seis quadriculados a partir de um atributo
// 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="人之本不相以"} passa ao design os seis caracteres num único atributo. Na LXGW WenKai TC, todo caractere chinês tem um eme de largura, de modo que um tracking igual ao passo dos quadriculados menos um eme (18,4 − 10,6 mm) leva cada caractere ao quadriculado, e um único elemento de texto preenche a fileira. O quadriculado é um SVG desenhado em código: uma moldura vermelha e uma cruz tracejada.
#4 · Cada fonte carrega os seus próprios caracteres
// 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)))]);
O Fontsource corta cada fonte chinesa em cerca de cem arquivos por intervalo de caracteres. A fonte Kai compõe a amostra inteira e carrega os arquivos que contêm os caracteres. A fonte Hei compõe só os selos, os rótulos e o rodapé, por isso recebe esse texto e baixa poucos arquivos. A Andika vem de loadFonts, que acrescenta o arquivo latin-ext quando o texto tem letras além do Latin-1, como ǎ e ǐ.
#5 · A pontuação de Hong Kong vem do locale
// 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 define as regras de Hong Kong: pontuação de largura inteira e as regras básicas de quebra de linha, que nenhum dístico daqui precisa. A LXGW WenKai TC desenha a vírgula e o ponto no meio do quadrado, como Hong Kong e Taiwan os imprimem, e é por isso que esta cartilha é de Hong Kong. Uma cartilha da China continental também é composta em Kai, em caracteres simplificados, com a vírgula e o ponto no canto inferior esquerdo do quadrado. Mas o Fontsource não tem uma Kai de texto para o chinês simplificado, e a tradicional colaria esses sinais no caractere seguinte, por isso uma página continental nestas Receitas usa a Noto Serif SC, a fonte Song da página de romance continental.
A receita completa
// ═══ 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'),
O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)
Variações
#Mostre a grade enquanto compõe a página
show: true desenha no canvas os doze quadrados de cada linha; o PDF os deixa de fora, a menos que renderToPdf receba characterGrid: true.
- grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11 },
+ grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11, show: true },#Ponha o zhuyin ao lado dos caracteres
As leituras em bopomofo ficam numa coluna à direita de cada caractere; a cartilha com zhuyin as compõe numa página vertical.
Erros comuns
Erro comum
As leituras são impressas no texto, não em designs, legendas nem células
As leituras rubi são desenhadas em parágrafos, títulos, itens de lista, citações e boxes. Um elemento de texto de design (uma abertura, um cabeço, um selo), uma legenda, uma nota de rodapé e uma célula de tabela imprimem os caracteres-base sem as leituras. Um título que precisa do seu pinyin é um título sem design próprio: desenhe o que está em volta dele (uma faixa, o número da lição) com o design do título anterior, cujos elementos com reserve: false são pintados sob o texto de uma abertura span: 'page'. Rubi: leituras em pinyin e zhuyin →
Erro comum
Componha a pontuação de cada região com uma fonte dessa região
As larguras da pontuação levam o branco de cada sinal para o lado em que a região do documento o coloca, não para o lado em que a fonte o desenha: com zh-Hans, uma vírgula Kaiming mantém a metade esquerda da sua caixa, onde uma fonte simplificada desenha o glifo, e cede a metade direita. Uma fonte tradicional centraliza ,。 na caixa, então a metade que sai leva parte do glifo e a vírgula fica colada no caractere seguinte. LXGW WenKai TC, a única Kai de texto do Fontsource, faz isso em texto simplificado. Componha o texto, as notas e as citações continentais em Noto Serif SC ou Noto Sans SC, deixe as fontes TC para zh-Hant e use uma fonte de pincel simplificada (Ma Shan Zheng) só em linhas de destaque, onde o texto de design não aplica larguras de pontuação. Ela também desenha formas herdadas que nem o padrão continental nem o de Taiwan imprimem, 為 com o topo 爫 de 爲 e 令 (em 冷, 領) com o pé de 卩: confira os caracteres que uma página compõe com ela. Largura da pontuação chinesa →
Erro comum
Fontes chinesas são carregadas em fatias, pelo bloco cjk
O Fontsource serve uma família chinesa, japonesa ou coreana em cerca de cem arquivos por peso, cada um com um intervalo de caracteres. loadFonts baixa só o arquivo latin, então na tela os caracteres chineses vêm de uma fonte do sistema e são medidos errado, e o fontsourceProvider entrega ao PDF esse arquivo latin, que os imprime como caixas vazias. Inclua o bloco cjk do kit, chame loadCjkFonts(FONTS, markdown) depois de loadFonts (uma vez por voz, com o texto que ela compõe, quando o livro usa várias fontes CJK) e passe a renderToPdf fontProvider: cjkPdfProvider: os dois pegam os arquivos que contêm os caracteres do texto. Fontes chinesas, japonesas e coreanas →
Erro comum
Marque o documento como zh-Hans ou zh-Hant, não com LANG
As edições de uma receita são en e es, mas uma amostra chinesa é chinesa nas duas: `locale: LANG` a marcaria como inglês ou espanhol, hifenizaria as suas palavras latinas, chamaria as suas figuras de Figure ou Figura e daria ao PDF o idioma errado. Desde o postext 1.30 a marcação é também o idioma em que o texto é composto (em que é medido, pintado e incorporado), então, sob uma marcação inglesa ou espanhola, uma fonte chinesa compõe com outras formas os algarismos e a pontuação que divide com o texto latino, e as linhas quebram em outro ponto. Escreva você mesmo a marcação: 'zh-Hans' (convenções da China continental: quebra de linha GB, pontuação Kaiming) ou 'zh-Hant' (Taiwan: pontuação de largura inteira centralizada); 'zh-HK' para Hong Kong. Um 'zh' sozinho é lido como chinês simplificado continental. Uma amostra japonesa leva 'ja' (armadilha ja-locale-tag). Quebra de linha em chinês →
Aviso de diagramação · rubyExceedsLeading
Leituras encostam na linha vizinha
Por quê. Um parágrafo com leituras rubi acima ou abaixo do texto tem um vão entre linhas mais estreito que as leituras: elas ocupam a entrelinha e encostam na linha vizinha.
Correção. Componha o parágrafo com mais entrelinha (pelo menos o corpo mais `cjk.ruby.fontSize`) ou reduza as leituras. Docs →
-
Esta receita não oferece PDF. O
fontsourceProviderdo kit incorpora só o arquivo latin de uma fonte, e as letras com tom ā ǎ ǐ ǒ ǔ estão no latin-ext, de modo que o PDF as perderia e o postext-pdf avisaria cada uma comomissingGlyph. Se precisar de um, componha as leituras numa fonte chinesa, cujos arquivos ocjkPdfProviderescolhe caractere a caractere. -
Confira cada caractere dos quadriculados com as formas padrão da região. A LXGW WenKai TC desenha 為 com a parte de cima 爫 de 爲, uma forma mais antiga que passa no texto corrido, como em 老何為 e 為人子 aqui, mas não num quadriculado que uma criança de Hong Kong copia. Por isso a lição três treina 幼.
Créditos
- Receita
- Ignacio Ferro
- Texto
- 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 · domínio público
- The pinyin, the notes for families and the translations · Postext Cookbook · CC BY 4.0
- Imagens
- 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 · original
- Lesson 2’s vignette: the shuttle of a loom, a watercolour · Generated With Diffusion Models · original
- Lesson 3’s vignette: a brush and its first stroke, a watercolour · Generated With Diffusion Models · original
- Lesson 4’s vignette: a jade disc on a red cord, a watercolour · Generated With Diffusion Models · original
- Fontes
- LXGW WenKai TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1) · Andika (SIL OFL 1.1)
- Código
- MIT, como o Postext
Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)


