En pocas palabras
Páginas de una cartilla infantil de Hong Kong. Enseña a escribir la pronunciación en letras latinas encima de cada carácter chino, con cuadrículas para practicar la escritura.
Lo que vas a componer
Dos dobles páginas de 《蒙學誦讀》, una cartilla inventada de Hong Kong, donde los niños leen en voz alta el Clásico de los tres caracteres en mandarín (putonghua). Cada página es una lección de cuatro pareados en kai de 一号 (26 pt), y cada carácter va bajo su sílaba de pinyin. Las sílabas van en Andika porque dibuja la a y la g de un solo piso que imprimen los libros escolares chinos. Una banda verde pálido lleva la etiqueta roja de la lección, una pequeña acuarela y el título en 初号 (42 pt) con su propia lectura. Debajo del texto, seis cuadrículas de escritura (田字格) guardan los caracteres para copiar, y una nota cuenta a la familia qué dicen los versos. Su pareja en español es la cartilla de sílabas en chips, donde cada sílaba es un chip de color en lugar de una lectura sobre un carácter.
Una cartilla se aparta a propósito de las normas del libro chino. Un niño lee pocos caracteres y grandes, así que la línea lleva doce de 26 pt donde un libro pone entre 25 y 40 de 10,5 pt, y el interlineado pasa un poco del doble del cuerpo para que quepan las lecturas. Cada pareado va centrado en su propia línea, sin justificar ni sangrar. El texto va en kai, la letra que sigue al pincel, porque enseña los trazos que el niño aprende a escribir; un libro lo compondría en song.
Esta receta responde a
- ¿Cómo pongo pinyin sobre los caracteres chinos?
La respuesta corta
// {人之初|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
- Funciones
- Ruby: lecturas en pinyin y zhuyinFuentes chinas, japonesas y coreanasRetícula de caracteresAnchura de la puntuación chinaTipografía del textoAperturas diseñadasAtributos de títuloImágenes en los diseños de páginaTextos, filetes y cajas en los diseños de páginaRecuadrosPaleta de color semánticaCabeceras y folios
- También usa
- Corte de líneas en chinoSalir de la rejilla a propósitoBanda de capítulo a todo el anchoEstilos de párrafoFiguras y tablas como recursos
- Tipografía
- LXGW WenKai TC, Noto Sans TC, Andika (SIL OFL 1.1)
- Recursos
brush-800.jpgjade-800.jpgshuttle-800.jpgsprout-800.jpg- Las cuadrículas de escritura, dibujadas en código con la paleta de la página (Postext Cookbook, CC BY 4.0)
- La viñeta de la lección 1: un brote, una acuarela (Generated With Diffusion Models, original)
- La viñeta de la lección 2: la lanzadera de un telar, una acuarela (Generated With Diffusion Models, original)
- La viñeta de la lección 3: un pincel y su primer trazo, una acuarela (Generated With Diffusion Models, original)
- La viñeta de la lección 4: un disco de jade con un cordón rojo, una acuarela (Generated With Diffusion Models, original)
Elaboración
#1 · Una sílaba sobre cada carácter
El código es la respuesta corta de arriba. {人之初|rén zhī chū} da tres lecturas a tres caracteres, separadas por los espacios: cada sílaba se centra sobre su carácter, y la línea puede cortarse entre ellos. La lectura no ocupa sitio propio. Va en el hueco entre líneas, aquí 54 − 26 = 28 pt, y un hueco más estrecho que la lectura se avisa como rubyExceedsLeading. Una sílaba más ancha que su carácter sí ocupa sitio: ensancha la caja de ese carácter, y en una línea centrada los caracteres que la siguen se salen de la retícula. Las lecturas llevan el cuerpo con el que las sílabas más anchas de la muestra, xiāng y zhuān, aún caben sobre un carácter, 0,38 em (9,9 pt): cada pareado mide ocho caracteres y cada carácter conserva su casilla. Con 0,45 em, 性相近,習相遠 se estiraría hasta ocho caracteres y medio y abriría huecos alrededor de 相.
#2 · El título conserva su lectura
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) } } },
] } };
El texto de un diseño no imprime lecturas, así que el título no puede salir del diseño de la apertura. El encabezado de primer nivel, 第一課, dibuja la banda, la viñeta y la etiqueta roja; el de la lección es el encabezado de segundo nivel que va debajo, sin diseño propio, en 初号, y el compositor de texto lo compone con su pinyin. reserve: false deja la banda y la viñeta fuera de la altura del título, y span: 'page' los pinta debajo del texto.
Un diseño de encabezado no atiende a parity, así que la viñeta tiene un elemento a cada lado de la página: {attr.left} a 14 mm del borde izquierdo y {attr.right} a 14 mm del derecho. Las lecciones de página par escriben # 第一課 {left="sprout"}, y las de impar, {right="shuttle"}, de modo que cada viñeta queda en el lado exterior de la doble página; el elemento cuyo atributo falta no dibuja nada.
#3 · Seis cuadrículas con un solo 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="人之本不相以"} pasa al diseño los seis caracteres en un atributo. En LXGW WenKai TC cada carácter chino mide un cuadratín, así que un espaciado igual al paso de las cuadrículas menos un cuadratín (18,4 − 10,6 mm) lleva cada carácter a su cuadrícula, y un solo elemento de texto llena la fila. La cuadrícula es un SVG dibujado en código: un marco rojo y una cruz de trazos.
#4 · Cada fuente carga sus propios 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)))]);
Fontsource corta cada fuente china en un centenar de archivos por intervalos de caracteres. La kai compone toda la muestra y carga los archivos que contienen sus caracteres. La hei solo compone las etiquetas, los rótulos y el pie, así que recibe ese texto y descarga unos pocos archivos. Andika llega con loadFonts, que añade el archivo latin-ext cuando el texto tiene letras más allá de Latin-1, como ǎ y ǐ.
#5 · La etiqueta de idioma trae la puntuación de Hong Kong
// 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 fija las reglas de Hong Kong: puntuación de ancho completo y el juego básico de reglas de corte, que aquí ningún pareado necesita. LXGW WenKai TC dibuja la coma y el punto en el centro de la casilla, como los imprimen Hong Kong y Taiwán, y por eso esta cartilla es de Hong Kong. Una cartilla continental también va en kai, en caracteres simplificados y con la coma y el punto abajo a la izquierda de la casilla. Pero Fontsource no tiene una kai de texto para el chino simplificado, y la tradicional pegaría esos signos al carácter siguiente, así que en este Recetario una página continental toma Noto Serif SC, la song de la página de novela continental.
La receta 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 = 'es'; // @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'),
El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)
Variantes
#Muestra la retícula mientras compones
show: true dibuja en el canvas las doce casillas de cada línea; el PDF las omite salvo que renderToPdf reciba characterGrid: true.
- grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11 },
+ grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11, show: true },#Pon el zhuyin al lado de los caracteres
Las lecturas en bopomofo se colocan en una columna a la derecha de cada carácter; la cartilla de zhuyin las compone en una página vertical.
Errores frecuentes
Error frecuente
Las lecturas se imprimen en el texto, no en diseños, pies ni celdas
Las lecturas ruby se dibujan en párrafos, títulos, elementos de lista, citas y recuadros. Un elemento de texto de un diseño (una apertura, una cabecera, una etiqueta), un pie, una nota al pie y una celda de tabla imprimen los caracteres base sin sus lecturas. Un título que necesita su pinyin es un título sin diseño propio: dibuja lo que lo rodea (una banda, el número de la lección) con el diseño del título anterior, cuyos elementos con reserve: false se pintan bajo el texto de una apertura span: 'page'. Ruby: lecturas en pinyin y zhuyin →
Error frecuente
Compón la puntuación de cada región con una fuente de esa región
Los anchos de la puntuación mueven el blanco de cada signo al lado donde lo pone la región del documento, no al lado donde lo dibuja la fuente: con zh-Hans, una coma Kaiming conserva la mitad izquierda de su caja, donde una fuente simplificada dibuja el signo, y cede la derecha. Una fuente tradicional centra ,。 en la caja, así que la mitad que se va se lleva parte del signo y la coma se pega al carácter siguiente. LXGW WenKai TC, la única Kai de texto de Fontsource, lo hace en texto simplificado. Compón el texto, las notas y las citas continentales en Noto Serif SC o Noto Sans SC, deja las fuentes TC para zh-Hant y usa una letra de pincel simplificada (Ma Shan Zheng) solo en líneas de exhibición, donde el texto de diseño no aplica anchos de puntuación. Además dibuja formas heredadas que no imprime ni el estándar continental ni el de Taiwán, 為 con el 爫 de 爲 y 令 (en 冷, 領) con el pie de 卩: revisa los caracteres que compone en cada página. Anchura de la puntuación china →
Error frecuente
Las fuentes chinas se cargan por fragmentos, con el bloque cjk
Fontsource sirve una familia china, japonesa o coreana en un centenar de archivos por peso, cada uno con un intervalo de caracteres. loadFonts solo descarga el archivo latin, así que en pantalla los caracteres chinos salen de una fuente del sistema y se miden mal, y fontsourceProvider entrega al PDF ese archivo latin, que los imprime como cajas vacías. Añade el bloque cjk del kit, llama a loadCjkFonts(FONTS, markdown) después de loadFonts (una vez por voz, con el texto que compone, si el libro usa varias fuentes chinas) y pasa a renderToPdf fontProvider: cjkPdfProvider: ambos toman los archivos que contienen los caracteres del texto. Fuentes chinas, japonesas y coreanas →
Error frecuente
Etiqueta el documento zh-Hans o zh-Hant, no con LANG
Las ediciones de una receta son en y es, pero una muestra china es china en las dos: `locale: LANG` la etiquetaría como inglés o español, separaría sus palabras latinas, llamaría Figure o Figura a sus figuras y daría al PDF un idioma equivocado. Desde postext 1.30 la etiqueta es además el idioma en el que se compone el texto (en el que se mide, se pinta y se incrusta), así que bajo una etiqueta inglesa o española una fuente china compone con otras formas sus cifras y la puntuación que comparte con el texto latino, y las líneas se parten por otro sitio. Escribe tú la etiqueta: 'zh-Hans' (convenciones de la China continental: corte GB, puntuación Kaiming) o 'zh-Hant' (Taiwán: puntuación de ancho completo centrada); 'zh-HK' para Hong Kong. Un 'zh' a secas se lee como chino simplificado continental. Una muestra japonesa lleva 'ja' (gotcha ja-locale-tag). Corte de líneas en chino →
Aviso de maquetación · rubyExceedsLeading
Lecturas pegadas a la línea vecina
Por qué. Un párrafo con lecturas ruby encima o debajo del texto tiene un hueco entre líneas más estrecho que las lecturas: ocupan el interlineado y tocan la línea vecina.
Solución. Compón el párrafo con más interlineado (al menos el cuerpo más `cjk.ruby.fontSize`), o reduce las lecturas. Documentación →
-
Esta receta no ofrece PDF. El
fontsourceProviderdel kit incrusta solo el archivo latin de una fuente, y las letras con tono ā ǎ ǐ ǒ ǔ están en latin-ext, así que el PDF las perdería y postext-pdf avisaría de cada una conmissingGlyph. Si lo necesitas, compón las lecturas con una fuente china, cuyos archivos eligecjkPdfProvidercarácter a carácter. -
Comprueba cada carácter de las cuadrículas con las formas normalizadas de la región. LXGW WenKai TC dibuja 為 con la parte de arriba de 爲 (爫), una forma antigua que pasa en el texto corrido, como en 老何為 y 為人子, pero no en una cuadrícula que copia un niño de Hong Kong. Por eso la lección tercera practica 幼.
Créditos
- Receta
- Ignacio Ferro
- Texto
- El Clásico de los tres caracteres (三字經), versos 1-32: el texto del 新刊三字經 de la Biblioteca Harvard-Yenching transcrito en zh.wikisource (revisión 10344699), con puntuación actual y 隣 escrito 鄰 · Traditionally attributed to Wang Yinglin (13th century); transcription by Wikisource editors · dominio público
- El pinyin, las notas para las familias y las traducciones · Postext Cookbook · CC BY 4.0
- Imágenes
- Las cuadrículas de escritura, dibujadas en código con la paleta de la página · Postext Cookbook · CC BY 4.0
- La viñeta de la lección 1: un brote, una acuarela · Generated With Diffusion Models · original
- La viñeta de la lección 2: la lanzadera de un telar, una acuarela · Generated With Diffusion Models · original
- La viñeta de la lección 3: un pincel y su primer trazo, una acuarela · Generated With Diffusion Models · original
- La viñeta de la lección 4: un disco de jade con un cordón rojo, una acuarela · Generated With Diffusion Models · original
- Fuentes
- LXGW WenKai TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1) · Andika (SIL OFL 1.1)
- Código
- MIT, como Postext
Editar este texto ↗ (se abre en una nueva pestaña)Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)


