跳到主要内容
食谱编号50

排版食谱 · 第6章 · 框与注释

带安全提示的产品说明书

一本德文电水壶说明书:WARNUNG和VORSICHT标注框把警告三角放在信号色的色带上,图和表的标签也是德文。

第2–3页,共7页

  • 英文样例:尚无中文版本
  • 成品尺寸148 × 210 mm
  • 1栏
  • Red Hat Text 9.3/12.8
  • Red Hat Display
  • Red Hat Mono
  • 7页
  • 难度
  • Postext 1.65.0
  • 排版用时182 ms
  • 184行代码

简单来说

一本七页的德语电热水壶说明书。示例演示怎样做带警示三角的安全提示,按危险程度分别用红色或琥珀色。

成品一览

一本七页的使用说明书,产品是虚构的电水壶Verra W1,德文,A5开本。安全页把两个危险等级排成标注框:一条信号色的色带沿左侧竖下,承载警告三角;同色的细边框把框封住,WARNUNG用红色,VORSICHT用琥珀色。HINWEIS这一级针对的是器具损坏,它不用色带和三角,改为圆角的蓝绿色底色。标注框上方的段落把三个信号词都排成实心标签。第3页有一张零件图,编号引线在图例上方;第4页的按键名是描边标签,旁边是大号步骤编号。故障排除表跨第6、7两页。题注写作Abbildung和Tabelle,拆开的表格在两页上都标有Fortsetzung。

这道食谱解答

  • 怎样做带图标、色条和圆角的注释、提示或警告框?
  • 怎样做行内标签:键盘按键、标签、练习用的词库?
  • 怎样定制列表:每级的项目符号、(a)/(i)编号、任务复选框、保持在网格上的间距?
  • 怎样加一幅带编号题注的图,并在正文里引用它(“见图3.2”)?
  • 怎样做一个有表头行、合并单元格、栏宽和逐格对齐的表?
  • 怎样把长表跨页拆分,并重复表头、加上“续表”标记?
  • 怎样让“图”和“表”的标签使用文档的语言?

简短回答

script.js · 第29–47行在完整代码中
const BAND = 8.5; // mm: a stripe on the side is the icon's column; the icon is centred on it
const [TITLE, TITLE_GAP] = [8.6, 2.4]; // pt; a box title's line is 1.2 times its size
const PAD_Y = (2 * LEAD - 1.2 * TITLE - TITLE_GAP) / 2; // pt: title and padding fill two lines
const notice = (id, hue, ink, icon) => ({ id, backgroundEnabled: false,
  stripe: { enabled: true, side: 'left', width: mm(BAND), color: col(hue) },
  border: { enabled: true, color: col(hue), width: pt(0.75) }, // closes the band into a frame
  icon: { kind: 'resource', resourceId: icon, size: mm(5.6), align: 'top' },
  padding: { top: pt(PAD_Y), right: mm(3.2), bottom: pt(PAD_Y), left: mm(3.2) },
  titleStyle: { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(TITLE), color: col(ink),
    textTransform: 'uppercase', letterSpacing: pt(1.3), gap: pt(TITLE_GAP) },
  body: { fontSize: pt(8.8), lineHeight: pt(LEAD) }, // on the grid: a box is whole lines tall
  lists: { color: col(ink), gap: mm(2) }, marginTop: pt(LEAD), marginBottom: pt(0) });
const calloutStyles = [
  notice('warnung', 'warning', 'warning', 'triangle-white'), // white triangle, red '!'
  notice('vorsicht', 'caution', 'ink', 'triangle-ink'), // amber type would fail contrast
  { ...notice('hinweis', 'brand', 'brand'), stripe: { enabled: false }, border: { enabled: false },
    backgroundEnabled: true, background: col('tint'), borderRadius: mm(2), // property damage:
    icon: { kind: 'resource', resourceId: 'info', size: mm(4.6) } }, // no band, an icon column
];

用料

类型
Red Hat Text, Red Hat Display, Red Hat Mono(SIL OFL 1.1)
素材
无:所有图片都用代码绘制

做法

#1 · 承载三角的色带

代码见上文的简短回答。stripe沿左边缘画出色带。标注框带侧边竖条时,图标放在竖条正中,而不另占一栏(标注框样式);align: 'top'让图标顶边与标题顶边平齐。同色的border把色带封成边框;没有它,框内文字就会立在光秃秃的页面上,旁边只是一根彩色竖条。PAD_Y是算出来的,让标题、标题后的间距和上下内边距合起来正好是12.8 pt网格的两行。正文沿用网格行距,所以每个框的高度都是整行数(WARNUNG 10行,VORSICHT 8行),marginTop: pt(LEAD)则让第2页的两个框之间恰好空一行。VORSICHT的色带和边框保留琥珀色,标题和项目符号改用墨色:琥珀色在白底上的对比度是2.0:1,而小字需要4.5:1。HINWEIS从同一个基础样式出发(...notice(…)),关掉色带和边框,于是它的信息图标自占一栏,borderRadius把一块普通底色做成圆角。

#2 · 图和表的德文名称

script.js · 第51–59行在完整代码中
const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
// The built-in types in German, Abbildung and Tabelle; a table is captioned over its head.
const resourceTypes = defaultResourceTypes('de').map((type) => ({ ...type, ...counted,
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));
const tableStyle = { rules: 'horizontal', borderColor: col('rule'), borderWidth: pt(0.5),
  headerBackground: col('ink'), headerColor: col('paper'), headerFontFamily: MONO,
  headerFontSize: pt(7.6), bodyFontSize: pt(8.2), cellPadding: mm(1.3),
  // The engine's own German strings are '(Forts.)' and 'Wird fortgesetzt': these spell them out.
  continuedSuffix: '(Fortsetzung)', continuesMarker: 'Fortsetzung auf der nächsten Seite' };

locale: 'de'让说明书使用德文断词,也让内置类型用德文名称:不做别的设置,题注会写成Abbildung 2.1和Tabelle 5.1,拆分表格前一部分下方的说明会写Wird fortgesetzt。表格样式把这条说明和题注的后缀写成完整的说法;传入defaultResourceTypes('de')则是为了改两处。第一处是counted:{n}配合resetOn: 'never'在整本说明书中连续计数(Abbildung 1,Tabelle 1到3),而不是每节重新开始。只有表格类型设了captionStyle.position: 'above',所以表格的题注在表头上方,零件图的题注仍在图下。

#3 · 用标签排按键、信号词和零件编号

script.js · 第63–71行在完整代码中
const filled = (id, fill, ink) => ({ id, fontFamily: DISPLAY, bold: true, fontSize: em(0.82),
  background: col(fill), color: col(ink), borderWidth: pt(0), paddingX: em(0.45) }); // no outline
const chipStyles = [
  { id: 'taste', fontFamily: MONO, bold: true, fontSize: em(0.92), backgroundEnabled: false,
    borderColor: col('ink'), borderWidth: pt(0.6), borderRadius: pt(2.2), paddingX: em(0.4) },
  filled('warnung', 'warning', 'paper'), filled('vorsicht', 'caution', 'ink'),
  filled('hinweis', 'brand', 'paper'), { ...filled('nr', 'brand', 'paper'), fontSize: em(0.95),
    borderRadius: em(1) }, // a part number, round like the drawing's
];

taste用等宽字体为按键名描边、不填色,就像按钮上印的标签那样。信号词标签用各自标注框的颜色填充,琥珀色标签里的字用墨色,与VORSICHT标题一致。nr给零件编号设的圆角半径大于其高度的一半,所以它们成了圆片,与零件图上的编号圆圈一样。标签尺寸以周围文字的em为单位:按键在正文中是8.6 pt,在表格单元格中是7.5 pt(行内标签样式)。

#4 · 站在基线上的步骤编号

script.js · 第75–80行在完整代码中
const orderedLists = { separator: '', fontFamily: DISPLAY, fontWeight: 800, color: col('brand'),
  numberFontSize: pt(15), gap: mm(3), itemSpacing: pt(5), marginTop: pt(LEAD / 2),
  marginBottom: pt(0), numberVerticalOffset: pt(-1) }; // gotcha: list-number-centred
const unorderedLists = { color: col('brand'), gap: mm(2), marginTop: pt(0), marginBottom: pt(0),
  levels: [{ level: 2, bulletChar: '–', indent: mm(6.5) }, // at a step's text: number + 3 mm gap
    { level: 3, bulletChar: '–', color: col('muted') }] }; // teal •, teal –, grey –

步骤是一个有序列表,编号用15 pt的Red Hat Display 800,蓝绿色,不带分隔符。列表编号在其第一行中垂直居中,而不是站在基线上,所以一个15 pt的数字排在9.3 pt的文字旁时,会比该行低约1 pt。numberVerticalOffset: pt(-1)是在截图上量出的值,把数字的底边提到基线上。itemSpacing让步骤之间相隔5 pt,给大号数字留出空间。嵌套在步骤下的项目从6.5 mm处开始,与步骤正文对齐;它们是蓝绿色短横线,第三级用灰色短横线(有序列表)。

#5 · 反白方标里的节号

script.js · 第84–94行在完整代码中
const H1 = 14, TAB = 2 * LEAD - 3.6, PAD = (TAB - H1 * 1.2) / 2; // pt: a square 2 lines less 3.6
const face = { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(H1), lineHeight: 1.2 }; // both
const section = { level: 1, numberingTemplate: '{1}', // {number}: 1, 2, 3 …
  breakBefore: { enabled: false }, marginTop: pt(LEAD), marginBottom: pt(LEAD / 2), // run on
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'text', id: 'tab', content: '{number}', ...face, color: col('paper'), align: 'center',
      box: { backgroundColor: col('brand'), padding: pad(PAD) },
      placement: pin('container', 'top-left', 0, 0, { width: pt(TAB) }) },
    { kind: 'text', id: 'title', content: '{titleText}', ...face, color: col('ink'),
      overflow: 'wrap', box: { padding: { top: pt(PAD) } }, placement: pin('#tab', 'right-of', 3) },
  ] } } };

每一节都是栏内的一级标题,由一个版面设计槽位绘制。方标在蓝绿色方块上用白色印出{number}(由numberingTemplate: '{1}'填入),标题从其右侧3 mm处开始。节号和标题的字号、行高相同,所以同样的上内边距让它们落在同一条基线上。方标是22 pt见方,比12.8 pt网格的两行少3.6 pt,所以标题不会超出两条网格线。封面也是一级标题,只是用了一个不编号的标题样式,因此Sicherheitshinweise是第1节。

#6 · 可拆分、带合并单元格的故障排除表

script.js · 第297–315行在完整代码中
function faultTable(tsv) { // the first line is the head row; the widths are weights
  let m = { ...parseTSV(tsv, { headerRows: 1 }), columnWidths: [30, 34, 36] };
  for (let r = 2, top = 1; r < m.rows.length; r++) { // a rowspan per fault: no cut runs through it
    if (m.rows[r][0].content) top = r; // mergeCells hides what it covers: merged-cells-hiddenby
    else m = mergeCells(m, { start: { row: top, col: 0 }, end: { row: r, col: 0 } });
  }
  return m;
}
const fold = (rows, columnWidths) => ({ columnWidths, rows: rows.slice(0, rows.length / 2) // 2 up
  .map((row, k) => [...row, ...rows[k + rows.length / 2]]) });
const legend = fold(parseTSV(parts).rows.map(([chip, name]) => [{ ...chip, align: 'center' },
  name]), [7, 43, 7, 43]); // each part's number chip centred in its narrow column
const HERE = { placement: { position: 'here' } }; // at the resource's ::resource line
const table = (id, caption, model, styleId = 'bare', where = HERE) => ({ id, typeId: 'table',
  kind: 'table', caption, table: { model, styleId }, createdAt: 0, updatedAt: 0, ...where });
const tables = [table('legende', 'Teile des Verra W1', legend),
  table('daten', 'Kenndaten des VW-170', fold(parseTSV(data).rows, [20, 30, 20, 30])),
  table('stoerungen', 'Störungen und ihre Behebung', faultTable(faults), null, // the house style,
    { placement: { position: 'top' } })]; // a float: it heads the page after its citation

每个表格都是单独内容文件里的TSV。在故障排除数据中,第一个单元格为空的行属于上方的故障,mergeCells把这些首格合并成一个高单元格,并把被覆盖的单元格标为隐藏。parseTSV不设表头行,所以用headerRowCount: 1声明,这一行就是第7页上重复的那一行。这个表格比一页还高,所以要拆分,在下一页接续。position: 'top'把它设为第6页顶部的浮动体;从postext 1.25起,设为'here'时它也会同样拆分,但表后的文字在第7页上会从更低的位置开始,最后几行会被挤到第8页。拆分落在行与行之间,从不穿过合并单元格,因此每个故障都与它的原因在同一页(比页面还高的表格)。它在第5页被引用,排在第6页顶部,这是引用之后第一个能容纳顶部浮动体的页面。fold把一个列表的两半并排排出,图例和技术数据都用它;图例用align: 'center'让编号标签居中。

#7 · 给纸上读者的网址和二维码

“废弃处理”一节用普通的Markdown链接指向Stiftung EAR(德国废旧电器登记机构)的回收点查询页。在屏幕上和PDF中它仍是链接;纸上的读者无法点击,所以links: { print: 'notes', show: 'both' }在链接文字后加一个注号,把网址和二维码一起排在页脚。urlDisplay: 'short'去掉印出网址的https://和末尾的斜杠,qr: { size: mm(12), side: 'start' }把12毫米的二维码放在注文行前。链接注就是脚注,所以字号、颜色和注线由footnotes决定。这条注占去第7页三行,因此缩短了废弃处理一段、表格中的一条处理方法和版权说明,手册仍是七页(印刷版中的链接)。

完整食谱

沙盒
// ═══ Postext Cookbook · Nº 050 · Product manual with safety notices ════════════════
// https://postext.dev/en/cookbook/product-manual-warnings
// Code: MIT · Text: original, in German (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: Red Hat Text, Red Hat Display, Red Hat Mono (SIL OFL 1.1) · Needs postext ≥ 1.65.0
import {
  buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage, parseTSV,
  mergeCells, defaultResourceTypes, inlineSvgFonts } from 'https://esm.sh/postext';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'product-manual-warnings';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#1a1f24', paper: '#ffffff', // a blue-black on white
  brand: '#10727b', tint: '#e4f0f1', // the house teal (5.7:1 on white) and its pale tint
  warning: '#d62e1f', caution: '#f2a900', // the signal colours of WARNUNG and VORSICHT
  rule: '#cfd5da', muted: '#5b6570' }; // hairlines; running heads and notes
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.brand }) // the defaults
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Red Hat Text', 'Red Hat Display', 'Red Hat Mono'];
const PAGE = { w: 148, h: 210, top: 19, bottom: 19.4, inner: 17, outer: 13 }; // mm: A5, mirrored
const LEAD = 12.8; // pt: the body's leading and baseline grid, 38 lines to the page
const pin = (to, edge, x = 0, y = 0, size) => ({ anchor: { to, edge },
  offset: { x: mm(x), y: mm(y) }, ...(size && { size }) });
const pad = (y, x = 0) => ({ top: pt(y), bottom: pt(y), left: pt(x), right: pt(x) }); // pt

// #region answer: signal-word boxes: a band in the hazard's colour carries its triangle
const BAND = 8.5; // mm: a stripe on the side is the icon's column; the icon is centred on it
const [TITLE, TITLE_GAP] = [8.6, 2.4]; // pt; a box title's line is 1.2 times its size
const PAD_Y = (2 * LEAD - 1.2 * TITLE - TITLE_GAP) / 2; // pt: title and padding fill two lines
const notice = (id, hue, ink, icon) => ({ id, backgroundEnabled: false,
  stripe: { enabled: true, side: 'left', width: mm(BAND), color: col(hue) },
  border: { enabled: true, color: col(hue), width: pt(0.75) }, // closes the band into a frame
  icon: { kind: 'resource', resourceId: icon, size: mm(5.6), align: 'top' },
  padding: { top: pt(PAD_Y), right: mm(3.2), bottom: pt(PAD_Y), left: mm(3.2) },
  titleStyle: { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(TITLE), color: col(ink),
    textTransform: 'uppercase', letterSpacing: pt(1.3), gap: pt(TITLE_GAP) },
  body: { fontSize: pt(8.8), lineHeight: pt(LEAD) }, // on the grid: a box is whole lines tall
  lists: { color: col(ink), gap: mm(2) }, marginTop: pt(LEAD), marginBottom: pt(0) });
const calloutStyles = [
  notice('warnung', 'warning', 'warning', 'triangle-white'), // white triangle, red '!'
  notice('vorsicht', 'caution', 'ink', 'triangle-ink'), // amber type would fail contrast
  { ...notice('hinweis', 'brand', 'brand'), stripe: { enabled: false }, border: { enabled: false },
    backgroundEnabled: true, background: col('tint'), borderRadius: mm(2), // property damage:
    icon: { kind: 'resource', resourceId: 'info', size: mm(4.6) } }, // no band, an icon column
];
// #endregion

组合好的script.js可以直接运行:把它粘贴到任何页面的模块脚本中,或在CodePen上打开这道食谱。 GitHub上的食谱文件夹 ↗ (在新标签页中打开)

变化

#按节给图和表编号

在模板中加入节号,并在每节重置,零件图就变成Abbildung 2.1,故障排除表变成Tabelle 5.1。

-const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
+const counted = { numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal' };

常见问题

易错点

'top'浮动体默认排在引用页的下一页,除非允许它置于引用页顶

默认情况下浮动体不会排在自己的引用之前,所以在第N页引用的整页宽'top'浮动体会出现在第N+1页的顶部。在资源或其类型的defaultPlacement上设置placement.citingPage: true(或者对全书设置layout.floatsAtCitingPage,自postext 1.25起),它就改为置于第N页顶部,引用处之上的文字移到它下方,前提是它不超过layout.maxTopFraction且引用行仍留在该页。它不会置于章首页或强制分页之后的页面顶部:那时仍排在下一页,而'auto'或'bottom'可以占用引用页的底部。 图的放置 →

易错点

合并单元格需要hiddenBy占位:使用mergeCells

单元格按其在行数组中的位置排布,所以合并单元格延伸到的地方需要标记hiddenBy的占位单元格;像HTML那样省略它们,后面的每一列都会错位。用mergeCells来合并。从postext 1.5起,网格不规则的表会在doc.contentWarnings中报告为raggedTableGrid,parseTSV(text, { headerRows })会标记表头行。 由数据生成的表 →

易错点

列表编号以首行居中,而不是立在基线上

有序列表的编号用Canvas的'middle'基线绘制,位于该项首行基线之上0.3 em(按正文字号)处,所以换用别的字体或加大numberFontSize的编号会从这里向上下两个方向扩展,而不是立在行上:展示字体会偏高,大号的步骤编号会横跨首行。用orderedLists.numberVerticalOffset调整位置,并按实际尺寸检查效果。目录编号从postext 1.5起落在基线上;列表编号仍然居中。 编号列表 →

  • 各栏齐底会把收尾一页的框推到该页最后一条网格线上,于是页面上剩下的空间都出现在框的上方(各栏齐底)。第2页的文字是调整过的,正好填满一栏。删掉一个VORSICHT项目,框仍然结束在页脚处,但两个框之间的空隙会从4.5 mm增大到13.6 mm;如果设headings: { balancing: { enabled: false } },框会保持在WARNUNG下方一行处,页面则在离底部两行的地方结束。

致谢

文本
原创文字, CC BY 4.0
字体
Red Hat Text (SIL OFL 1.1) · Red Hat Display (SIL OFL 1.1) · Red Hat Mono (SIL OFL 1.1)
沙盒