docx-svg

DOCX SVG -- Word ドキュメントの SVG 画像サポート

方針：変換ゼロ（必須）

SVG ファイルを .docx に挿入する前に、PNG、JPEG、その他のラスター形式に絶対に変換しないでください。

最新の Word（2016 以降）は、asvg:svgBlip OOXML 拡張機能を介して SVG をネイティブにサポートしています。PNG に変換すると、ベクター画像の利点（拡大縮小性、ファイルサイズ、鮮明さ）が損なわれます。

1. ユーザーがレガシー環境との互換性を明示的に求めない限り、「ベストプラクティス」としてラスター形式へのフォールバックを提案しないでください。
2. OOXML を直接扱うのは「複雑すぎる」と主張しないでください。このスキルでは、その複雑さに対処するツール（officecli または scripts/svg.py）を提供しています。
3. ソースファイルとしては、常に SVG をそのまま使用してください。
4. .docx に挿入するために SVG を PNG/JPEG に変換するリクエストを受けた場合は、変換を断り、代わりに SVG を直接挿入してください。

概要

Microsoft Word は OOXML 形式の SVG 画像をサポートしていますが、一般的なプログラム用ツール（python-docx、docxtpl）は標準では SVG を認識しません。このスキルでは、優先順位順に2 つの方法を提供します。

優先度	ツール	使用する場合
1. 推奨	officecli	環境で利用できる場合は常に
2. フォールバック	Python モンキーパッチ（scripts/svg.py）	officecli がインストールされていない、利用できない、またはバージョンチェックに失敗した場合

officecli が存在していても v1.0.64 より古い場合は、使用しないでください。代わりに Python のフォールバックを使用してください。不完全な、または古い officecli のインストールを使用しないでください。

---

方針：まず officecli を確認する

方法を選択する前に、officecli が利用可能かどうかを確認します。

officecli --version

バージョンが v1.0.64 以降の場合：officecli を使用します（以下のセクション 1）。 見つからない場合、またはバージョンが v1.0.64 より古い場合：Python のフォールバックを使用します（以下のセクション 2）。

---

技術的な背景：仕組み（OOXML）

SVG を挿入するとき、Word は a:blip 要素内に a:ext ブロックがあることを想定しています。officecli と scripts/svg.py は、どちらもこれを自動的に生成します。

構造の参考情報（概要把握用）：

<a:blip r:embed="rId1">
  <a:extLst>
    <a:ext uri="{96DAC541-0531-4A20-96AC-8D759B1F206D}">
      <asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG" r:embed="rId2"/>
    </a:ext>
  </a:extLst>
</a:blip>

• rId1 は PNG/JPEG のフォールバックを指します（最新の Word では任意ですが、必要な場合は officecli が処理します）。
• rId2 は word/media/ 内の実際の .svg ファイルを指します。

---

セクション 1：推奨 -- officecli

officecli は docx の画像に対するネイティブな SVG サポートを備えています。モンキーパッチも追加依存関係も不要で、Python も必要ありません。

インライン SVG 画像を追加する

officecli add report.docx /body --type picture --prop file=chart.svg

サイズを明示して追加する

officecli add report.docx /body --type picture --prop file=chart.svg --prop width=10cm --prop height=6cm

特定の段落の後に追加する

officecli add report.docx '/body/p[2]' --type picture --prop file=chart.svg --prop width=12cm

テキストを折り返す浮動画像を追加する

# Insert as floating image, then set wrap and position
officecli add report.docx /body --type picture --prop file=hero.svg --prop width=8cm
# Use the returned picture path to set wrap mode
officecli set report.docx '/body/pic[1]' --prop wrap=square

画像のプロパティを設定する

画像を追加した後、officecli set を使用して調整します。

officecli set report.docx '/body/p[3]/picture[1]' --prop alt="Sales chart Q4"
officecli set report.docx '/body/p[3]/picture[1]' --prop brightness=10 --prop contrast=-5
officecli set report.docx '/body/p[3]/picture[1]' --prop hposition=2cm --prop hrelative=page

利用可能な画像プロパティを確認する

プロパティ名が不明な場合は、ヘルプシステムを実行します。

officecli help docx image
officecli help docx picture

---

セクション 2：フォールバック -- Python モンキーパッチ

この方法は、officecli が利用できない場合にのみ使用してください。scripts/svg.py モジュールは python-docx と docxtpl にモンキーパッチを適用して、SVG をサポートします。

モジュールをインポートするとパッチが自動的に適用されるため、依存関係をインストールする以外の手動セットアップは不要です。

依存関係をインストールする

uv run python scripts/svg.py

このスクリプトは PEP 723 のインラインメタデータで依存関係（python-docx>=1.1.2、docxtpl>=0.19.0）を宣言しているため、uv run が自動的に解決します。

python-docx を直接使用する

import docx
from scripts import svg  # noqa: F401  # <- patch activates on import
from docx.shared import Mm

doc = docx.Document()
doc.add_paragraph("Below is an SVG chart:")
doc.add_picture("chart.svg", width=Mm(120))
doc.save("report.docx")

scripts.svg をインポートすると、python-docx にグローバルなモンキーパッチが適用されます。これにより、add_picture は PNG/JPEG に加えて .svg ファイルも受け付けるようになります。

重要： Python のフォールバックを使用する場合も、PNG に変換しないでください。このパッチは SVG のネイティブ埋め込みに対応します。

docxtpl テンプレートの使用方法

from docxtpl import DocxTemplate
from scripts.svg import SvgInlineImage
from docx.shared import Mm

tpl = DocxTemplate("template.docx")
img = SvgInlineImage(tpl, "chart.svg", width=Mm(100))
tpl.render({"chart": img})
tpl.save("output.docx")

テンプレートでは、段落内に {{ chart }} を配置します。SvgInlineImage は SVG ファイルを自動的に検出し、パッチ適用済みのパイプラインで処理します。

自動サイズ調整

width と height の両方を省略すると、画像は使用可能なページ幅（ページ幅から左右の余白を差し引いた幅）いっぱいに表示されます。

img = SvgInlineImage(tpl, "wide-chart.svg")  # auto-sizes to page width

ユーティリティ：ファイルが SVG かどうかを確認する

from scripts.svg import is_svg

assert is_svg("icon.svg")

---

Python フォールバックの仕組み

1. インポート時のモンキーパッチ -- モジュールは3つの SVG バイトシグネチャ（<?xml、<svg、<!DOCTYPE svg）を登録し、 image/svg+xml を python-docx の MIME タイプ定数に追加して、_ImageHeaderFactory を置き換え、デフォルトの64バイトではなく256バイトをスキャンします。

2. SVG の寸法の抽出 -- Svg._dimensions_from_stream は width / height 属性を読み取り（pt、cm、mm、% などの単位を除去）、これらの属性がない場合は viewBox を使用します。

3. docxtpl ヘルパー -- SvgInlineImage は InlineImage のサブクラスであり、パッチ適用済みのファクトリーが SVG を解析できるよう、Path デスクリプターを上流に渡す前に BytesIO に変換します。

制限事項

• Word での SVG のレンダリング：Microsoft Word は SVG を静止画像としてレンダリングします。 インタラクティブ機能（ホバー、アニメーション、埋め込み JavaScript）は OOXML 形式ではサポートされていません。
• フォールバック画像（Python アプローチのみ）：現在の実装では、OOXML パッケージ内に PNG フォールバックを追加しません。古いバージョンの Word（2016 より前）では SVG が表示されない場合があります。互換性が必要な場合は、 SVG を事前に PNG に変換してください。
• 寸法の単位（Python アプローチのみ）：パーサーは、すべての単位を72 DPIでピクセルに正規化します。印刷精度の高いサイズ指定が必要な場合は、docx.shared.Mm / Inches / Cm を使って width / height を明示的に指定してください。