# 文書形式：画像、表、動画 > 本文の中のリソース：参照と埋め込み、番号付け、配置とフロートが置かれる場所、回り込み、ビットマップのサイズ、セーフエリア、漫画のアンカー、動画 - HTML版: https://postext.dev/ja/docs/document-format-resources - 最終更新: 2026-10-16 - 読了時間: 40分 - 他の言語: [en](https://postext.dev/en/docs/document-format-resources.md), [es](https://postext.dev/es/docs/document-format-resources.md), [ca](https://postext.dev/ca/docs/document-format-resources.md), [de](https://postext.dev/de/docs/document-format-resources.md), [fr](https://postext.dev/fr/docs/document-format-resources.md), [it](https://postext.dev/it/docs/document-format-resources.md), [pt](https://postext.dev/pt/docs/document-format-resources.md), [zh](https://postext.dev/zh/docs/document-format-resources.md), [ar](https://postext.dev/ar/docs/document-format-resources.md) ## かんたんな説明 このページでは、本の画像、表、動画を説明します。一度追加して本文で触れれば、Postextはそれぞれを最初に触れた場所の近くに置きます。置く場所は、ページの上、すべての段にまたがる幅、書いたその場所などから選べます。画像のまわりに文章を回り込ませることもできます。画像を切り詰めて収めるとき、いつも見えていなければならない部分を指定できます。動画はWeb表示と電子書籍で再生され、印刷では1枚の絵になります。 ## リソース 画像、SVG、表、動画は本文中には書きません。これらは**リソース**として一度だけ宣言し（Sandboxの[**リソース**パネル](https://postext.dev/ja/docs/sandbox.md#リソースパネル)で管理します。このパネルでは、画像とSVGのアップロード、対話式の表エディター、YouTube・Vimeo・アップロードした動画、キャプションと配置の編集を扱います）、IDで本文と結び付けます。**リソースは参照するだけで組み込まれます**。インラインの`:ref{id="…"}`で一度言及すれば、エンジンが図や表をその参照の後にある最初の空き位置へフロートとして配置します。言及した段の下端、次の段の上端、次のページの帯など、印刷の組版者と同じやり方です。2度目に配置する必要はありません。 以下の2つの形式はどちらもCommonMarkと衝突しない新しい構文なので、これらを使った文書もほかのMarkdownビューアーではプレーンテキストとして読めます。 ### インライン参照（基本の形） 本文中からリソースを参照するには`:ref{id="…"}`を使います。最初の参照はリソースを**組み込み**（ページ上に配置されるようにし）、同時に算出された番号を表示します。番号の前には、既定で種類の短いラベルが付きます。 ```md As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery. ``` 表示は「*As shown in Fig. 1.7, the lantern room sits above the gallery.*」となります。図そのものはその文の後にある最も近い空き位置（この段の下端、次の段の上端、または次のページの帯）へフロートとして配置され、この文とそれに続くテキストは途切れずに流れます。 参照の位置で本文が途切れることはありません。リソースが置かれる場所（最初の空き位置か、上端または下端の位置だけか、1段の中か全幅にわたるか）は、その**配置**（後述の[配置](https://postext.dev/ja/docs/document-format-resources.md#配置)を参照）と、言及した場所によって決まります。探索は参照の直後から始まります。 ### ブロック埋め込み（任意、本文中への明示的な配置） リソースをフロートさせず、流れの中の決まった位置に置きたい場合もあります。フロートをやめるには、リソースに`placement.position: "here"`を指定し、`::resource{id="…"}`を単独の行に書いて埋め込みます。 ```md Here is the floor plan we discussed. ::resource{id="lighthouse-diagram"} The keeper's quarters occupy the eastern wing. ``` フロートするリソースには`::resource`ディレクティブは不要です。`:ref`がすでに配置しており、同じIDに対する余分な`::resource`は2つ目の複製ではなく、もう1つの参照として扱われます。`::resource`がリソースを本文中に描画するのは、解決された配置が`"here"`の場合だけです。インラインのリソースは、フロートと同じく上に1行分のアキ（フロートのアキ）を取ります。ただし、直前のブロックがそれより大きなアキを求める場合はそちらに従います。本文中では下にも同じアキを取り、その後のテキストはベースライングリッドに戻ります。このとき、さらに最大1行分のアキが加わることがあります。直後に見出し、リスト、囲み、または別のインラインのリソースが続く場合、そのアキは後続の要素自身の上のアキと共有され、両方ではなく大きいほうが適用されます。（postext 1.4までは、下のアキはグリッドへのスナップで残る分だけで、0から1行まで幅がありました。`layout.inlineResourceGap: 'above'`でその規則を保てます。1.5より前に保存された本はこの設定で読み込まれます。）囲み（`:::callout`）の中でもリソースは同じアキを保ち、上には囲み自体のテキストの1行分、`'around'`の場合は下にも同じだけ取ります。囲みの上端または下端では、代わりにパディングがリソースを離します。（postext 1.4までは、リソースは囲みのテキストに密着していました。`layout.inlineResourceGapInBoxes: false`でその動作を保てます。リソースを埋め込んだ囲みを含む、1.5より前に保存された本はこの設定で読み込まれます。） 段が複数ある版面では、配置にさらに`span: 'page'`を指定したインラインのリソース（`placement: { position: 'here', span: 'page' }`）は、ページ幅の囲みと同じく、ディレクティブの位置でページ幅いっぱいに組まれます。上の段は高さをそろえて閉じ（段の均等化を行い、そろえられない場合はリソースが次ページの頭へ送られます）、リソースは版面の幅いっぱいに上下に同じアキを取って組まれ、本文はその下のすべての段で続きます。1段のページでは、これまでどおり段幅いっぱいに組まれます。`columns`を指定した`span: 'column'`のリソースは、インラインで埋め込むと自分の段にとどまります。段数はフロートにだけ効きます。postext 1.19から。 `id`は**リソース**パネルで定義したリソースと一致している必要があります。エンジンはリソース（ビットマップ、SVG、表）を描画し、その下に図や表の脚書きとしてキャプションを組みます。キャプションのテキストは、リソースの種類の`captionPrefix`、算出された番号、リソース自身のキャプションから組み立てられます。たとえば「**Figure 1.7. The original lighthouse plan.**」のようになります。キャプションの文字組みは[設定 › キャプションスタイル](https://postext.dev/ja/docs/configuration-resources.md#キャプションスタイル)で決まります。ラベルと説明文は書体とサイズを共有し、ラベルだけは太字・イタリック・色を個別に設定できます。キャプションの上のアキの既定値は`0.75em`、そろえの既定値は左です。キャプションはリソースの上に置くこともでき（`captionStyle.position: 'above'`。全体またはリソースの種類ごとに指定）、色付きの帯の上に組むこともできます。リソースには`note`（注記）を付けることもできます。出典やクレジットを示す短い行で、キャプションと同じインラインの書式と`:ref`の記号が使えます。注記はリソースの下に小さめの文字で組まれ（キャプションが下にあるときはキャプションの下、上にあるときは本体の下）、スタイルは`captionStyle.note`で設定します。 **キャプションと注記の改行**。キャプションや注記はそれぞれ、その位置の行長で組まれる1つの段落で、中で入力した改行はスペースになります。新しい行を始めるには、タイトルで使う強制改行の`\\`を書くか、Markdownのハード改行として行末をバックスラッシュで終えます。`¹ Measured at 20 °C. \\ ² Mean of three runs.`と書けば、幅の広い表の脚注がそれぞれ1行に組まれます。改行の前の行は自然な幅のままで、行長いっぱいに伸ばされることはありません。改行を2つ続けても空行はできません（間にノーブレークスペースを入れると空行になります）。表のセルの中では、`\\`は改行と同じく新しい段落を始めます。その次の行の字下げは保たれるので、先頭の2つのスペースでリスト項目を入れ子にできます。本文中では2つのバックスラッシュは常に改行になり、エスケープの方法はありません。そのまま印字するには、バックスラッシュが書いたとおりに印字されるインラインコードの中に入れます。リンク先の中ではURLの一部、ディレクティブの属性（`:ref`の`text`）の中では値の一部のままです。1行に組まれるチップの中では、改行はスペースになります。（postext 1.4までは、バックスラッシュがそのまま印字され、キャプションや注記は行長が尽きたところでしか改行されませんでした。） 表のリソースは独自の罫線を描画し、そのスタイルは[設定 › 表スタイル](https://postext.dev/ja/docs/configuration-resources.md#表スタイル)で設定します。本文セルとヘッダーセルの文字組みは完全に独立しています。ヘッダーの背景の既定値は`#f0f0f0`、罫線は`0.75pt`、`cellPadding`は`0.375em`で、未設定の項目は本文テキストから継承されます。列幅は表そのものに含まれます。`TableModel.columnWidths`は列ごとに1つの相対的な比率を持ち（`[2, 1, 1]`なら第1列が幅の半分を占めます）、未設定なら列は幅を均等に分けます。表は名前付きのバリエーションで組むこともできます。`table.styleId`は文書の`tableStyles`の1つを選び（[設定 › 名前付きの表スタイル](https://postext.dev/ja/docs/configuration-resources.md#名前付きの表スタイル)を参照）、その未設定の項目は`tableStyle`を継承します。不明なIDやIDがない場合は`tableStyle`のままです。 セルの内容の置き方は、`TableCell.align`（`left`、`center`、`right`。リスト項目は左そろえのまま）と`TableCell.verticalAlign`（既定値の`top`、`middle`、`bottom`）で決めます。縦方向のそろえは、内容より背の高いセル、つまり隣の長いセルに引き伸ばされた行や、`rowSpan`がまたがる行の中で、セルの内容全体（画像とその下のテキストを1つのまとまりとして）を動かします。これはすべての出力（canvas、HTML、PDF）、回転した表、ページをまたいで分割された表の各部分に適用されます。どちらもSandboxの表エディターのツールバーにあるそろえのボタンでセルごとに設定します。 表のセルには画像を入れることもできます。`TableCell.image`はビットマップまたはSVGのリソースをIDで指定します（`{ "resourceId": "fig-arm", "width": 0.7 }`）。画像はセルの中に描画され（番号、フロート、キャプションは付きません）、縦横比を保ったままセルの内側の幅（または`width`で指定したその割合。既定値は`1`）に合わせられ、セルのテキストと同じようにそろえられます。セルのテキストはその下に続きます。行は画像が収まるように高くなります。Sandboxの表エディターでは、ツールバーの画像ボタンで選択中のセルのリソースを選び、幅の欄で割合を設定します。どの画像リソースとも一致しないIDの場合、セルはテキストだけになります。 セルには独自の塗りを持たせることもできます。`TableCell.background`は色の値（`{ "hex": "#c1dfd6", "model": "hex" }`。`paletteId`で文書のパレットの項目にリンクすることもできます）で、スタイルのヘッダーや本文の背景の代わりに塗られます。互換性の一覧表では、この方法でセルを緑、赤、黄色に塗り分けます。Sandboxの表エディターでは、ツールバーの塗りのコントロールで設定します。こうした塗りの凡例のために、キャプション、注記、あらゆるテキストブロックでインラインの**カラースウォッチ**が使えます。`:swatch{color="#c1dfd6"}`（hex値、またはパレット項目のID。`:swatch{color="table-compatible"}`）は、ベースライン上にフォントサイズの4分の3の小さな正方形を置き、その色で塗ってテキストの色で輪郭を描きます。これで注記を`:swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible`のように書けます。何にも解決されない色の場合は、空の輪郭だけが描かれます。hex値にはアルファチャンネル（`#rrggbbaa`、`#rgba`）も使え、`rgb()` / `rgba()`の色も使えるので、半透明のセルの塗りには半透明の凡例を合わせられます（[設定 › 透明度](https://postext.dev/ja/docs/configuration-fonts-colors-viewers.md#透明度)を参照）。 SVGのリソースは、さらに`diagramStyle.singleInk`（既定値は`false`）で、1色の特色印刷向けに色を変えられます。有効にすると、SVGのダイアグラムのすべての色が、輝度に応じた`diagramStyle.inkColor`（既定値はパレットのメインカラー`#295AA3`）の濃淡に置き換えられます。白は紙の色に、黒はインキのベタになるので、文書を1色の特色で印刷しても図が忠実に再現されます。[設定 › ダイアグラムスタイル](https://postext.dev/ja/docs/configuration-resources.md#ダイアグラムスタイル)を参照してください。 不正な埋め込み（`id`がない、または空、`id`が引用符で囲まれていないか一重引用符で囲まれている、余分な属性がある）はリソースのブロックとして扱われず、通常の段落として解析されて出力にそのまま表示されます。正しい形式の埋め込み行でも、段落の行の直下に空行なしで続けて書くと同じで、その段落の一部として読まれます。どちらも`malformedEmbed`警告となり、Sandboxの**検査**パネルに**テキストとして組まれた埋め込み**の項目として表示されます。 インライン参照は、段落、見出し、引用ブロック、リスト項目など、あらゆるテキストブロックの中で認識され、太字、イタリック、インラインコード、インライン数式と並べて使えます。 #### 参照のオプション `:ref`ディレクティブは3つの省略可能な属性を任意の順序で受け付けます。`style`は算出されたラベルの表示方法を選びます。`style="number"`は番号だけ（`1.7`）、`style="full"`は種類の正式名と番号（`Figure 1.7`）を表示し、`style`が未設定のときは種類の`shortLabel`と番号（`Fig. 1.7`）を使います。`case`はラベル部分の大文字・小文字だけを変え（`lower`、`upper`、`capitalize`）、番号には触れません。`text`は書いたとおりに使われる上書きで、算出されたラベルを置き換え、`style`と`case`の両方より優先されます。表示のオプションを並べると次のとおりです。 | 構文 | 表示 | 備考 | | --- | --- | --- | | `:ref{id="…"}` | `Fig. 1.7` | 既定のスタイル：種類の`shortLabel`に続けて番号を表示します。両者はノーブレークスペースでつながれ、別々の行に分かれることはありません。 | | `:ref{id="…" style="number"}` | `1.7` | 算出された番号だけで、ラベルは付きません。 | | `:ref{id="…" style="full"}` | `Figure 1.7` | 種類の正式な`name`に続けて番号を表示します。文頭や、略記では読みにくい箇所で使います。 | | `:ref{id="…" case="lower"}` | `fig. 1.7` | ラベルだけの大文字・小文字を変えます：`lower`（`fig. 1.7`）、`upper`（`FIG. 1.7`）、`capitalize`（先頭の文字を大文字に）。`style="full"`と組み合わせられます（`figure 1.7`）。番号は変わらず、認識されない値は無視されます。 | | `:ref{id="…" text="see the plan"}` | `see the plan` | 明示的な上書きです。算出されたラベルの代わりに、指定したテキストがそのまま使われます。「先に見たように」のような本文中のリンクに便利です。指定した場合、`text`は`style`と`case`より優先されます。 | `:ref`（または`::resource`）が一致するリソースのないIDを指定すると、ラベルは`?`になり（`text=`のラベルがある場合はそれが表示されますが、番号もリンクも付きません）、Sandboxは**不明なリソース**の警告を出します。エンジンはこれを文書の`contentWarnings`に`unknownResourceId`の項目として、参照のソース範囲とページとともに記録します。本文が使うリソースのキャプション、注記、表のセルの中にある`:ref`も同様です。 ### 初出順の番号付け リソースの番号は、**読む順序で最初に言及されたとき**に割り当てられます。最初の言及が`::resource`のブロック埋め込みでもインラインの`:ref`でも同じです。以降、同じIDへの参照はすべて同じ番号を表示します。 つまり番号は、パネルでリソースを作成した順ではなく、読者が出会う順に付きます。 - 序論で図を`:ref`で参照し、2ページ後で初めて（`::resource`で）埋め込んだ場合も、その図には序論の時点の番号が付きます。参照のほうが先だからです。 - 文書の*前のほう*に新しい参照を挿入すると、それ以降はすべて自動的に番号が振り直されます。手作業で番号を合わせる必要はありません。 番号はリソースの種類ごとに付けられ、種類ごとのリセット範囲とカウンターの書式に従います。テンプレートのトークン（`{h1}`、`{n}`）、`resetOn`、`counterFormat`については[設定 › リソースの種類](https://postext.dev/ja/docs/configuration-resources.md#リソースの種類)を参照してください。 数えられるのは本文が参照するものだけです。デザインだけが描くリソース（たとえば章扉の画像要素）には番号が付かず、カウンターも変わりません。また`{h1}`は、スタイルが`numbered: false`でないすべてのレベル1見出しを数えます。`numberingTemplate`が空の見出しも含むため、唯一のH1がタイトルである記事では、図の番号は既定で1.1、1.2…となります。[設定 › 番号が付くもの](https://postext.dev/ja/docs/configuration-resources.md#番号が付くもの)に、この2つの規則と、図1、図2…と番号を付けるための設定があります。 ### 配置 各リソースには、フロートの置き場所を決める**配置**があります。配置はリソースごとに、まずリソース自身の`placement`、次にその種類の`defaultPlacement`、最後に組み込みの既定値`auto` / `column`の順に解決されます。 | 項目 | 値 | 意味 | | --- | --- | --- | | `position` | `"auto"` · `"top"` · `"bottom"` · `"here"` | `"auto"`（既定値）は、上端・下端を問わず参照の後にある最初の空き位置を取ります。`"top"` / `"bottom"`はその種類の位置だけを受け入れます。`"here"`はフロートをやめ、`::resource`ディレクティブの位置で本文中に埋め込みます（そこに置いた表は、段の残りに収まらなければ行の間で切られます。[ページより高い表](https://postext.dev/ja/docs/configuration-resources.md#ページより高い表)を参照）。 | | `width`, `align` | `0 < width < 1`; `"left"` · `"center"` · `"right"` | 位置より幅の狭いリソースに使います。`width`は段（またはページ）の幅に対して占める割合、`align`は位置の中での置き場所です（段の中央に置く小さな表、1段分の幅の写真を載せるページ幅の帯など）。位置より幅の狭い画像（段より小さいビットマップや、`layout.fitFiguresToPage`で縮小されたもの）も`align`に従って置かれ、その下のキャプションは位置の行長を保ちます。フロートにもインラインの`::resource`埋め込みにも適用されます。 | | `captionSide` | `true` · `false` | サイド段をフロート専用にした1段半レイアウト（`layout.sideColumnRole: 'floats'`）では、`captionSide`を指定した`"column"`フロートは本体を主段に置き、キャプション（と注記）をサイド段に、図の上端（下端のフロートでは下端）の高さにそろえて組みます。サイド段はその帯を明け渡します。そのような段のないページでは、キャプションは図の下に置かれます。postext 1.28からは、本文中に置いた（`"here"`）1段幅のリソースにも適用されます。キャプションと注記は本体の上端の高さでサイド段に組まれ、本文中のブロックは本体だけの高さになり、あとから置かれるサイド段の図や囲みはこのキャプションを避けます。リソースの横でサイド段がふさがっているときは、キャプションは本体の下に置かれます。次の段やページへ送られたリソースは、そこで改めて判断します。囲みの中、縦組みのページ、文字が回り込む図版には適用されません。`layout.inlineCaptionSide: false`にすると、サイド段のキャプションは段幅のフロートだけになります。 | | `span` | `"column"` · `"page"` | 1つの段を占めるか、段の流れを断ち切ってすべての段にわたる版面の全幅を占めるかを選びます。1段組みのレイアウトでは両者は同じです。 | | `columns` | 整数、既定は`1` | 複数の段があるページで、`"column"`フロートを指定した数の隣り合う段に、段間も含めてまたがらせます。新聞の5段のうち2段にまたがる写真などです。上端のそろった空の段の並びの頭か、引用した段とその後の空の段の足に置かれます。ページの段数以上を指定すると、ページ幅のフロートになります。`"page"`と`"side"`のspan、回転したリソース、インラインの埋め込み（`"here"`）では無視され、`captionSide`は1段幅のフロートにだけ効きます。postext 1.18以降。 | | `rotate` | `"ccw"` · `"cw"` | リソースを90度回転して組みます。縦長の本に入れる横長の表などに使います。`"ccw"`は反時計回りに回転し、上端がページの左端を向きます（読者は本を時計回りに回して読みます）。これが一般的な慣習です。`"cw"`はその逆です。回転したリソースは常に、専用のページに置かれるページ幅のフロートになります。版面の高さに沿ってレイアウトされ、その長さはベースライングリッドの行単位に切り下げたうえで、本文1行分（すべてのフロートの帯が保つフロートのアキ）を差し引いたものです（14ptのグリッドで237mmの版面には47行、232.1mmが入るので、リソースはそのうち46行、227.2mmを使います）。余白を左右対称にしている場合は背の側に寄せ（それ以外は左そろえ）、1ページに収まらないほど幅の広い表は行の間で切られ、ヘッダーを繰り返しながら、回転したまま次のページ以降に続きます。これは1ページより背の高い通常の向きの表とまったく同じです。回転した図はページに収まるように縮小されます。インライン（`"here"`）の埋め込みでは無視されます。 | | `shrink`、`minScale` | `"never"` · `"page"` · `"slot"`、`0 < minScale ≤ 1`、既定は`0.7` | フロートの図版（ビットマップ、SVG、動画のポスター）を、次へ送らずに、縦横比を保ったまま置き場所の空きまで縮小します。`"never"`（既定）は元の大きさで組みます。`"page"`は、新しいページの帯より高いときだけ縮小します。帯とは、版面からそのページにすでにあるもの（扉、ほかのフロート、脚注）とフロートのアキを除いた部分で、ページに合わせて組む図録の図版などに使います。`"slot"`は、引用しているページの置き場所や、別の帯の横に残る空きにも、`minScale`以上で収まるなら縮小して入れます。収まらなければこれまでどおり次へ送ります。置き場所はいつもの順に試され、帯はやはりベースライングリッドで終わります。セーフエリアのある図版は、縮小する前にその内側でトリミングされます（[セーフエリア](https://postext.dev/ja/docs/document-format-resources.md#セーフエリア)を参照）。ほかに行き場のない新しいページでは、`minScale`でも収まらない図版はその倍率で組まれ、帯からはみ出します。縮小したフロートごとに、レイアウトは`floatShrunk`の警告を出します。表（分割されます）、フロートのボックス、コマ漫画の帯、回転したリソース、インラインの埋め込みは縮小しません。ドキュメントの既定値は`layout.floatShrink`です。postext 1.24から。 | | `captionMeasure` | `"slot"` · `"body"` | 置き場所より幅の狭い図版（縮小したもの、段より小さいビットマップ）のキャプションと注の行長です。`"slot"`（既定）は置き場所の幅を保ちます。`"body"`は図版と同じ幅にして`align`に従って図版の下に組むので、中央に置いた図版はキャプションも中央にそろいます。フロートにもインラインの埋め込みにも使えます。postext 1.24から。 | | `wrap`, `wrapGap` | `"none"` · `"left"` · `"right"` · `"start"` · `"end"`; 長さ | 本文をリソースの横に組みます。リソースは段のその側に置かれ、横の行は残りの行長で、リソースの枠（キャプションを含む）から`wrapGap`離して組まれ、その下では全幅に戻ります。対象は本文中の埋め込み（`"here"`）と、段頭または段末に置く 1 段幅のフロートです。ページ幅、複数段、サイド段、回転したフロートは帯のままです。リソースは段幅の`width`、未設定なら`layout.wrap.defaultWidth`（0.45）を占めます。`wrapGap`の既定は`layout.wrap.gap`、それもなければ本文 1 行分です。[回り込み](https://postext.dev/ja/docs/document-format-resources.md#回り込み)を参照。postext 1.24以降。 | | `citingPage` | `true` · `false`、既定値`false` | `"top"`または`"auto"`のフロートを、LaTeX の`t`配置のように、最初に参照する行のあるページ（ページ幅のフロート）または段（段幅のフロート、`columns`で複数段にまたがるものも）の先頭に置きます。その行の後の最初の空き位置ではありません。参照より前の本文はフロートの下に送られます。次の条件をすべて満たすときに限ります：フロートが段の高さの`layout.maxTopFraction`（既定値 0.7）以内に収まる、同じ番号系列の先行するフロートがすでに置かれている、明示的な改ページで始まるページ（章の最初のページ、部、`:::pagebreak`の後）ではなく、参照行より上にページ幅の要素がない、そしてそう置いたあとも参照行がそのページ（フロートが先頭を占める段）に残る。そうでなければフロートは通常の位置に置かれます。回転したフロート、サイド段のフロート、ページをまたいで分割された表の続きはこのように動きません。既定値：種類の`defaultPlacement`、次に`layout.floatsAtCitingPage`。postext 1.25 から。 | フロートは、読む順序で**最初の参照の後にある最初の空き位置**に置かれます。順に、参照がある段の下端、同じページで次に空いている段の上端と下端、そして流れが開く次のページの帯です（ページ幅のフロートは、すべての段にまだ収まる余地があればページの下端を取り、そうでなければ次のページの帯を取ります）。インラインの図や表が開くページも対象になります。そのページを待っているフロートは、両方が収まる場合、図や表の上にあるページの先頭を取ります。収まらない場合は図や表がそのページを使い、フロートは次のページを待ちます。postext 1.4までは、そのようなページは飛ばされ、両方が収まる場合でもフロートはその次のページを待っていました。フロートは、`shrink`で置き場所の空きまでの縮小を許していない限り元の大きさで組まれ（上の表を参照）、参照より前に置かれることもありません。同じ番号の系列のフロートは参照の順に現れます。あるページのどこにも収まらない図は、後ろの図を待たせます（待っている表が図を待たせることも、その逆もありません）。そのため図12が図11より前に現れることはありません。待つことになる表は、代わりに分割されます。空いた段の先頭が提供されると、収まる行だけを取り、ヘッダー行を繰り返して次の位置（隣の段か次のページ）に続きます（`tableStyle.overflow`を参照）。`citingPage`をオンにした`top`または`auto`のフロートは、代わりに参照行のあるページ（または段）の先頭に置かれることがあり、参照より前の本文はその下に送られます。このときフロートは同じページで参照より上に描かれますが、それより前のページに置かれることはなく、タグ付き PDF と HTML では参照の後に読まれます。エンジンは数回の追加パスでこれを決め、参照行がそのページに残る場合にだけ保持します。 フロートが章の外に出ることはありません。章扉（`breakBefore`または`span: 'page'`を持つ見出しレベル）、`:::part`、`floatBarrier: true`を指定した囲みスタイル（章末の「要点」の囲み）、文書の末尾では、保留中のフロートがすべて先に配置されます。置かれるのは、そのページの空き位置か、境界より前に開いたページです。章扉自体が最初に参照するフロート（自分の図を挙げる章タイトル）や、`:::part`の後の最初のブロックが最初に参照するフロートは新しい章に属し、ほかのフロートと同じくその行の後に置かれます。ページの先頭を求めた図や表は、専用のページではなく、章の最後のページの、段末をそろえた段の下にある下端を取ることがあります。`:::pagebreak`は、保留中のフロートをその後のページに送るだけです。 2段以上の本文の上に組んだページ幅の章扉の下では、章扉のある段にまだ章扉の後の内容がないあいだ、その段の先頭は空いているものとして扱われます。章扉の直後に置いたフロートの囲みや、そこに`::resource`で埋め込んだリソースは、章扉の下で第1段の先頭に入り、ほかの段の先頭とそろいます（`columns`があれば第1段から数段にまたがります）。その段の本文はその下から始まります。本文中で参照されるフロートは、これまでどおり参照する行の後に置かれます。postext 1.24までは第1段のこの位置は使われず、フロートは第2段から置かれていました。`layout.floatsUnderOpener: false`でその動作を保てます（[設定 › レイアウト](https://postext.dev/ja/docs/configuration-page-layout.md#レイアウト)を参照）。 サイド段の囲み（`span="side"`）も章の外には出ません。そのページのサイド段に収まらない囲みは、次のページのサイド段に置かれます。その前に章または文書が終わると、待っている囲みはそれぞれ、フェンスの順に本文の後に開いたページのサイド段に置かれ、その後で参照されたサイド段の図はそれらの後ろに置かれます。そのページには本文がないので、ビルドはそこにある囲みと図をすべて知らせます（`afterText`）。空のサイド段より高い囲みもそのまま置かれて知らされ（`calloutOverflow`）、それでもページが見つからないものも、捨てられずに知らされます（`unplaced`）。postext 1.24までは、そうしたページは最初の1ページしか開かれず、残りの囲みは警告なしに失われていました。 フロートの帯はベースライングリッドに合わせて補正され、周囲のテキストはページ全体の縦のリズムを保ちます。**上端**の帯は下側の余白を次のグリッド線まで広げるので、フロートの下のテキストは隣の段や向かいのページとそろったままになります。**下端**のフロートは、キャプションの最終行がほかの段の最終行とベースラインを共有するように固定されます（キャプションのない内容は下端を最後のグリッド位置にそろえます）。そのため満杯のページは、段をまたいでも見開きをまたいでも同じ高さで終わります。 章の最後のページ（および文書の最後のページ）では、テキストの最後の帯の下に組まれたページ幅の図や表の後には何も続きません。そのため、それらはテキストの下にフロートのアキ1つ分だけ空けて、順に積み重ねて上に移動し、テキストとページ下端の図の間に空白を残しません。`position: 'bottom'`のフロートも同じです。ほかのページと同じく下端に置いたままにするには、`layout.hugClosingFloats: false`を設定します（[設定 › レイアウト](https://postext.dev/ja/docs/configuration-page-layout.md#レイアウト)を参照）。サイド段のあるページでは移動しません。 canvasのプレビュー、HTMLビューアー、PDF出力の3つのバックエンドすべてがリソースを描画します。HTMLバックエンドでは画像データが本体とは別に保持されるため、ホストが`resourceImageUrl(fileId)`リゾルバーオプションで渡します。リゾルバーがない場合（またはファイルに対して何も返さない場合）、リソースは中立的なプレースホルダーの枠として描画され、レイアウトは崩れません。動画のファイル自体も、同じように`resourceVideoUrl(fileId)`で渡します（[動画](https://postext.dev/ja/docs/document-format-resources.md#動画)を参照）。 #### フロートが置かれる場所 「参照より前には置かない」は、フロートを参照する行から数えます。フロートはその行が組まれるまで待ち、読む順序でその後にある最初の空き位置を取ります。その行が組まれるページの先頭は、行より前にあたります。サイドフロート（`span: 'side'`。1段半レイアウトのフロート専用のサイド段に置くもの）は例外で、参照するテキストの横のサイド段に積み重ねられ、参照行よりページの上のほうに置かれることもあります。5ページで参照される図の場合は次のとおりです。 | 配置 | 5ページでは | それ以外 | | --- | --- | --- | | `top`, `span: 'page'` | 置かれません。ページ先頭の帯は参照行より上にあります。 | 6ページの上端の帯。 | | `top`, `span: 'column'` | まだ空いている後続の段の先頭。2段組みの1段目で参照された場合、2段目の先頭に置けます。 | 6ページのいずれかの段の先頭。 | | `auto`または`bottom`, `span: 'page'` | すべての段にまだ余地があれば、5ページの下端の帯。 | 6ページの帯。 | | `auto`または`bottom`, `span: 'column'` | 参照する段の下端。次に、後続の空いた段の下端（どちらの値でも）または先頭（`auto`のみ）。 | 6ページ。 | - 章扉のページにも同じ規則が適用されます。章扉の最初の段落で参照されたページ幅の`auto`または`bottom`のフロートは、そのページの下端の帯（テキストの下）を取れます。`top`のフロートは次のページの先頭に置かれます。参照するページに画像を置くには、`auto`か`bottom`を使うか、章扉のデザインの画像要素として描きます。 - 同じ段落で参照された2つの段のフロートは、続く2つの位置を取ります。通常、1つ目は参照する段の下端、2つ目は次の空いた段の先頭に置かれ、ページ上で横に並びます。 - 1段組みのレイアウトではページ幅のフロートは段のフロートと同じで、同じ規則が適用されます。あるページで参照された`top`のフロートは、次のページの先頭に置かれます。 - ページをまたぐ段落も、参照行から数えます。段落が5ページの下端で始まり、参照が6ページにある場合（あるいは、5ページの下端に収まる行が足りず段落全体が6ページに移る場合）、参照は6ページにあることになります。`top`のフロートは7ページの先頭に置かれ、`auto`のフロートは余地があれば6ページの下端を取ります。同じページの段の間や、ページをまたいで分割された囲みでも同様で、囲みの2つ目の部分が参照する図はその部分を待ちます。 - **postext 1.5での変更**。postext 1.4までは、フロートを参照する段落にレイアウトが達した時点でフロートが待ち行列に入っていたため、そのような段落が続く（または移る）ページの先頭、参照を含む行より上にフロートが置かれることがありました。現在そのような図は1ページ後に置かれるか、`auto`を求める場合はそのページの下端に置かれます。その結果、ページ数が変わることがあります。 ### 回り込み 段より狭い図版、表、ボックスは、雑誌や会報のように段の片側に置き、本文をその横に組めます。配置に`wrap`の側と、必要なら`width`を指定します。 ```json { "id": "bed", "typeId": "figure", "kind": "svg", "caption": "新しい花壇。", "placement": { "position": "here", "wrap": "right", "width": 0.4 } } ``` - **本文中（`"here"`）。** リソースは段のその側に置かれ、上端は`::resource`行の次の行の上端にそろいます。続く段落、引用、箇条書きの項目は残りの行長でその横に組まれ、下では全幅に戻ります。横で始まり下で終わる段落は 1 つの段落のままで、途中で切れず、図版の下に余分な空きも入りません。すべての行がベースライングリッドに乗り、図版の下の空きは間隔を行送りの整数倍に切り上げたものです。 - **段のフロート。** 1 段幅の`span: "column"`フロートを段頭（`"top"`、または段頭の`"auto"`）か段末（`"bottom"`、`"auto"`）に置くと、ほかのフロートと同じく帯に置かれ、段の最初または最後の行がその横に組まれます。2 段組では、フロートは自分の段に属し、もう一方の段は全幅のままです。 - **ボックス。** `:::callout`は同じ設定を属性で受け取ります。`:::callout{wrap="right" width=0.4}`は現れた位置に引用や囲み記事を置き、続く本文を横に組みます。`placement="top"`または`"bottom"`と`wrap`を併せると段頭か段末に浮かせます。回り込むボックスはまとめて組まれ、分割されません。 - **下に回るもの。** 見出し、別行立ての数式、図や表、ボックス、詩は回り込む対象の横に組まれず、その下に回ります。その上の横の余白は空いたままです。段を離れると（段末、`:::columnbreak`、改ページ）そこで回り込みは終わり、対象は自分の段に属します。本文中のリソースの直後のブロックが横に組めないときは、`wrap`がない場合と同じくリソースが帯を占めます。 - **間隔と限度。** `wrapGap`（なければ`layout.wrap.gap`、それもなければ本文 1 行分）が、キャプションを含む対象と横および下の本文とを隔てます。横の本文が`layout.wrap.minTextWidth`（本文の 12 em）より狭くなる場合や、対象が`layout.wrap.minLinesBeside`行（2）より低い場合は、全幅を占め、`textWrap`警告が出ます。段の残りに収まらない本文中の対象は、アンカーとともに次の段へ移り、同じ警告が出ます。 - **左右。** `left`と`right`は`align`と同じく本文の流れの側です。右から左の本では`left`は紙面の右です。`start`と`end`は同じ側を指します。 - **出力。** キャンバス、HTMLビューアー、PDF、固定レイアウトEPUBはレイアウトどおりに行を組みます。タグ付きPDFは、図版やボックスを横に組まれた段落より先に読みます。リフロー型EPUBはCSSで同じ幅の割合のまま片側に浮かせます。 - **未対応。** 図版の両側に本文を組むこと、輪郭に沿った回り込み、ボックスの中身の中での回り込み、縦組みでの回り込み（対象は帯のままで警告が出ます）。回り込む対象のある段は段のそろえから外れます。 ### ビットマップのサイズ ビットマップは自分のピクセル数を宣言します。`bitmap.width`と`bitmap.height`はファイルのピクセル数で、印刷サイズではありません。1インチに何ピクセルを割り当てるかで、置き場所による上限がかかる前の画像の大きさが決まります。サイズの決め方は3つあります。 - **ページのdpiでのピクセル数**（既定）。解像度がなければ、画像の1ピクセルはレイアウトの1ピクセルです（`page.dpi`。指定しなければ300）。2400 pxの写真は、300 dpiのページでは幅8インチ（203.2 mm）、150 dpiのページではその2倍になります。 - **解像度**。`bitmap.resolution`は原寸で印刷したときの画像のppiなので、原寸の幅はページのdpiにかかわらず`width × page.dpi / resolution`です。`resolution: 300`の2400 pxは、150 dpiで組んだページでも300 dpiで組んだページでも幅203.2 mmです。`layout.bitmapResolution`は、自身の解像度を持たないすべてのビットマップに解像度を与えます。値は数値（`300`）か、ファイルに記載された解像度を使う`'file'`です（`bitmap.fileResolution`。PNGの`pHYs`、JPEGのJFIFまたはEXIFの密度、WebPのEXIF。Wordから読み込んだ画像では、Wordで印刷されるサイズ）。カメラ、スクリーンショット、Web向けの書き出しは、印刷サイズを何も知らないまま72や96 ppiと記載することが多いため、`'file'`ではこの2つを記載なしとして扱い、画像はページのdpiでのピクセル数のままになります。リソース自体に宣言した72は、書かれたとおりに使われます。既定の`'document'`は1つ目の方法です。 - **段に対する割合**。`placement.width`はフロートやインラインの埋め込みを段（またはページ）の幅の一定の割合まで狭めます。その幅より大きい画像は、ピクセル数にかかわらずその幅まで縮小されます（[配置](https://postext.dev/ja/docs/document-format-resources.md#配置)を参照）。 どの場合も、画像は縦横比を保ったまま置き場所を上限とし、それより小さい画像が拡大されることはありません。表のセルの画像や、サイズが`'auto'`のデザインの`image`要素にも、同じ原寸が使われます。PDFはファイルをそのまま、配置したサイズで埋め込みます。各画像が印刷される解像度は[プリフライト](https://postext.dev/ja/docs/configuration-fonts-colors-viewers.md#プリフライト)で検査され、Sandboxの[**リソース**パネル](https://postext.dev/ja/docs/sandbox.md#リソースパネル)には画像ごとに表示されます。postext 1.24から。 ```json { "id": "harbour", "typeId": "figure", "kind": "bitmap", "caption": "The harbour at dawn.", "bitmap": { "fileId": "harbour.jpg", "format": "jpeg", "width": 2400, "height": 1600, "resolution": 300 } } ``` `bitmapInfo(bytes)`（`postext`と`postext/bundle`がエクスポート）は、ファイルのピクセル数と、ファイルに記載された解像度を`{ width, height, resolution?: { x, y, source } }`として読み取ります。`'file'`で開いたバンドルはこれで`fileResolution`を埋め、Sandboxはアップロードしたすべての画像についてこの値を保存します。 ### セーフエリア ビットマップやSVGのリソースには**セーフエリア**を指定できます。画像の中で重要なもの（人物とその背後の風景の一部、グラフのプロット部分など）を含み、常に表示される長方形です。これはリソースの`safeArea`で、画像の固有サイズに対する4つの割合（0〜1）を左上の角から測ります。`x`と`width`は幅に対する割合、`y`と`height`は高さに対する割合です。この名前は残すべきものを表します。トリミングの枠なら、どこを切るかを表すことになります。 ```ts const harbour: Resource = { id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.', createdAt: 0, updatedAt: 0, bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 }, // the boats and the quay: 18–68 % of the width, 25–85 % of the height safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 }, }; ``` トリミングされるのはセーフエリアのある画像だけです。その場合エンジンは、画像全体からセーフエリアまでの間の任意の縦横比で画像を表示できます。左右を切り落として画像本来の比率より縦長にする場合はセーフエリアの幅まで、天地を切り落として横長にする場合はセーフエリアの高さまでです。図の幅は変わらず、変わるのは高さだけです。セーフエリアの外側は、その両側の余白に比例して切り落とされるので、中央より左にある被写体は中央より左に残ります。上の港の画像を幅60mmで組むと、全体を表示したときの高さは40mmで、24mm（天地を高さの60%まで切り落とす）から80mm（左右を幅の半分まで切り落とす）までの任意の高さで表示できます。画像の端を超える値は端に収められます。数値でない値を含む範囲、辺が画像の2%未満の範囲、画像全体を覆う範囲は無視され、表に指定した場合も無視されます。セーフエリアがなければ、画像はこれまでどおり常に全体が表示されます。 エンジンはこの余裕を4つの場面で使います。 - **段に残った余地**。インラインの画像（`position: 'here'`）が段に残った余地に対して少し高すぎる場合（キャプションがページの下端を超えてしまう場合も含む）、次の段やページに移ってこの段を短く残す代わりに、セーフエリアの範囲でトリミングしてその段にとどまります。 - **図より短いページ**。`layout.fitFiguresToPage`を指定すると、ページに対して高すぎる画像はまず幅を保ったままセーフエリアの範囲でトリミングされ、それでも高すぎる場合にだけ縮小されます（[設定 › レイアウト](https://postext.dev/ja/docs/configuration-page-layout.md#レイアウト)を参照）。 - **図より短い帯**。`placement.shrink`で置き場所の空きまで縮小するフロートは、まず幅を保ったままセーフエリアの内側でトリミングし、それでも足りないときに縮小します。下の`flexFigure`のレバーがその空きを超えて伸ばすことはありません。 - **段末そろえ**。短い段にインラインで組まれた画像や、その段だけにかかるように段の先頭か下端にフロートとして置かれた画像のうち、セーフエリアのあるものは、段の空いた行を埋めるようにベースライングリッドの行単位で高くなります。画像が高くなっても目に見える穴は残らないので、この調整手段`flexFigure`は、段を閉じる囲みの調整の直後、見出しの上やリストの後にアキを加えるより前に試されます。章の最後のページや閉じの帯で段の先頭に置かれたフロートは高くなりません。それらの段の先頭は高さをそろえたままにするためです（[設定 › 段末そろえ](https://postext.dev/ja/docs/configuration-page-flow.md#段末そろえ)を参照）。 VDTはトリミングをリソースのブロックに記録します。`bodySource`は`bodyRect`に表示される画像の部分で、同じ割合で表します（画像全体が収まる場合はありません）。`bodyFlex`は、本体がまだ縮められる量と伸ばせる量、および調整手段がすでに変えた量をpxで示します（`{ shrink, grow, delta }`）。canvasのプレビューとPDFは本体でクリップし、トリミングしない大きさで画像全体を描きます。HTMLビューアーと固定レイアウトのEPUBは、`object-fit: cover`とそれに合わせた`object-position`で画像を組みます。埋めるべきページのないリフロー型のEPUBでは、画像全体を表示します。画像を自前で描くホストは、`postext`がエクスポートするヘルパーを使えます。`resourceSafeArea`と`normalizeSafeArea`（エンジンが読み取るセーフエリア、または`undefined`）、`safeAreaHeightRange`（ある幅での本体の最小と最大の高さ）、`safeAreaSource`（ある高さで表示される部分）、`uncroppedPictureBox`（クリップの前に画像全体を描く位置）、そして型`ResourceSafeArea`です。Sandboxでは、[**リソース**パネル](https://postext.dev/ja/docs/sandbox.md#リソースパネル)の画像にある**セーフエリア**の項目で設定します。 レシピ集のNo. 116「[短い段を埋めるように伸びる写真](https://postext.dev/ja/cookbook/photos-fill-short-columns.md)」は、2段組みの雑誌特集をセーフエリアなしとセーフエリアありの2回組むので、ページを並べて比べられます。 ### 話者のアンカーと回避エリア 漫画のコマの絵になる画像は、写植のために、人物がどこにいるかも示せます（[漫画](https://postext.dev/ja/docs/document-format-directives.md#漫画)を参照）。`anchors`は話し手ごとに1つの点を、`avoid`はどの吹き出しも覆わない範囲を並べ、どちらもセーフエリアと同じく画像に対する割合で表します。 ```ts const radio: Resource = { id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0, bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 }, safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 }, anchors: [ // 灯台守：口、頭（思考の吹き出し用）、顔 { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } }, ], avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // 無線機 }; ``` アンカーの`id`は台本の話し手のキー（`tomas: …`）か、コマの描き文字を集める点を表す`sfx`です。`x`と`y`はセリフの吹き出しのしっぽが指す口、`head`は思考の吹き出しの泡が指す点（未設定なら口）、`face`はどの吹き出しも覆わない長方形です。エンジンはすべての点をコマのトリミングと反転を通して写すので、コマがどんな形になってもしっぽは話し手から外れません。セーフエリアの外にあるアンカーは、トリミングで切られるおそれがあるので`comicAnchorOutsideSafeArea`を出します。3つ目の一覧`faces`には、話さない人物の顔を`avoid`と同じ長方形で書きます。吹き出しはこの顔を覆いません。回避エリアのほうは、コマにほかの場所がないときには覆われます。アンカーは画像に属し、その漫画のどの翻訳にも使えます。アンカーを読むのは漫画のコマだけで、図は無視します。Sandboxでは、[**リソース**パネル](https://postext.dev/ja/docs/sandbox.md#リソースパネル)の**セーフエリアと写植**のダイアログで指定します。 ### 動画 **動画**リソース（`kind: 'video'`）は、YouTubeまたはVimeoの動画、あるいは自前の動画です。自前の動画は、本の中に持つファイル（MP4、WebM）でも、Webのアドレスにあるもの、つまりサーバー上のファイルや**HLSストリーム**（`.m3u8`のプレイリスト）でもかまいません。画像と同じように配置、キャプション付け、フロート、参照ができ、独自の系列で番号が付きます。組み込みの`video`の種類は、*Figure 1.1*や*Table 1.1*と並んで*Video 1.1*、*Video 1.2*…と表示します（[設定 › リソースの種類](https://postext.dev/ja/docs/configuration-resources.md#リソースの種類)を参照）。各出力は、それぞれ可能な形で動画を表示します。 | 出力 | 表示されるもの | | --- | --- | | Canvas、PDF | 動画の1フレームである**ポスター画像**に、再生マークと動画を開くQRコードを重ねて表示します（[設定 › 動画スタイル](https://postext.dev/ja/docs/configuration-resources.md#動画スタイル)）。PDFでは、ポスター画像は動画へのリンクにもなります。 | | Folio | 印刷物と同じポスター画像を表示します。クリックすると動画は**そのページの上で**再生され、丁をめくっている間も再生が続きます（後述の[Folioのページで再生する動画](https://postext.dev/ja/docs/document-format-resources.md#folioのページで再生する動画)を参照）。YouTubeやVimeoの動画はポスター画像のままです。 | | HTMLビューアー | 動画の**プレーヤー**を表示します。YouTubeやVimeoのプレーヤー、ファイルやアドレスの場合はブラウザーのHTML5プレーヤーです。HLSストリームはSafariと最近のChromeではそのまま再生され、それ以外のブラウザーでは、Sandboxがしているように、ホストがhls.jsなどのプレーヤーを付けます。`videoStyle.html: 'poster'`を指定すると、代わりに印刷用のポスター画像を表示します。 | | EPUB | ファイルは本に同梱されるか公開先のアドレスから読み込まれ、リーディングシステム自身のプレーヤーで再生されます。YouTubeやVimeoの動画は、動画にリンクしたポスター画像になります。EPUBにはWebページのプレーヤーを埋め込めないためです。HLSストリームも、動画にリンクしたポスター画像になります。HLSのプレイリストは、EPUBが再生してよいメディアタイプではないためです。リーディングシステムがスクリプトを実行する場合、同じページや章のファイルは`player.exclusive`に従います。1本を再生すると、同時に再生しないほかの動画が一時停止します。 | ```ts const talk: Resource = { id: 'keeper-talk', typeId: 'video', kind: 'video', caption: 'The keeper explains the lamp.', altText: 'A lighthouse keeper beside the lamp', createdAt: 0, updatedAt: 0, video: { source: 'youtube', // 'youtube' | 'vimeo' | 'file' url: 'https://youtu.be/aqz-KE-bpKQ', poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 }, start: 30, // plays from 0:30; the printed link starts there too }, }; ``` 本文は図と同じように動画を参照します。`:ref{id="keeper-talk"}`は*Video 1.1*と表示し、参照の後にある最初の空き位置へポスター画像をフロートとして配置します。`placement.position: 'here'`を指定して`::resource{id="keeper-talk"}`を書くと、本文中に組まれます。`Resource.video`（`ResourceVideo`）の項目は次のとおりです。 | 項目 | 型 | 意味 | | --- | --- | --- | | `source` | `'youtube'` · `'vimeo'` · `'file'` | 動画の再生元。YouTubeやVimeoのページ、または自前の動画（`'file'`）で、自前の動画はアップロードしたものでもアドレスにあるものでもかまいません。 | | `url` | `string` | YouTubeまたはVimeo：動画のアドレス。形式は問いません（視聴ページ、`youtu.be`、ショート、埋め込みリンク、`youtube-nocookie.com`。Vimeoのページ、チャンネルのページ、ハッシュ付きの限定公開リンク）。ファイル：その**公開先のアドレス**、つまり公開された本がファイルを見つける場所。ファイルを持たない自前の動画は、このアドレスから再生されます。サーバー上のMP4やWebM、あるいはHLSストリーム（`…/master.m3u8`）です。 | | `fileId`, `format` | `string` | ファイル：アップロードした動画（ビットマップと同じく本体とは別に保存されます）とその形式。形式は`'mp4'`、`'webm'`、`'ogv'`、`'mov'`、HLSストリームなら`'hls'`です。形式を指定しなければアドレスの拡張子で決まり（`.m3u8`は`'hls'`）、それもなければ`'mp4'`になります。 | | `poster` | `{ fileId, format, width, height }` | ポスター画像のフレーム（ビットマップ）。 | | `width`, `height`, `duration` | `number` | 動画のフレームサイズ（px。ポスター画像がない場合は縦横比として使います）と長さ（秒）。 | | `posterTime` | `number` | ファイルのどの秒のフレームをポスター画像にしたか。選び直せるように保存されます。 | | `start`, `end` | `number` | `start`秒から`end`秒まで再生します。QRコードとPDFのリンクも`start`から始まります。 | | `player` | `VideoPlayerOptions` | この動画のプレーヤーオプション。`videoStyle.player`の上に重ねて適用されます。 | **ポスター画像**。その位置の行長（またはその`placement.width`の割合）で、ピクセルサイズにかかわらず自身の縦横比で組まれます。画面サイズのフレームは、小さく印刷されるのではなく拡大されます。ビットマップと同じく[セーフエリア](https://postext.dev/ja/docs/document-format-resources.md#セーフエリア)を持つことができ、`placement.align`に従います。ポスター画像のない動画は、動画の縦横比（指定がなければ16:9）の暗い枠をオーバーレイ付きで印刷し、`videoWithoutPoster`の内容の警告を出します。Sandboxでは、YouTubeやVimeoの動画のポスター画像はアドレスを入力したときにプラットフォームから取得され、ファイルの場合は動画の中から選んだフレームになります。 **アドレス**。QRコードとPDFのリンクは、動画のページ`https://youtu.be/`または`https://vimeo.com/`を`start`の位置から開きます。ファイルにはページがないので、公開先のアドレスを開きます。ファイルを持たない動画（サーバー上のMP4、HLSストリーム）も、このアドレスから再生されます。それがない場合、印刷物にはQRコードもリンクも付かず（`videoWithoutUrl`）、ファイルを含まないHTMLやEPUBの出力はポスター画像を表示します。YouTubeやVimeoのアドレスがそのプラットフォームの動画を指していない場合は`videoUrlInvalid`が出て、プレーヤーの代わりにポスター画像が表示されます。 **プレーヤー**。プレーヤーのオプション（コントロール、ダウンロードボタン、全画面表示、速度メニュー、ピクチャーインピクチャー、キャスト、自動再生、ミュートでの開始、ループ、プリロード、プライバシー強化モードの埋め込み）は、本全体には`videoStyle.player`で、1つの動画には`video.player`で設定します。各プレーヤーは対応できる範囲でこれに従います（[設定 › 動画スタイル](https://postext.dev/ja/docs/configuration-resources.md#動画スタイル)を参照）。HTMLバックエンドは、画像を`resourceImageUrl`で受け取るのと同じように、ファイルの再生可能なURLを`resourceVideoUrl(fileId)`オプションで受け取り、なければ公開先のアドレスを使います。その`videos: { files, streams, hls }`オプションは、`videoStyle.html`に優先して、再生元ごとにプレーヤーかポスター画像かを選びます（`hls`はHLSのアドレスから再生する動画のためのもので、指定しなければ`files`に従います）。EPUBライターもこれを使います。HLSのアドレスを再生する`