Python を使用して構造化された Word 文書を作成する方法

Python アプリケーションにおいて、Word 文書をプログラムで生成することは非常に一般的な要件です。
レポート、請求書、契約書、監査ログ、エクスポートされたデータセットなどは、単なるテキストや PDF ではなく、編集可能な .docx ファイルとして提供されることが多くあります。

プレーンテキストとは異なり、Word 文書は 構造化ドキュメント です。
セクション、段落、スタイル、レイアウト規則といった要素で構成されており、.docx ファイルを単なる文字列コンテナとして扱うと、レイアウト崩れや保守性の低下を招きます。

本チュートリアルでは、Spire.Doc for Python を使用し、実践的な Word 文書作成方法 を解説します。
Word 本来のドキュメントオブジェクトモデルに沿って文書を構築し、正しい構造レベルで書式を適用することで、コンテンツが増えても安定して編集可能な .docx ファイルを生成する方法を紹介します。

コンテンツ一覧

• 1. Python における Word 文書構造の理解
• 2. Python で基本的な Word 文書を作成する
• 3. テキストの追加と書式設定
• 4. Word 文書への画像挿入
• 5. 表の作成とデータの入力
• 6. ヘッダーとフッターの追加
• 7. セクションによるページレイアウト制御
• 8. 文書プロパティとメタデータの設定
• 9. 保存・エクスポートとパフォーマンスの考慮点
• 10. Python で Word 文書を作成する際の注意点

1. Python における Word 文書構造の理解

コードを書き始める前に、Word 文書が内部的にどのような構造を持っているかを理解することが重要です。

.docx ファイルは単なるテキストの連続ではありません。
以下のような複数のオブジェクト階層で構成されています。

• Document – 文書全体を管理するルートコンテナ
• Section – ページサイズ、余白、向きなどのページレイアウトを定義
• Paragraph – 論理的なテキストブロック
• Run（TextRange） – 文字書式を持つインラインテキスト
• Style – 段落やテキストに適用可能な再利用可能な書式定義

Python で Word 文書を作成する際は、この階層構造を コード上で明示的に構築 することになります。
書式やレイアウトは、適切な階層レベルで設定した場合にのみ、予測通りに動作します。

Spire.Doc for Python は、これらの要素に対応する抽象化を提供しており、Word 自体の構造に非常に近い形で文書を操作できます。

2. Python で基本的な Word 文書を作成する

このセクションでは、Spire.Doc を使用して Python から有効な Word 文書を生成する方法を紹介します。
正しい文書構造と基本的な処理フローに焦点を当てます。

Spire.Doc for Python のインストール

pip install spire.doc

または、Spire.Doc for Python をダウンロード して手動で組み込むことも可能です。

シンプルな .docx ファイルの作成

from spire.doc import Document, FileFormat

# 文書オブジェクトを作成
document = Document()

# セクションを追加（ページレイアウトを定義）
section = document.AddSection()

# 段落を追加
paragraph = section.AddParagraph()
paragraph.AppendText(
    "この文書は Python によって生成されました。"
    "Spire.Doc を使用した基本的な Word 文書作成の例です。"
)

# 文書を保存
document.SaveToFile("basic_document.docx", FileFormat.Docx)
document.Close()

このコードは、Microsoft Word で正常に開くことができる、最小構成の .docx ファイルを生成します。 文書作成の基本的な流れ（Document → Section → Paragraph → 保存）を示しています。

技術的な観点では次の通りです。

• Document オブジェクトは Word 文書全体の構造と内容を管理します。
• Section は段落に対するページレイアウトのコンテキストを定義します。
• Paragraph は表示されるテキストを保持し、段落レベルの書式設定の基本単位となります。

Spire.Doc で生成されるすべての Word 文書は、この構造パターンに基づいており、以降の高度な操作の基盤となります。

3. テキストの追加と書式設定

Word 文書内のテキストは階層的に管理されます。 書式設定は以下の 2 つのレベルで適用できます。

• 段落レベル：配置、行間、インデントなど
• 文字レベル：フォント、サイズ、色、太字、斜体など

さらに、スタイル を使用すると、これらの書式設定をまとめて定義し、複数の段落やテキストに再利用できます。 段落書式・文字書式・スタイルの違いを理解することは、Python で Word 文書を作成・編集する上で非常に重要です。

段落の追加と段落書式の設定

Word 文書に表示されるすべてのテキストは、必ず段落を通して追加されます。 段落はテキストとレイアウトのコンテナであり、Paragraph.Format を通じて段落レベルの書式を設定できます。 文字レベルの書式は、TextRange.CharacterFormat を使用して設定します。

from spire.doc import Document, HorizontalAlignment, FileFormat, Color

document = Document()
section = document.AddSection()

# タイトル段落を追加
title = section.AddParagraph()
title.Format.HorizontalAlignment = HorizontalAlignment.Center
title.Format.AfterSpacing = 20
title.Format.BeforeSpacing = 20
title_range = title.AppendText("月次売上レポート")
title_range.CharacterFormat.FontSize = 18
title_range.CharacterFormat.Bold = True
title_range.CharacterFormat.TextColor = Color.get_LightBlue()
title_range.CharacterFormat.FontName = "Yu Gothic UI"

# 本文段落を追加
body = section.AddParagraph()
body.Format.FirstLineIndent = 20
body_range = body.AppendText(
    "本レポートでは、地域別および製品カテゴリ別の売上推移を含む、"
    "月次の販売実績概要を示します。"
    "以下のデータは、経営判断を支援する目的で提供されています。"
)
body_range.CharacterFormat.FontSize = 12
body_range.CharacterFormat.FontName = "Yu Mincho"

# 文書を保存
document.SaveToFile("formatted_paragraph.docx", FileFormat.Docx)
document.Close()

生成された Word 文書のプレビューです。

技術メモ

• Paragraph.Format：段落全体の配置、余白、インデントを設定
• AppendText()：TextRange を返し、文字レベルの書式設定が可能
• すべての段落は必ずセクションに属し、段落の順序が読み順とページ分割に影響します

スタイルの作成と適用

スタイルを使用すると、段落レベルおよび文字レベルの書式設定を一度定義し、文書全体で再利用できます。
配置、余白、フォント、強調表現などをスタイルとして管理することで、書式の一貫性が向上し、保守も容易になります。

Word 文書では、カスタムスタイル と 組み込みスタイル の両方を使用できます。
いずれの場合も、スタイルは適用前に文書へ追加する必要があります。

カスタム段落スタイルの作成と適用

from spire.doc import (
    Document, HorizontalAlignment, BuiltinStyle,
    TextAlignment, ParagraphStyle, FileFormat
)

document = Document()

# カスタム段落スタイルを作成
custom_style = ParagraphStyle(document)
custom_style.Name = "CustomStyle"
custom_style.ParagraphFormat.HorizontalAlignment = HorizontalAlignment.Center
custom_style.ParagraphFormat.TextAlignment = TextAlignment.Auto
custom_style.CharacterFormat.Bold = True
custom_style.CharacterFormat.FontSize = 20

# 組み込みの見出しスタイルを基に継承
custom_style.ApplyBaseStyle(BuiltinStyle.Heading1)

# スタイルを文書に追加
document.Styles.Add(custom_style)

# カスタムスタイルを適用
title_para = document.AddSection().AddParagraph()
title_para.ApplyStyle(custom_style.Name)
title_para.AppendText("地域別パフォーマンス概要")

組み込みスタイルの追加と適用

# 組み込みスタイルを追加
built_in_style = document.AddStyle(BuiltinStyle.Heading2)
document.Styles.Add(built_in_style)

# 組み込みスタイルを適用
heading_para = document.Sections.get_Item(0).AddParagraph()
heading_para.ApplyStyle(built_in_style.Name)
heading_para.AppendText("地域別売上")
    
document.SaveToFile("document_styles.docx", FileFormat.Docx)
document.Dispose()

生成された Word 文書のプレビューです。

技術的な解説

• ParagraphStyle(document) は、文書に紐づく再利用可能なスタイルオブジェクトを作成します
• ParagraphFormat は配置やテキストフローなど、レイアウト関連の設定を制御します
• CharacterFormat はフォントサイズや太字など、文字レベルの書式を定義します
• ApplyBaseStyle() を使用すると、組み込みスタイルの意味的構造や既定動作を継承できます
• document.Styles に追加することで、すべてのセクションでスタイルを使用可能になります

見出し 2（Heading 2） などの組み込みスタイルを適切に使用することで、アウトライン表示や目次生成など、Word の機能とも高い互換性を保てます。

4. Word 文書への画像挿入

Word のドキュメントモデルでは、画像は段落に属する埋め込みオブジェクトとして扱われます。 段落にアンカーされた画像は、テキストと自然に連動し、コンテンツ変更時にもページ分割や位置関係が自動調整されます。

段落に画像を追加する

from spire.doc import Document, TextWrappingStyle, HorizontalAlignment, FileFormat, ShapeHorizontalAlignment

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("\r\n\r\n画像サンプル\r\n")

# 画像を挿入
image_para = section.AddParagraph()
image_para.Format.HorizontalAlignment = HorizontalAlignment.Center
image = image_para.AppendPicture("Screen.jpg")

# 文字列の折り返し方法を設定
image.TextWrappingStyle = TextWrappingStyle.Square
# 画像サイズを設定
image.Width = 350
image.Height = 200
# 透明度を設定
image.FillTransparency(0.7)
# 水平方向の配置を設定
image.HorizontalAlignment = ShapeHorizontalAlignment.Center

document.SaveToFile("document_images.docx", FileFormat.Docx)
document.Dispose()

生成された Word 文書のプレビューです。

技術的なポイント

• AppendPicture() は画像を段落内に挿入し、テキストフローの一部として扱います
• TextWrappingStyle は、画像周囲のテキストの回り込み方法を制御します
• Width / Height は表示サイズを指定します
• FillTransparency() は画像の不透明度を設定します
• HorizontalAlignment により、段落内で画像を中央揃えできます

画像を段落に属させることで、以下の利点があります。

• 画像サイズ変更時もページ分割が自動調整される
• テキスト編集時に周囲の文章が正しく再配置される
• PDF など他形式にエクスポートしても相対位置が維持される

これらの挙動は、Word におけるインライン画像の標準的な動作と一致しています。

より高度な画像操作については、 Python で Word 文書に画像を挿入する方法 を参照してください。

5. 表の作成とデータの入力

表は、レポート、集計結果、比較データなどの構造化情報を表現する際によく使用されます。

内部的には、表は 行・セル・セル内の段落 で構成されています。

Word 文書で表を作成し、書式を設定する

from spire.doc import Document, DefaultTableStyle, FileFormat, AutoFitBehaviorType

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("\r\n\r\n表のサンプル\r\n")

# 表データを定義
table_headers = ["地域", "製品", "販売数量", "単価（円）", "売上合計（円）"]
table_data = [
    ["北", "ノートPC", 120, 95000, 11400000],
    ["北", "スマートフォン", 300, 50000, 15000000],
    ["南", "ノートPC", 80, 95000, 7600000],
    ["南", "スマートフォン", 200, 50000, 10000000],
    ["東", "ノートPC", 150, 95000, 14250000],
    ["東", "スマートフォン", 250, 50000, 12500000],
    ["西", "ノートPC", 100, 95000, 9500000],
    ["西", "スマートフォン", 220, 50000, 11000000]
]

# セクションに表を追加
table = section.AddTable()
table.ResetCells(len(table_data) + 1, len(table_headers))

# ヘッダー行を設定
for col_index, header in enumerate(table_headers):
    header_range = table.Rows[0].Cells[col_index].AddParagraph().AppendText(header)
    header_range.CharacterFormat.FontSize = 14
    header_range.CharacterFormat.Bold = True
    header_range.CharacterFormat.FontName = "Yu Gothic UI Semibold"


# データ行を設定
for row_index, row_data in enumerate(table_data):
    for col_index, cell_data in enumerate(row_data):
        data_range = table.Rows[row_index + 1].Cells[col_index] \
            .AddParagraph().AppendText(str(cell_data))
        data_range.CharacterFormat.FontSize = 12
        data_range.CharacterFormat.FontName = "Yu Gothic UI"

# 表スタイルを適用し、列幅を自動調整
table.ApplyStyle(DefaultTableStyle.ColorfulListAccent6)
table.AutoFit(AutoFitBehaviorType.AutoFitToContents)

document.SaveToFile("document_tables.docx", FileFormat.Docx)
document.Dispose()

生成された Word 文書のプレビューです。

技術的なポイント

• Section.AddTable() により、表はセクションのコンテンツフローに挿入されます
• ResetCells(行数, 列数) で表の構造を明示的に定義します
• Table.Rows[row].Cells[col] は TableCell を返します

Word の表では、各セルが独立したコンテンツコンテナとして扱われます。 セル内には複数の段落、画像、書式付きテキストを配置できるため、単純な表から複雑なレポートレイアウトまで柔軟に対応できます。

動的な表生成、セル結合、個別セルの書式設定など、より高度な操作については、 Python で Word 文書に表を挿入する方法 を参照してください。

6. ヘッダーとフッターの追加

Word におけるヘッダーとフッターは セクション単位の要素 です。 本文コンテンツとは独立しており、本文のページ分割には影響しません。

各セクションは独自のヘッダー・フッターを持つため、文書内で異なる繰り返し情報を表示できます。

セクションにヘッダーとフッターを追加する

from spire.doc import Document, FileFormat, HorizontalAlignment, FieldType, BreakType

document = Document()
section = document.AddSection()
section.AddParagraph().AppendBreak(BreakType.PageBreak)

# ヘッダーを追加
header = section.HeadersFooters.Header
header_para1 = header.AddParagraph()
header_para1.AppendText("月次売上レポート").CharacterFormat.FontSize = 12
header_para1.Format.HorizontalAlignment = HorizontalAlignment.Left

header_para2 = header.AddParagraph()
header_para2.AppendText("会社名").CharacterFormat.FontSize = 12
header_para2.Format.HorizontalAlignment = HorizontalAlignment.Right

# フッターにページ番号を追加
footer = section.HeadersFooters.Footer
footer_para = footer.AddParagraph()
footer_para.Format.HorizontalAlignment = HorizontalAlignment.Center
footer_para.AppendText("ページ ").CharacterFormat.FontSize = 12
footer_para.AppendField("PageNum", FieldType.FieldPage).CharacterFormat.FontSize = 12
footer_para.AppendText(" / ").CharacterFormat.FontSize = 12
footer_para.AppendField("NumPages", FieldType.FieldNumPages).CharacterFormat.FontSize = 12

document.SaveToFile("document_header_footer.docx", FileFormat.Docx)
document.Dispose()

生成された Word 文書のプレビューです。

技術メモ

• section.HeadersFooters.Header / Footer で、セクションのヘッダー・フッターにアクセスします
• AppendField() を使用すると、ページ番号などの動的フィールドを挿入できます

ヘッダーとフッターは、レポートタイトル、会社情報、ページ番号表示などに広く使用されます。 文書内容が変更されても自動的に更新され、Word・PDF などの出力形式とも高い互換性を保ちます。

より詳細な使用例については、 Python で Word 文書にヘッダーとフッターを挿入する方法 を参照してください。

7. セクションによるページレイアウトの制御

Spire.Doc for Python では、ページレベルのレイアウト設定はすべて Section オブジェクトを通じて管理されます。
ページサイズ、向き、余白などは、セクションが持つ PageSetup によって定義され、そのセクション内のすべてのコンテンツに適用されます。

ページサイズと向きの設定

from spire.doc import PageSize, PageOrientation

section.PageSetup.PageSize = PageSize.A4()
section.PageSetup.Orientation = PageOrientation.Portrait

技術的な解説

• PageSetup は Section が所有するレイアウト設定オブジェクトです
• PageSize はページの物理的なサイズを定義します
• Orientation により、縦向き（Portrait）または横向き（Landscape）を指定します

PageSetup の設定は、セクション全体に適用されます。 そのセクションに追加される段落、表、画像はすべて同じレイアウト規則に従います。 他のセクションには影響しないため、文書内で異なるレイアウトを共存させることが可能です。

ページ余白の設定

section.PageSetup.Margins.Top = 50
section.PageSetup.Margins.Bottom = 50
section.PageSetup.Margins.Left = 60
section.PageSetup.Margins.Right = 60

技術的な解説

• Margins はセクション内の印刷可能領域を定義します
• 余白の値はドキュメント単位で指定されます

余白はセクション単位で評価されるため、個々の段落ごとに設定する必要はありません。 なお、ヘッダーやフッターの領域には影響しません。

複数セクションを使用した異なるレイアウトの適用

文書内で異なるページレイアウトが必要な場合は、新しいセクションを追加します。

landscape_section = document.AddSection()
landscape_section.PageSetup.Orientation = PageOrientation.Landscape

技術メモ

• AddSection() は新しいセクションを作成し、文書末尾に追加します
• 各セクションは独自の PageSetup、ヘッダー、フッターを持ちます
• この呼び出し以降に追加されるコンテンツは、新しいセクションに属します

複数のセクションを活用することで、縦向きと横向きのページを混在させたり、 用途に応じたレイアウトを 1 つの Word 文書内で実現できます。

以下は、上記設定を反映した Word 文書の例です。

8. 文書プロパティとメタデータの設定

Word 文書には、表示されるコンテンツとは別に、文書レベルのメタデータ を設定できます。 これらはレイアウトや描画には影響せず、文書管理や検索に利用されます。

組み込み文書プロパティの設定

document.BuiltinDocumentProperties.Title = "月次売上レポート"
document.BuiltinDocumentProperties.Author = "データ分析システム"
document.BuiltinDocumentProperties.Company = "サンプル株式会社"

技術メモ

• BuiltinDocumentProperties を通じて、標準的な文書プロパティにアクセスできます
• Title、Author、Company などをプログラムから設定可能です

文書プロパティは、ファイルのインデックス化、検索、文書管理、監査フローなどで広く利用されます。このほかにも、Keywords、Subject、Comments、Hyperlink base などのメタデータを設定できます。また、Document.CustomDocumentProperties を使用すれば、カスタムプロパティの定義も可能です。

カスタムメタデータの管理方法については、Python で Word 文書のカスタムプロパティを管理する方法 を参照してください。

9. 保存・エクスポートとパフォーマンスの考慮点

Word 文書をメモリ上で構築した後、最終ステップとして保存またはエクスポートを行います。Spire.Doc for Python では、統一された API により、同一の文書構造を複数の出力形式に再利用できます。

複数形式での保存・エクスポート

文書は編集用の DOCX として保存できるほか、配布用途向けに他形式へエクスポートできます。

from spire.doc import FileFormat

document.SaveToFile("output.docx", FileFormat.Docx)
document.SaveToFile("output.pdf", FileFormat.PDF)
document.SaveToFile("output.html", FileFormat.Html)
document.SaveToFile("output.rtf", FileFormat.Rtf)

エクスポート時には、セクション、表、画像、ヘッダー、フッターなどの構造が保持され、 出力形式が異なっても一貫したレイアウトが維持されます。 対応フォーマットの一覧は、FileFormat 列挙型 を参照してください。

文書生成時のパフォーマンス最適化

大量または高頻度で Word 文書を生成する場合、以下の点を意識すると効率が向上します。

• テンプレートやスタイルの再利用
• 不要なセクションの作成を避ける
• すべてのコンテンツ生成後にまとめて保存する
• 保存・エクスポート後は document.Close() を明示的に呼び出してリソースを解放する

類似した文書を大量に生成する場合は、 個別にコンテンツを挿入するよりも 差し込み印刷（メールマージ） の方が効率的です。 Spire.Doc for Python には、バッチ生成向けのメールマージ機能が標準で用意されています。

詳細については、 Python で差し込み印刷を使用して Word 文書を一括生成する方法 を参照してください。

保存およびエクスポートは、Python による Word 文書生成の重要な工程です。 Spire.Doc for Python の出力機能と基本的なパフォーマンス対策を組み合わせることで、 単一ファイルからバッチ処理まで、安定した文書生成を実現できます。

10. Python で Word 文書を作成する際のよくある落とし穴

Word 文書をプログラムで生成する際によく発生する問題を以下に示します。

Word 文書をプレーンテキストとして扱ってしまう

問題点

コンテンツ量が変化すると書式やレイアウトが崩れる。

推奨事項

生テキストを直接挿入せず、セクション・段落・スタイルを正しく使用する。

書式設定をコードに直接埋め込む

問題点

レイアウト変更時に、複数箇所のコード修正が必要になる。

推奨事項

スタイルやセクション設定を用いて、書式ルールを一元管理する。

セクション境界を意識しない

問題点

余白やページ向きの変更が文書全体に影響してしまう。

推奨事項

異なるレイアウトは別セクションで明確に分離する。

11. まとめ

Python で Word 文書を作成する という作業は、単にテキストを書き込むだけではありません。.docx 文書は、セクション、段落、スタイル、埋め込み要素から構成される構造化オブジェクトです。

Spire.Doc for Python を使用し、Word のドキュメントモデルに沿ってコードを設計することで、編集可能で構造が明確な Word 文書を、要件の変化にも耐えられる形で生成できます。このアプローチは、バックエンドサービス、レポート生成パイプライン、文書自動化システムに特に適しています。

大規模文書の生成や文書変換機能を利用する場合は、ライセンス版 の使用が必要となります。