# 配置：漫画

> comics设置：漫画页的画框和格间距、分格样式、嵌字、对白框样式和角色表

- HTML版本: https://postext.dev/zh/docs/configuration-comics
- 最后更新: 2026-10-10
- 阅读时间: 3分钟
- 其他语言: [en](https://postext.dev/en/docs/configuration-comics.md), [es](https://postext.dev/es/docs/configuration-comics.md), [ca](https://postext.dev/ca/docs/configuration-comics.md), [pt](https://postext.dev/pt/docs/configuration-comics.md), [ja](https://postext.dev/ja/docs/configuration-comics.md), [ar](https://postext.dev/ar/docs/configuration-comics.md)

## 简单来说

本页讲漫画页面的设置。你可以设定页面的画框和分格之间的间距。你可以选择嵌字的字体和字号。你可以定义对白框、旁白框和拟声词怎样画。你还可以列出角色，让每个角色用自己的样式说话。漫画指南讲解怎样写这些页面。

## 漫画

`comics`属性配置漫画页（`:::page`）、漫画条（`:::strip`）和跨页：分格从中切出的画框和格间距、分格样式、嵌字、对白框样式以及角色表。只有含漫画的文档才读取它；没有漫画的文档，排版结果与以前完全相同；含漫画却没有`comics`一节的文档，采用其语言的默认值。标记和嵌字的方式见[漫画](https://postext.dev/zh/docs/comics.md)。

```ts
const config: PostextConfig = {
  comics: {
    readingDirection: 'auto',
    gutter: { horizontal: { value: 5, unit: 'mm' }, vertical: { value: 2.5, unit: 'mm' } },
    panel: { borderWidth: { value: 0.8, unit: 'pt' }, borderStyle: 'rough' },
    panelStyles: [{ id: 'night', background: { hex: '#14142b', model: 'hex' }, borderColor: { hex: '#ffffff', model: 'hex' } }],
    lettering: { fontSize: { value: 8.5, unit: 'pt' }, textTransform: 'uppercase' },
    balloonStyles: [{ id: 'eerie', shape: 'wavy', italic: true }],
    cast: [{ id: 'maya', name: '玛雅' }, { id: 'tomas', name: '托马斯爷爷' }],
  },
};
```

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `readingDirection` | `'auto' \| 'ltr' \| 'rtl'` | `'auto'` | 一行中各分格的顺序。`'auto'`在从右到左的文档、竖排文档以及日文和繁体中文中从右往左读，否则按`artDirection`的方向读（简体中文和韩文也是如此）。页面的`direction`属性可以覆盖它。`page.binding: 'auto'`时，漫画从右往左读的书在右侧装订。 |
| `artDirection` | `'ltr' \| 'rtl'` | `'ltr'` | 画稿绘制时设想的阅读方向：日本漫画为`'rtl'`。 |
| `mirrorArt` | `boolean` | `false` | 把阅读方向与`artDirection`相反的页面上的画面左右翻转。分格写`mirror=false`时保持原画。 |
| `frame.margins` | `PageMargins` | 页面边距 | 漫画页自己的边距（`top`、`bottom`、`left`、`right`、`mirror`）。分格从这些边距以内的区域切出；未设置时，从页面的版心切出。 |
| `gutter.horizontal` | `Dimension` | `4mm` | 行与行之间的距离。页面的`gutter`属性可以覆盖它。 |
| `gutter.vertical` | `Dimension` | `2mm` | 同一行中左右相邻的分格之间的距离。 |
| `panel` | `PanelStyleConfig` | 见下文 | 默认的分格样式。 |
| `panelStyles` | `NamedPanelStyleConfig[]` | `[]` | 命名分格样式，用`:::page{style=…}`或`::panel{style=…}`选取。每个样式有一个`id`、一个可选的`name`（只用于编辑器界面）和分格样式的各个字段；未设置的字段沿用`panel`。 |
| `lettering` | `LetteringConfig` | 见下文 | 全书每个对白框的字体、字号和排印规则。 |
| `balloonStyles` | `BalloonStyleConfig[]` | 九种内置样式 | 按种类划分的对白框样式。内置样式始终存在；id与内置样式相同的条目修改该样式，新id的条目添加一个以`speech`为基础的样式。 |
| `cast` | `ComicCastMember[]` | `[]` | 角色（见[角色表](https://postext.dev/zh/docs/configuration-comics.md#角色表)）。 |
| `runningHeads` | `boolean` | `false` | 在漫画页上印书眉和页码。关闭时，漫画页只有分格，但它的页码照样计数。 |
| `viewerLeaf` | `ComicViewerLeafConfig` | 未设置 | 用于页面不是纸页的宿主：把漫画页排在一张印刷纸页上（`width`、`height`、`margins`），缩放到`fitWidth` px宽（高度最多`fitHeight` px），放在页面顶部。沙盒的HTML查看器设置它；它从不随文档保存。 |

### 分格样式

`comics.panel`以及`comics.panelStyles`的每个条目：

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `borderWidth` | `Dimension` | `1pt` | 边框粗细；`0`表示不画边框。边框沿分格的轮廓描画。 |
| `borderColor` | `ColorValue` | 黑色 | 边框颜色（可链接调色板）。 |
| `borderRadius` | `Dimension` | `0` | 矩形分格的圆角半径，最大为较短边的一半。被斜线切出的分格保持尖角。 |
| `borderStyle` | `'solid' \| 'rough' \| 'none'` | `'solid'` | 干净的直线、略带抖动的手绘线（以分格为种子生成，所以每次排版都一样），或者不画。 |
| `background` | `ColorValue` | 白色 | 画面下面的底色：空分格的颜色，以及完整显示画面时四周色带的颜色。 |
| `fit` | `'cover' \| 'contain'` | `'cover'` | `cover`裁切画面以填满分格，但绝不切进安全区；`contain`完整显示画面。 |
| `bleed` | `boolean` | `false` | 使用这个样式的分格，在每条贴着画框的边上越过画框，延伸到裁切线和出血位。 |

### 嵌字

`comics.lettering`设定全书的每个对白框。字号只有一个：对白框样式可以按比例缩放它（`fontScale`），文字从不为了塞进对白框而缩小。

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `fontFamily` | `string` | 按语言 | 嵌字字体。未设置时为`Comic Neue`；日文为`Zen Antique`，简体中文为`Noto Sans SC`，繁体中文为`LXGW WenKai TC`，阿拉伯文、波斯文和乌尔都文为`Playpen Sans Arabic`（`defaultComicFont(locale)`）。 |
| `fontSize` | `Dimension` | `7.5pt` | 对白框文字的字号。印刷页面上的漫画嵌字通常在7到9 pt之间。 |
| `lineHeight` | `number` | `1.15` | 行与行之间的距离，以字号的倍数表示。保持默认值时，竖排以及中文和日文的对白框取1.5，阿拉伯文取1.45。 |
| `color` | `ColorValue` | 黑色 | 文字颜色。 |
| `bold`、`italic` | `boolean` | `false` | 把全部嵌字排成粗体或斜体。中文、日文和阿拉伯文的嵌字从不倾斜。 |
| `letterSpacing` | `Dimension` | `0` | 字与字之间额外增加的距离；`em`相对于文字字号。阿拉伯文从不加字距。 |
| `writingMode` | `'auto' \| 'horizontal' \| 'vertical'` | `'auto'` | `'auto'`让日文和繁体中文以及任何竖排的文档竖排成列嵌字，其他一律横排。台词行的`vertical`或`horizontal`标记可以让那一行另行排列（见[漫画 › 嵌字](https://postext.dev/zh/docs/comics.md#嵌字)）。 |
| `textTransform` | `'none' \| 'uppercase'` | `'none'` | 全部大写，这是美式和欧式嵌字的传统样式。没有大小写之分的文字保持原样。 |
| `dropFinalStop` | `'auto' \| boolean` | `'auto'` | 省略对白框末尾的句号（日本漫画中的`。`）。`'auto'`：只用于日文和中文。 |
| `doubleDash` | `boolean` | `false` | 把破折号写成`--`，这是美式嵌字的习惯。 |
| `inset` | `Dimension` | `1.5mm` | 对白框与所在分格边框之间保留的距离。紧贴边框的旁白框不受它限制。 |
| `joinSameSpeaker` | `'butt' \| 'connector' \| 'none'` | `'butt'` | 同一说话人连续的两个对白框：框体合成一条轮廓，用一段细颈相连，或者保持分开。台词行可以用`join`或`join=false`单独指定。 |
| `maxColumnChars` | `number` | `8` | 竖排嵌字时，对白框中一列最多的字数。拟声词五个字后换列。 |

### 对白框样式

`comics.balloonStyles`的每个条目叠加在id相同的内置样式（`speech`、`thought`、`whisper`、`shout`、`radio`、`caption`、`inner`、`note`、`sfx`）之上；id是新的时，叠加在`speech`之上。下表的默认值是`speech`的；每种内置样式改变了哪些值，见[漫画一页](https://postext.dev/zh/docs/comics.md#对话框样式)。以`em`为单位的长度相对于对白框文字的字号。

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `id` | `string` | 必填 | 台词行用来指定这个样式的词：`ben{whisper}: …`或`style=whisper`。 |
| `name` | `string` | `id` | 便于阅读的名称，只用于编辑器界面。 |
| `shape` | `'oval' \| 'rounded' \| 'rectangle' \| 'cloud' \| 'burst' \| 'wavy' \| 'electric' \| 'none'` | `'oval'` | 围绕文字的轮廓。`'none'`把文字直接排在画面上。 |
| `fill` | `ColorValue` | 白色 | 对白框的填充色。 |
| `stroke` | `ColorValue` | 黑色 | 轮廓颜色。 |
| `strokeWidth` | `Dimension` | `0.6pt` | 轮廓粗细。 |
| `dash` | `boolean` | `false` | 虚线轮廓（耳语）。 |
| `double` | `boolean` | `false` | 双线轮廓。 |
| `wobble` | `number` | `0` | 轮廓像手绘线一样抖动的程度，0到1，以对白框为种子生成，所以每次排版都不变。 |
| `roundness` | `number` | `2.2` | 椭圆所用超椭圆的指数：2是椭圆，数值越大越方。 |
| `burstPoints` | `number` | `14` | 爆炸形的尖刺数；`0`表示按周长计算。 |
| `burstDepth` | `number` | `0.22` | 爆炸形尖刺的深度，以框体半径的比例表示。 |
| `padding` | `Dimension` | `0.55em` | 文字与轮廓之间的空白。 |
| `aspect` | `number` | `1.6` | 断行时为文字块追求的宽高比（横排嵌字）。 |
| `tail` | `'curved' \| 'wedge' \| 'bubbles' \| 'zigzag' \| 'none'` | `'curved'` | 尾巴。 |
| `tailWidth` | `Dimension` | `0.9em` | 尾巴从轮廓伸出处的宽度。 |
| `tailReach` | `number` | `0.55` | 尾巴伸向说话人的长度，以从轮廓到嘴的距离的比例表示。 |
| `target` | `'mouth' \| 'head'` | `'mouth'` | 尾巴指向什么：锚点的嘴，或者它的头（心声）。 |
| `position` | `'auto' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end' \| 'top' \| 'bottom'` | `'auto'` | 台词行没有固定位置时对白框放在哪里：由嵌字安排，或者放在分格的某个角或某条边上。 |
| `butt` | `boolean` | `false` | 把放在角上或边上的对白框紧贴分格边框（旁白框）。 |
| `fontFamily` | `string` | 嵌字字体 | 这个样式的字体。`sfx`默认使用该语言的拟声词字体：`Bangers`，日文为`Dela Gothic One`，简体中文为`ZCOOL KuaiLe`，繁体中文为`LXGW WenKai TC`，阿拉伯文为`Lalezar`（`defaultComicSfxFont(locale)`）。 |
| `fontScale` | `number` | `1` | 文字字号，以嵌字字号的倍数表示。 |
| `bold`、`italic` | `boolean` | 同嵌字设置 | 粗体或斜体文字。 |
| `color` | `ColorValue` | 同嵌字设置 | 文字颜色。 |
| `textTransform` | `'none' \| 'uppercase'` | 同嵌字设置 | 这个样式全部大写。 |
| `letterSpacing` | `Dimension` | 同嵌字设置 | 字与字之间额外增加的距离。 |
| `align` | `'center' \| 'start'` | `'center'` | 对白框内文字行的对齐方式。 |
| `halo` | `Dimension` | 无 | 围绕字形画出的描边及其宽度，让文字压在画面上也能看清（拟声词）。 |
| `haloColor` | `ColorValue` | 白色 | 描边的颜色。 |
| `rotate` | `number` | `0` | 按顺时针旋转的角度。台词行的`rotate`属性优先。 |

### 角色表

`comics.cast`的每个条目描述一个角色：

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `id` | `string` | 必填 | 脚本和画面锚点所用的说话人键。 |
| `name` | `string` | `id` | HTML输出和流式EPUB在该角色的台词前印出的名字，编辑器也显示它。 |
| `balloonStyle` | `string` | `speech` | 该角色未指定样式的台词所用的样式。 |
| `color` | `ColorValue` | 同样式设置 | 该角色对白框的文字颜色。 |
| `fill` | `ColorValue` | 同样式设置 | 该角色对白框的填充色。 |
| `fontFamily` | `string` | 同样式设置 | 该角色对白框的字体。 |

台词行自己的`color`和`font`优先于角色表，角色表又优先于对白框样式。每个漫画颜色都可以是调色板条目，像其他链接的颜色一样跟随调色板变化。

```ts
const resolved = resolveComicsConfig(config.comics, 'ja');
// => 每个字段都已填好；字体为Zen Antique和Dela Gothic One

const minimal = stripComicsDefaults(config.comics, 'ja');
// => 全部是默认值时为undefined

const shout = pickBalloonStyle(resolved, 'shout'); // 内置的shout，加上本书的修改
const night = pickPanelStyle(resolved, 'night');   // 命名分格样式，没有时为默认分格
```