pptx

PPTX の作成、編集、分析

.pptx は XML ファイルをまとめた ZIP アーカイブです。タスクに応じて方法を選択してください。

タスク	方法
新しいデッキを作成する	pptxgenjs スクリプトを作成します。以下の注意点をご覧ください
既存のデッキを編集する、またはテンプレートから作成する	解凍 → ppt/slides/slideN.xml を編集 → 圧縮
内容を読む	markitdown deck.pptx（`` マーカーの下にスライドごとに 1 ブロック）。ビジュアルグリッド：python scripts/thumbnail.py deck.pptx

スクリプト

パスはこのスキルのディレクトリを基準とします。それ以外はすべて通常の Python、node、またはシェルです。

スクリプト	内容
scripts/thumbnail.py deck.pptx [prefix]	テンプレートのレイアウト選択に使える、全スライドのラベル付きグリッドです。.pptx のみ対応します。prefix を指定してください。既定値は thumbnails で、同じディレクトリで処理した別のデッキのグリッドを上書きします
scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml]	パッケージ内の関連情報をすべて含めて、スライド（または slideLayoutN.xml）を複製します。-o out.pptx を指定して .pptx を直接処理することもできます
scripts/clean.py unpacked/	参照されなくなったスライド、メディア、rels を削除します。<p:sldIdLst> が確定した後に実行してください
scripts/office/validate.py deck.pptx [--original src.pptx]	スキーマ、関連情報、コンテンツタイプ、グラフ、スライドをチェックします。失敗項目ごとに修正方法を示します。テンプレートから作成したデッキでは --original を指定してください。テンプレートを基準にスキーマをチェックするため、テンプレート自体の XSD エラーが自分のエラーとして扱われません
scripts/office/soffice.py --headless --convert-to pdf deck.pptx	LibreOffice のラッパーです。このサンドボックスでは soffice を直接実行するとハングします

pptxgenjs を使った作成時の注意点

pptxgenjs はプリインストールされています。先に npm install を実行せず、スクリプトを書いて require('pptxgenjs') を直接呼び出してください。その require が失敗した場合に限り、npm install pptxgenjs を実行してください。モデルは API を把握しています。以下は落とし穴です。

• スライドを追加する前に pres.layout を設定してください。 デフォルトのキャンバスは LAYOUT_16x9＝10" × 5.625" で、幅は 13.3" ではありません。範囲外の座標もそのまま書き込まれ、クランプされません。その図形はスライドに表示されないだけです。（LAYOUT_WIDE は 13.3" × 7.5" です。）
• 16 進カラーでは # を付けず、8 桁にもしないでください。 color: "FF0000" のように指定します。"#FF0000" と、16 進カラーにアルファ値を埋め込んだ値（"00000020"）は、どちらもファイルを破損させます。半透明にするには、塗りつぶしと画像には transparency: 0-100、影には opacity: 0.0-1.0 を指定してください。それぞれ、もう一方に指定しても黙って無視されます。
• pptxgenjs はオプションオブジェクトをその場で変更します（初回使用時に値を EMU に変換します）。同じ shadow／オプションオブジェクトを複数の add* 呼び出しで共有しないでください。毎回、新しいオブジェクトを作成してください。
• 影の offset は 0 以上でなければなりません。 負の値を指定するとファイルが破損します。上向きの影を付けるには、正の offset と angle: 270 を使用してください。
• letterSpacing は黙って無視されます。 正しいオプションは charSpacing です。
• リスト： 各項目に bullet: true を指定し、リテラルの • は使わないでください（箇条書き記号が二重に表示されます）。最後以外の配列項目すべてに breakLine: true を設定してください。箇条書きの段落間隔には lineSpacing ではなく paraSpaceAfter を指定してください（間隔が大きくなりすぎます）。
• 出力ファイルごとに new pptxgen() を 1 つ作成してください。 インスタンスを再利用しないでください。
• rectRadius が機能するのは ROUNDED_RECTANGLE のみです。 RECTANGLE では機能しません。
• グラデーション塗りつぶしには対応していません。 代わりに、グラデーション画像を背景として使用してください。
• テキストボックスには内部余白が組み込まれています。 テキストを図形、線、アイコンと同じ x 座標に揃える必要がある場合は、margin: 0 を設定してください。
• スピーカーノートは slide.addNotes("...") に指定します（プレーンテキストで、スライドごとに 1 回）。スライド上のテキストボックスには入れないでください。
• グラフはネイティブ形式のままにしてください。 PowerPoint でグラフ化できるものにはすべて addChart() を使用します（コンボグラフでは {type, data, options} の配列を渡します）。トレンドラインや誤差範囲など、ライブラリが公開していない PowerPoint ネイティブ機能については、追加の系列を自分で計算するか、生成された OOXML を後処理してください。レンダリング済み画像で代用しないでください。PowerPoint にネイティブ形式がないグラフの種類（サンキー、ネットワーク、コード）に限り、画像として挿入します。
• デフォルトのグラフは簡素な表示になります（タイトルなし、データラベルなし、古い配色）。showTitle と title、showValue: true と dataLabelPosition、パレットから選んだ chartColors: [...] を設定し、枠まわりの表示を控えめにしてください（catAxisLabelColor／valAxisLabelColor、valGridLine: { color, size }、catGridLine: { style: "none" }、系列が 1 つの場合は showLegend: false）。
• 積み上げ棒グラフまたは積み上げ縦棒グラフでは、dataLabelPosition に ctr、inEnd、inBase のいずれかを指定してください。 outEnd を指定するとファイルが破損します。
• secondaryValAxis／secondaryCatAxis を使用するコンボ系列では、グラフオプションに valAxes と catAxes の両方が必要で、それぞれ 2 つの項目を指定してください。 これらがないと、pptxgenjs は宣言されていない軸 ID を書き込み、PowerPoint はグラフを破棄してファイルが破損していると報告します。valAxes だけでは不十分です。
• writeFile() の後に python scripts/office/validate.py deck.pptx を実行してください。 このコマンドは、上記 2 つのグラフの不具合と、PowerPoint が受け付けないスライド XML の欠陥を報告し、それぞれの修正方法も示します。修正は生成用スクリプトで行い、パッケージ化された XML を手作業で編集しないでください。
• <p:presentation> の子要素の順序は絶対に変更しないでください。 pptxgenjs は <p:notesMasterIdLst> を <p:sldIdLst> の直後に書き込み、両方のマスターを 1 つのテーマパーツに関連付けます。PowerPoint はこの状態を問題なく読み込みますが、要素を移動すると同じデッキが開けなくなります。
• アイコン： react-icons を ReactDOMServer.renderToStaticMarkup で SVG にレンダリングし、sharp で 256px 以上にラスタライズしてから、addImage({ data: "image/png;base64," + buf.toString("base64") }) で挿入します。image/png;base64, のプレフィックスは必須です（react-icons、react、react-dom、sharp はプリインストールされています。require が失敗した場合に限り、npm install react-icons react react-dom sharp を実行してください）。

既存のデッキとテンプレートの編集

まずレイアウトを選びます：python scripts/thumbnail.py template.pptx template-thumbs を実行すると、各スライドにラベルを付けた一覧が出力され、作成されたファイル（template-thumbs.jpg、スライドが12枚を超える場合は分割された template-thumbs-N.jpg）が表示されます。2つ目の引数は必ず指定し、デッキ名にちなんだ名前を付けてください。 既定値は thumbnails なので、同じディレクトリ内で2つのデッキのサムネイルを作成すると、一覧が気づかないうちに上書きされ、最初のデッキの一覧が失われます（テンプレートの分析専用です。ビジュアル QA には画像への変換で作成するフル解像度のレンダリングが必要です。また、.pptx のみ受け付けるため、まず .potx を .pptx という名前でコピーしてください）。これを markitdown と併用して、各コンテンツセクションをテンプレートのスライドに割り当て、レイアウトに変化を持たせます。すべてのセクションを同じタイトルと箇条書きのスライドにしないでください。

python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # duplicate a slide (or slideLayoutN.xml); prints the new slide's path
# reorder / delete slides = edit <p:sldIdLst> in ppt/presentation.xml
python scripts/clean.py unpacked/                                     # after deletions: removes orphaned slides, media, rels
# edit slide content in ppt/slides/slideN.xml
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)           # zip from INSIDE the dir; rm first or deleted parts survive
python scripts/office/validate.py out.pptx --original deck.pptx

• スライドのコンテンツを編集する前に、追加・削除・並べ替えなどの構造上の作業をすべて行ってください。 add_slide.py はスライドファイルをそのままコピーするため、編集後に複製すると編集済みのコンテンツも複製されます。また、clean.py は <p:sldIdLst> にないスライドをすべて削除するため、書き込んだばかりのスライドも削除されます。
• スライドファイルを手動でコピーしないでください — add_slide.py は新しいスライドに必要な登録をすべて行い、作成した内容を報告します（Created ppt/slides/slide17.xml from slide2.xml）。ファイルを直接指定して実行することもできます：add_slide.py deck.pptx slide2.xml -o out.pptx — -o を指定しないと、入力デッキが上書きされます。 複製したスライドは、元のスライドのグラフ／SmartArt／埋め込みオブジェクトのパーツを複製せずに参照するため、一方のスライドのグラフを編集すると、もう一方にも変更が反映されます。
• python-pptx を使う場合、できないことが3つあります。スライドの複製（唯一のエントリーポイントは add_slide(layout) です）、text_frame.text = "..." による書式の保持（段落全体が書式のない単一の run にまとめられるため、代わりに run.text を割り当ててください）、テンプレートでよく使われる SVG／EMF の読み込み（add_picture は UnidentifiedImageError を発生させます）です。
• 古い形式の .ppt は、まず変換する必要があります：python scripts/office/soffice.py --headless --convert-to pptx file.ppt。.potx テンプレートは展開と再パッケージが同じ手順で行えます — 出力でも .potx 拡張子を維持してください。
• テンプレートのアイコンや画像を再利用するには、それを含むスライドまたはレイアウトを複製してください。

テンプレートに内容を入力するときは、次の点に注意してください：

• XML 変換をスクリプトで行う場合は、defusedxml.minidom で解析してください。OOXML を xml.etree.ElementTree で往復処理すると、名前空間のプレフィックスが書き換えられ、デッキが破損します。
• テンプレートの枠 ≠ ソース項目。 テンプレートにチームメンバーが4人表示されていて、実際は3人の場合、4人目のテキストだけでなく、グループ全体（画像＋テキストボックス）を削除してください。その後、QA で不要なビジュアルが残っていないか確認します。
• リスト項目ごとに <a:p> を1つ使います。複数の項目を1つの段落にまとめないでください。間隔を維持するには、兄弟要素の <a:pPr> をコピーし、タイトル、セクション見出し、インラインラベル（Status:、Owner:）の <a:rPr> に b="1" を指定します。
• 箇条書きの設定はレイアウトから継承させます。上書きする場合に限り <a:buChar>、<a:buAutoNum>（番号付き）、または <a:buNone> を追加してください。テキスト内に文字として • を入力してはいけません。
• 先頭または末尾にスペースがあるテキストでは、<a:t> に xml:space="preserve" を指定する必要があります。

デザインのアイデア

退屈なスライドは作らないでください。 白い背景に単純な箇条書きを並べても、見る人の印象には残りません。各スライドについて、以下のリストからアイデアを検討してください。

開始する前に

• 大胆で、内容に合ったカラーパレットを選びます：パレットは、このトピックのためにデザインされたと感じられるものにします。色をまったく別のプレゼンテーションに入れ替えても「問題なく使える」なら、選択が十分に具体的ではありません。
• 均等さよりも、色の主役を決めます：1色を視覚的な重みの60～70％にし、補助色を1～2色、鋭いアクセントカラーを1色加えます。すべての色を同じ比重にするのは避けます。
• 明暗のコントラストをつけます：タイトルと結論のスライドは暗い背景、本文のスライドは明るい背景にします（「サンドイッチ」構成）。または、プレミアムな印象を目指して、全体を暗い色調に統一します。
• ビジュアルモチーフを決めます：特徴的な要素を1つ選び、繰り返し使います。たとえば、角丸の画像フレームや、色付きの円に入れたアイコンなどです。すべてのスライドで一貫して使います。カラーバーやアクセントのストライプをモチーフにしないでください（「避ける項目」を参照）。

カラーパレット

トピックに合う色を選びます。一般的な青を安易に選ばないでください。以下のパレットを参考にしてください。

テーマ	メインカラー	サブカラー	アクセントカラー
ミッドナイト・エグゼクティブ	1E2761（ネイビー）	CADCFC（アイスブルー）	FFFFFF（白）
フォレスト＆モス	2C5F2D（フォレストグリーン）	97BC62（モスグリーン）	F5F5F5（クリーム）
コーラル・エナジー	F96167（コーラル）	F9E795（ゴールド）	2F3C7E（ネイビー）
ウォーム・テラコッタ	B85042（テラコッタ）	E7E8D1（サンド）	A7BEAE（セージ）
オーシャン・グラデーション	065A82（ディープブルー）	1C7293（ティール）	21295C（ミッドナイト）
チャコール・ミニマル	36454F（チャコール）	F2F2F2（オフホワイト）	212121（黒）
ティール・トラスト	028090（ティール）	00A896（シーフォーム）	02C39A（ミント）
ベリー＆クリーム	6D2E46（ベリー）	A26769（ダスティローズ）	ECE2D0（クリーム）
セージ・カーム	84B59F（セージ）	69A297（ユーカリ）	50808E（スレート）
チェリー・ボールド	990011（チェリー）	FCF6F5（オフホワイト）	2F3C7E（ネイビー）

各スライドについて

すべてのスライドにビジュアル要素が必要です。画像、グラフ、アイコン、図形などを使います。テキストだけのスライドは印象に残りません。

レイアウトの選択肢：

• 2列（左にテキスト、右にイラスト）
• アイコン＋テキストの行（色付きの円に入れたアイコン、太字の見出し、その下に説明）
• 2×2または2×3のグリッド（片側に画像、もう片側にコンテンツブロックのグリッド）
• 片側全体に画像を配置し、その上にコンテンツを重ねるレイアウト

データの表示：

• 大きな数値のコールアウト（60～72ptの大きな数値と、その下の小さなラベル）
• 比較用の列（導入前／導入後、メリット／デメリット、選択肢の並列比較）
• タイムラインまたはプロセスフロー（番号付きの手順、矢印）

ビジュアルの仕上げ：

• セクション見出しの横に、小さな色付きの円に入れたアイコンを配置します
• 重要な統計やタグラインには、アクセントとしてイタリック体のテキストを使います

タイポグラフィ

.pptx に指定したフォント名は、この環境ではなくユーザーの PowerPoint で描画されます。 ビジュアル QA の描画には LibreOffice を使用しますが、LibreOffice にないフォントは代替フォントに置き換えられます。また、フォントによっては代替フォントの幅が異なるため、QA プレビューでは実際のスライドとは異なり、テキストがはみ出したり、収まったりすることがあります。QA の信頼性を保つため、次の点に注意してください。

• 安全なフォント（QA で実際の幅どおりに描画され、Office にも付属）：Arial、Calibri、Cambria、Times New Roman、Courier New、Bookman Old Style、Century Schoolbook。本文や、文字の収まりが重要な箇所にはこれらを使用してください。
• QA 上のリスクなしで個性を出せる見出し：安全なフォントのセリフ体見出し（Cambria、Bookman Old Style、Century Schoolbook）と、安全なフォントのサンセリフ体本文（Calibri または Arial）を組み合わせます。文字のはみ出しを確実に確認しながら、視覚的なコントラストを付けられます。
• ユーザーが安全なフォント一覧にないフォント（例：Georgia、Trebuchet MS）を指定した場合：指定された箇所にはそのフォントを使用しますが、コンテナーには約10％の余裕を持たせ、それらの要素の文字の収まりについては QA を信頼しないでください。そのフォントのプレビューはあくまで概算です。ユーザーから指定がない場合は、本文には安全なフォント一覧のフォントを優先してください。
• QA で信頼できないフォント（代替フォントの幅が異なるため、はみ出しの確認が不正確になる場合がある）：Georgia、Trebuchet MS、Impact、Arial Black、Garamond、Consolas、Palatino Linotype。Calibri Light の代替は環境によって異なるため、QA で信頼できないフォントとして扱ってください。タイトルやアクセントには余裕を持たせて使用できますが、文字の収まりの確認には使わないでください。
• Aptos をデフォルトにしないでください。Office の2023年以降のデフォルトフォントは、この環境にメトリック互換の代替フォントがなく、古い Office には含まれていないため、どちらの環境でも信頼できません。

要素	サイズ
スライドタイトル	36〜44pt、太字
セクション見出し	20〜24pt、太字
本文	14〜16pt
キャプション	10〜12pt、控えめな色

間隔

• 余白は最低0.5インチ
• コンテンツブロック間は0.3〜0.5インチ
• 余白を十分に取り、隅々まで埋めないでください

避けること（よくあるミス）

• 同じレイアウトを繰り返さない — スライドごとにカラム、カード、コールアウトに変化を付けてください
• 本文を中央揃えにしない — 段落とリストは左揃えにし、中央揃えはタイトルだけにしてください
• サイズのコントラストを弱めない — タイトルは本文の14〜16ptより目立つよう、36pt以上にしてください
• 青をデフォルトにしない — トピックに合った色を選んでください
• 間隔をランダムに混在させない — 0.3インチまたは0.5インチの間隔を選び、一貫して使用してください
• 1枚だけをスタイリングして、残りをそのままにしない — 全体に徹底するか、すべてをシンプルにしてください
• テキストだけのスライドを作らない — 画像、アイコン、グラフ、その他のビジュアル要素を追加し、タイトルと箇条書きだけの構成は避けてください
• テキストボックスのパディングを忘れない — テキストの端に合わせて行や図形を配置する場合は、テキストボックスの margin: 0 を設定するか、パディングを考慮して図形の位置をずらしてください
• コントラストの低い要素を使わない — アイコンもテキストも背景に対して十分なコントラストが必要です。明るい背景に明るいテキスト、暗い背景に暗いテキストを置くのは避けてください
• タイトルの下にアクセントラインを絶対に使わない — AI 生成スライドの典型的な特徴です。代わりに余白や背景色を使ってください
• 装飾的なカラーバーやアクセントストライプを絶対に追加しない — これには、スライド幅いっぱいのヘッダー／フッターのバー、スライドの片側に沿って縦に伸びるサイドバーストライプ、カードやコンテンツブロックの端に沿った細いアクセントストライプ、長方形の「片側だけの枠線」が含まれます。これらは AI 生成の埋め草のように見えます。カードを際立たせるなら、端のストライプではなく、控えめな背景色、ドロップシャドウ、アイコンを使ってください。
• クリーム色やベージュ色の背景をデフォルトにしない — 背景の指定がない場合は、白（FFFFFF）またはユーザーのブランドカラーを使用し、F5F5DC、FAF0E6、FAEBD7、FFF8E1 のような暖色系のニュートラルカラーをデフォルトで使うのは避けてください
• 図形からはみ出すテキストをそのままにしない — テキストが収まらない場合は、フォントサイズを小さくする、スライドを分割する、またはコンテナーを大きくしてください。内容が切れたり、範囲からはみ出したりしたままにしないでください

QA（必須）

最初のレンダリングでは、通常、重なり、はみ出し、位置ずれなどの問題がいくつか見つかります。問題を見つけて修正し、変更したスライドだけを再レンダリングして終了してください。

コンテンツの QA

markitdown output.pptx

コンテンツの欠落、誤字、順序の誤りがないか確認してください。

テンプレートを使用する場合は、置き換え忘れたプレースホルダーテキストがないか確認してください。

markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert|this.*(page|slide).*layout"

grep で結果が返された場合は、成功を宣言する前に修正してください。

ファイルの QA（必須）

python scripts/office/validate.py output.pptx                      # built from scratch
python scripts/office/validate.py output.pptx --original src.pptx  # built from a template

デッキがテンプレートから作成された場合は、必ず --original を渡してください。 テンプレート自体に XSD が拒否する部分が含まれている可能性があるため、オプションなしで実行すると、自分が引き起こしていないエラーが報告されることがあります。また、その中に本当のリグレッションが隠れてしまうこともあります。--original を指定すると、テンプレートを基準にスキーマとスライドをチェックし、もともと存在していたエラーを抑制します。構造チェック（リレーションシップ、コンテンツタイプ、グラフ）は --original の影響を受けず、テンプレート由来の問題も同様に報告されるため、それぞれ個別に確認してください。

pptxgenjs は、PowerPoint では開けないグラフ XML を出力しますが、それ以外のすべてのツールでは受け入れられます。python-pptx ではこれらのデッキを開け、LibreOffice ではレンダリングでき、XSD も合格します。各エラーには修正方法が記載されています。ジェネレーターを修正して再ビルドしてください。

視覚的な QA

スライドを画像に変換し（画像への変換を参照）、すべての画像を確認してください。生成コードを見続けていると、実際にレンダリングされたものではなく、期待しているものが見えてしまいがちです。そのため、画像を新鮮な目で確認してください（利用できる場合は、サブエージェントを使うと効果的です）。ユーザーから見える不具合として、次の点を確認してください。

• テキストのはみ出し、またはボックスやスライドの境界でのテキストの切れ — まずこれを確認してください。 これは最もよくある不具合で、必ずユーザーの目に触れます。（Typography の説明にあるとおり、プレビューアーが不安定にレンダリングするフォントでは、プレビューはおおよその表示です。見た目上収まっているかどうかではなく、確保しておいた約 10% の余裕を基準にしてください。）
• 要素の重なり（テキストが図形に重なる、線が文字を横切る、要素が積み重なるなど）
• 出典の引用やフッターが、その上のコンテンツとぶつかっている
• 要素同士が近すぎる（間隔が 0.3" 未満）、またはカードやセクションがほぼ接触している
• 間隔が不均等（ある場所に大きな空白があり、別の場所は窮屈になっている）
• スライドの端からの余白が不十分（0.5" 未満）
• 列や類似する要素の位置が揃っていない
• コントラストの低いテキスト（例：クリーム色の背景に薄いグレーのテキスト）
• テキストの置き換え後にテンプレートの装飾の位置がずれている（例：1 行のタイトル向けに配置されたタイトル下線に対して、置き換え後のタイトルが 2 行に折り返されている）
• コントラストの低いアイコン（例：暗い背景に暗いアイコンがあり、対比する円がない）
• テキストボックスの幅が狭すぎて、過剰に折り返されている
• プレースホルダーコンテンツの置き換え忘れ

画像への変換

視覚的に確認できるよう、プレゼンテーションを個別のスライド画像に変換してください。

python scripts/office/soffice.py --headless --convert-to pdf output.pptx
rm -f slide-*.jpg
pdftoppm -jpeg -r 150 output.pdf slide
ls -1 "$PWD"/slide-*.jpg

上記で出力された絶対パスを、そのまま表示ツールに渡してください。 rm は前回の実行で残った古い画像を削除します。pdftoppm はページ数に応じてゼロ埋めします。10 ページ未満のデッキでは slide-1.jpg、10～99 ページでは slide-01.jpg、100 ページ以上では slide-001.jpg です。

修正後は、上記の 4 つのコマンドをすべて再実行してください。 pdftoppm に変更を反映するには、編集した .pptx から PDF を再生成する必要があります。

依存関係

pptxgenjs（npm、インストール済み — require('pptxgenjs') が失敗する場合のみインストール） · markitdown[pptx]、Pillow、defusedxml、lxml（pip — テキストダンプ、サムネイル、クリーンアップ、検証に使用） · LibreOffice（soffice、サンドボックス環境向けに scripts/office/soffice.py で自動設定） · pdftoppm（Poppler）