# テンプレートページ：ラベル付きの図

> 画像の上に文字を置く図：リソースのアンカーに置くラベル、図ごとの代替テキスト・キャプション・注記、ラベルの組み方、引き出し線で結ぶ離れたラベル、凡例とインラインの記号、ラベルの警告

- HTML版: https://postext.dev/ja/docs/composed-pages-figures
- 最終更新: 2026-10-20
- 読了時間: 8分
- 他の言語: [en](https://postext.dev/en/docs/composed-pages-figures.md), [es](https://postext.dev/es/docs/composed-pages-figures.md), [ca](https://postext.dev/ca/docs/composed-pages-figures.md), [de](https://postext.dev/de/docs/composed-pages-figures.md), [fr](https://postext.dev/fr/docs/composed-pages-figures.md), [it](https://postext.dev/it/docs/composed-pages-figures.md), [pt](https://postext.dev/pt/docs/composed-pages-figures.md), [zh](https://postext.dev/zh/docs/composed-pages-figures.md), [ar](https://postext.dev/ar/docs/composed-pages-figures.md)

## かんたんな説明

本の地図や図解には、海や町の名前、機械の部品名など、文字が載っていることがよくあります。Postextはこうした文字を画像の上にテキストとして組むので、言語ごとに別の文字を持てます。このページでは、Markdownでの書き方、ひとつひとつのラベルの置き方と描き方、名前を指す場所から離して線で結ぶ方法を説明します。記号を使った凡例や、収まらないラベルや重なるラベルの警告も扱います。

このページでは、テンプレートページや本文の図のうち、画像の上に文字を置くものを扱います。テンプレートページの書き方は[テンプレートページ](https://postext.dev/ja/docs/composed-pages.md)に、ラベルスタイルとアンカーのラベル用フィールドは[設定 › テンプレートページ](https://postext.dev/ja/docs/configuration-composed-pages.md#ラベルスタイル)にあります。

## ラベル付きの図

```md
:::figure{resource="mapa-europa" slot="mapa"}
::label[OCÉANO ATLÁNTICO]{at="atlantico" style="mar"}
::label[**Madrid**]{at="madrid"}
::label[Mar Negro]{at="62% 48%"}
:::
```

`:::figure{resource="…"}`は、`::resource`と同じく1つのリソースをキャプションと番号付きで置き、画像の上に置くラベルを並べます。ラベル1つにつき`::label[テキスト]{…}`を1行書き、間に空行をはさんでもかまいません。

- `at`は、リソースのアンカー（画像の上に一度だけ定義し、すべての言語で共有する点）を指定します。アンカーのないラベルには、画像に対するパーセントで点を`at="x% y%"`と指定します。
- `style`はラベルスタイルを指定し、アンカーのスタイルより優先します。
- `leader`はラベルからアンカーの点まで線を引き、`leader="none"`はその線を外します（[引き出し線、凡例、記号](https://postext.dev/ja/docs/composed-pages-figures.md#引き出し線凡例記号)を参照）。
- 角括弧の中のテキストはインラインのMarkdownで、太字、イタリック、チップ、`:icon`で書く記号が使えます。

図は、枠の中だけでなく本文の流れの中でも使えます。図のラベルは文字として画像の上に描かれ、図がどこに置かれてもいっしょに移ります。段、フロート、再配置の手順（内容を収めるための処理）で回転や縮小をした枠、見開きのどれでも同じです。図を閉じる`:::`が欠けていると、ラベルでも空行でもない最初の行で図は終わり、閉じていないコンテナーとして報告されます。

### 図に固有の文言

リソースに入っているのは1枚の画像、そのアンカー、1組の文言だけですが、本の版ごとに文言は違います。そこで図は`alt`、`caption`、`note`を自分で指定できます。開始行の属性としても、専用の行としても書け、そのファイルのページではリソースの文言に代わって使われます。

```md
:::figure{resource="relieve" alt="Mapa de relieve de Varenia"}
::caption[Relieve de **Varenia**, con sus tres cordilleras]
::note[Fuente: levantamiento de 1932]
::label[Mar de Sal]{at="mar"}
:::
```

- 開始行の属性としては、`alt`、`caption`、`note`に引用符で短い文字列を渡します。`::alt[…]`、`::caption[…]`、`::note[…]`の行は角括弧の中の文字列を取り、リソースのキャプションや注記と同じくインラインのMarkdownと、改行の`\\`が使えます。同じ名前の属性より行が優先されます。行はラベルの間に置け、空行をはさんでもかまいません。
- 図が指定しない項目は、リソースのままです。空文字列は「何も書かない」の意味で、`caption=""`はキャプションを外し、`alt=""`は画像を装飾として扱います。
- 文言は、それを書いた章の中でリソースのものに代わります。レイアウトも、各出力の代替テキストも、タグ付きPDFも、この文言を使います。リソース自体は変わりません。1つの章の中では、リソースの文言は1組だけで、最初の図のものが使われます。同じリソースを使う後の図が別の文言を書いても表示されず、`figureWordsShared`で知らされます。専用のキャプションが必要な縮小版には、同じ画像ファイルを指す2つ目のリソースを使ってください。ラベルと違い、キャプションはMarkdownと1文字ずつ対応づけられてはいません。`sourceAt`は、リソースのキャプションと同じように、クリックした位置のソースを返します。

### ラベルの組み方

- **位置**：ラベルはアンカーの点に置かれます。点は画像全体に対する割合で表すので、画像がセーフエリアに合わせてトリミングされても、小さく組まれても、ラベルは画像といっしょに動きます。アンカーの`align`はラベルのどの側を点に合わせるか、`verticalAlign`はどの辺を点の高さに合わせるかを決めます。`start`と`end`はラベル自身の書字方向に従い、アラビア語のラベルでは`start`が右端です。`rotate`は点を中心にラベルを時計回りに任意の角度で回します。川の流れに沿った川名や、斜めに並ぶ山地名などに使います。
- **見た目**：ラベル自身の`style`、なければアンカーの`style`がラベルスタイルを指定します（「設定：テンプレートページ」を参照）。スタイルがなければ本文の書体設定を使います。縁取りは文字の塗りの下に輪郭を描き、下地（`background`）は文字のまわりの矩形を塗ります。下地は`padding`の分だけ広がります。
- **収め方**：アンカーに`width`があると、ラベルはその幅の中で語と語の間で折り返し、語の途中では切りません。ある語が幅より広いときは、ラベル全体をスタイルの`minScale`まで小さく組みます。それでも収まらないラベルは、いちばん広い語を切って描きます。`width`がなければラベルは1行のままで、キャプションと同じく`\\`で改行した所だけ折り返します。
- **テキスト**：角括弧の中はインラインのMarkdownで、キャプションと同じように組まれます。太字、イタリック、チップ、ハイライト、相互参照、インライン数式が使えます。複数の語からなる名前は、言語ごとに語順が違っても1つのラベルです。`::label[大西洋]`と`::label[ATLANTIC OCEAN]`は同じアンカーに置かれます。右から左へ書く言語のラベルは右から左へ組まれ、中国語と日本語のラベルは文字の間で折り返します。
- **出力**：キャンバス、PDF、HTMLビューアー、固定レイアウトのEPUB、Folioがラベルを描きます。右から左のページでも、ラベルは画像が示す位置にとどまります。
- **縦組み**：アンカー（またはそのラベルスタイル）に`writingMode: 'vertical-rl'`を指定すると、ラベルは縦組みのページと同じように組まれます。文字は正立のまま1文字ずつ上から下へ並び、列は右から左へ進みます。欧文の単語と長い数字は横倒しに、短い数字は1マスに収まります。このとき`width`は画像の高さに対する割合、つまり1列の長さで、中国語や日本語のラベルはさらに列を増やして折り返します。`align`は列に沿った向き（`start`が列の上端）、`verticalAlign`は列をまたぐ向き（`top`が最初の列、つまり右端の列）で、`rotate`はラベルをさらに回します。右から左へ綴じる本の鏡像ページでも、ラベルは同じく列を上から下へ、文字を正立のまま、画像の同じ位置で読めます（postext 1.40以降）。
- **検査**：ラベルスタイルの`minScale`まで縮めても幅に収まらないラベルには`labelOverflow`、行がぶつかる2つのラベルでは後のほうに`labelOverlap`が出ます。どちらも版ごとに調べるので、語の長い訳文では、どこに余裕が必要かがわかります。部（`:::part{palette="…"}`）のパレットは、キャプションと同じようにそのページのラベルの色を置き換えます。コントラストの検査は、ラベルを下地の上で、なければ縁取りの上で測ります。画像の上に直接置いたラベルは、背景が画像なので対象外です。印刷のプリフライトは、ラベルの小さな文字が複数のインキで刷られていないか、インキの量、仕上がり線までの距離も調べます。
- **見開きで。** 見開きののどをまたぐ図（`crossGutter: true`の枠）は、それぞれのページに自分の側の半分を描きます。そのため、ラベルの矩形がのどの帯に入ると、折り目で切れてどちらのページでも読めなくなります。そこでラベルは、アンカーの点がある側へ、帯の端まで横にずれ、高さは変わりません。のどの真上にある点は、枠と同じく最初のページに属します。`gutter: 'cross'`のアンカーはその場に残ります。両ページにまたがる見出しに使います。紙面の外側の縁には手を加えません。仕上がり線を越えたラベルは、画像と同じように切れます。postext 1.43以降。

### 引き出し線、凡例、記号

postext 1.48からは、ラベルを名前の指す場所から離して置けます。ラベルを地図の凡例にすることも、ラベル、キャプション、表のセルに記号を入れることもできます。

**引き出し線**：アンカーの`labelAt`はラベルを点から離れた位置に置き（海の上の名前、図解の余白の注記）、引き出し線がラベルから点まで線を引きます。線の見た目はラベルスタイルの`leader`で決まり（[設定 › ラベルスタイル](https://postext.dev/ja/docs/configuration-composed-pages.md#ラベルスタイル)を参照）、Markdownでは1つのラベルごとに線を付けるか外すかだけを書きます。

```md
:::figure{resource="relieve" slot="mapa"}
::label[Sierra Alta]{at="peaks" leader}
::label[Lago Verde]{at="lake" leader="none"}
:::
```

`leader`に`none`、`false`、`off`以外の値を指定すると線が付きます。属性がなければアンカーの`leader`で決まり、どちらもなければ、点から離して置いたラベルは、スタイルに`leader`があるときに線が付きます。枠の注記から画像の一点を指すこともできます。端に画像のアンカーを指定した[コネクター](https://postext.dev/ja/docs/configuration-composed-pages.md#コネクター)（`anchor: 'lake'`）を使います。

**複数行のラベル**：`:::figure`の中の`:::label{at="…" style="…"}` … `:::`は、ラベルを1行ずつ書きます。ソースの空でない行がそれぞれラベルの1行になるので、凡例や住所の各行の末尾に`\\`を書く必要はありません。最初の`:::`がラベルを閉じ、次の`:::`が図を閉じます。`::label[…]`はこれまでどおり1行のラベルで、`\\`を書いた所だけで改行します。

**凡例**：`kind: 'legend'`のスタイルのラベルは地図の凡例です。各行が1つの項目になり、項目の先頭の記号は、いちばん幅の広い記号に合わせた列に並ぶので、項目の言葉は同じ位置から始まります。各行には記号を先に書きます。

```md
:::figure{resource="mapa-politico" slot="mapa"}
:::label{at="key" style="key"}
:icon[国]{glyph="■" color="country"} 国
:icon[首都]{glyph="⊙" font="Noto Sans Math"} 首都
:icon[町]{resource="town-mark" size="0.55"} 町
:icon[国境]{line="dashed" color="border"} 国境
:::
::label[:icon[首都]{glyph="⊙" font="Noto Sans Math"} Varena]{at="capital"}
:::
```

**記号**：`:icon[代替テキスト]{…}`は、行の中にベースラインに載せて小さな記号を置きます。

| 属性 | 働き |
| --- | --- |
| `resource="…"` | ビットマップまたはSVGのリソースです。縦横比を保ちます。 |
| `glyph="…"` | 1つの文字です。本文の書体か、`font="…"`で指定した書体で組みます。 |
| `line="solid\|dashed\|dotted"` | 高さの2倍の長さを持つ線の見本です。凡例の国境や道路に使います。 |
| `color="…"` | 16進の色かパレットの項目で、文字、線、画像の色合いを決めます。 |
| `size="…"` | 記号の高さで、本文のem単位です。既定は`0.75`で、大文字の高さです。 |

`resource`、`glyph`、`line`のうち最初に書いたものが記号の種類を決めます。どれもなければ、ディレクティブはテキストのままです。角括弧の中のテキストは記号の代替テキストで、スクリーンリーダー、タグ付きPDF、画像の代替テキストは記号の代わりにこれを読みます。角括弧が空の記号は装飾として扱います。記号が読まれるのは、図のラベルと、リソースのすべての文言（キャプション、注記、表のセル）です。このリリースでは、本文、見出し、デザイン用のテキストでは読まれません。

### labelAnchorUnknown

`::label`の`at`が、図のリソースにないアンカーを指しています。このラベルは描かれません。リフロー型EPUBでは引き続き一覧に出て、画像の代替テキストにも含まれます。警告には、リソース、アンカー、リソースにあるアンカー（`known`）、言語、ページ、ラベルの文字のソース範囲が入ります。アンカーのidを直すか、リソースにアンカーを追加するか、`at="x% y%"`で位置を指定してください。

Sandboxの検査パネルでは、この警告から本文パネルのラベルへ移動できます。ピンのボタンを押すと、画像のアンカーの画面が、この名前のアンカーを置く準備ができた状態で開き、画像を1回クリックするとアンカーが追加されます。

### anchorUnlabelled

図のリソースのアンカーにラベルスタイルが設定されているのに、この言語では図のどの`::label`もそこに置かれていません。地図には語を置く場所があるのに、この版ではその語が抜けています。これは情報としての指摘で、`postext check`は`info`として出します。スタイルのないアンカー（漫画の話者のものなど）は報告されません。警告には、リソース、アンカー、そのスタイル、言語、ページ、図のソース範囲が入ります。この言語のMarkdownにラベルを書くか、アンカーのスタイルを外してください。

検査パネルでは、この警告から本文パネルの図へ移動できます。ピンのボタンを押すと、画像のアンカーの画面が、このアンカーを選んだ状態で開きます。

### labelOverflow

ラベルが、ラベルスタイルの許す最小の倍率（`minScale`）に縮めてもアンカーの`width`より広いままです。ラベルはその倍率で描かれ、幅からはみ出します。警告には、リソース、ラベルの文字、アンカー（パーセントで置いたラベルにはありません）、指定された幅、到達した倍率、言語、ページ、ラベルの文字のソース範囲が付きます。版ごとに調べるので、語の長い言語では、別の言語ではあふれない場所であふれます。アンカーの`width`を広げるか、この版のMarkdownでその語を短くするか、ラベルスタイルの`minScale`を下げてください。中国語や日本語のラベルは文字の間で折り返すので、この形ではあふれません。postext 1.39以降。

### labelOverlap

同じ図の2つのラベルの行がぶつかっています。下地のあるラベルは、下地の範囲で判定します。警告は、書かれた順で後のほうのラベルに付き、ぶつかった前のラベルのうち最初のものの文字と、ぶつかった前のラベルの数が添えられます。判定にはラベルといっしょに回転した行ごとの矩形を使うので、短い行の横の空いた部分はぶつかりに数えません。2つの行が行の高さの8分の1までかぶっても、ぶつかりとは見なしません。版ごとに調べます。アンカーの一方を動かすか、ラベルの`width`を狭めて折り返させるか、この版のMarkdownで語を短くしてください。Sandboxの検査パネルでは、ピンのボタンで画像のアンカーの画面が開き、そのラベルのアンカーが選ばれます。postext 1.39以降。アンカーまたはそのラベルスタイルに`overlap: 'allow'`を書くと、元の印刷物で隣のラベルに接して刷られているラベル（点の多い地図など）は検査から外れ、それを含む組は報告されません（postext 1.42以降）。画像の`avoid`領域は、地図の記号として扱われます。画像のマークの**回避エリア**モードで、点やアイコンの上に、画像に対する割合で矩形を描きます。ラベルがその1つにかかると同じように報告され、相手のラベルの代わりに`symbol 2`と示されます（データでは`withSymbol`）。`overlap: 'allow'`にすると、そのラベルは両方の検査から外れます（postext 1.42以降）。

### figureWordsShared

ある`:::figure`が、同じ章の前の図がすでに文言を指定したリソースに、異なる文言（`alt`、`caption`、`note`）を指定しています。ページには最初の図の文言が表示され、こちらは省かれます。警告には、リソース、省かれた文言、そのうち最初のもののソース範囲が入ります。後の図が独自の文言を書いていなければ問題ありません。この図には専用のリソースを割り当ててください。同じ画像ファイルを指す2つ目のリソースを作り、専用のキャプション、番号、アンカーを付けます。Sandboxの検査パネルでは「図」に分類されます。postext 1.42以降。