Word アドインで Office Open XML を使用するタイミングと方法を理解する

  • [アーティクル]

提供元:Stephanie Krieger, Microsoft Corporation | Juan Balmori Labra, Microsoft Corporation

Wordで実行する Office アドインを構築している場合は、Office JavaScript API (Office.js) にドキュメント コンテンツの読み取りと書き込み用に複数の形式が用意されていることがわかっている場合があります。 そのような書式は強制タイプと呼ばれ、プレーン テキスト、表、HTML、Office Open XML が含まれています。

リッチ コンテンツを追加するためのオプション

それでは、イメージ、書式設定された表、グラフ、あるいは書式設定だけされたテキストをドキュメントに追加する必要があるとき、何を選択しますか。

  1. JavaScript API をWordします。 WordApi 要件セットで使用できる API から始めて、必要なものを提供するかどうかを確認します。 例については、「 Insert formatted text code snippet」を参照してください。 このスニペットやその他のスニペットは、Wordの Script Lab アドインで試すことができます。 Script Lab の詳細については、「Script Lab を使用して Office JavaScript API を探索する」を参照してください。

  2. HTML 強制。 API がまだ使用できない場合は、画像などの一部の種類のリッチ コンテンツを挿入するために HTML を使用できます。 シナリオによっては、コンテンツで使用できる書式設定および配置に関する制限など、HTML 強制型変換にとって不利な点が存在する場合があります。

  3. Office Open XML。 Office Open XML は、Word 文書 (.docx、.dotx など) が記述される言語であるため、Word 文書にユーザーが追加できるコンテンツであれば、ユーザーにとって適用可能なほぼすべてのタイプの書式設定で、事実上あらゆるタイプのコンテンツを挿入できます。 処理する Office Open XML マークアップを判別するのは、想像しているよりも簡単です。

注:

Office Open XML は PowerPoint と Excel (ならびに、Office 2013 以降、Visio) ドキュメントの言語です。 ただし、現在のところは、Word 用に作成された Office アドインでのみ、Office Open XML としてコンテンツを型強制できます。 完全な言語リファレンス ドキュメントなど、Office Open XML の詳細については、「 関連項目」セクションを参照 してください。

コンパニオン コード サンプルをダウンロードする

次の例のいずれかをWordに挿入するために必要な Office Open XML マークアップと Office.js コードを含む、コード サンプル Open XML を Word アドインに読み込んで書き込みます。

コンテンツ タイプについて学習する

まず、Office Open XML 強制を使用して挿入できるコンテンツ タイプをいくつか見てみましょう。

この記事全体を通じて、コンテンツ タイプとリッチ コンテンツという用語は、Word ドキュメントに挿入できるリッチ コンテンツの種類を指します。

図 1. 直接の書式設定が適用されたテキスト

直接書式設定が適用されたテキスト。

直接書式設定を使用して、ユーザーのドキュメント内の既存の書式に関係なく、テキストの外観を正確に指定します。

図 2. スタイルを使用して書式設定されたテキスト

段落スタイルで書式設定されたテキスト。

スタイルを使用して、挿入したテキストの外観をユーザーのドキュメントと自動的に調整します。

図 3. 単純な画像

サンプル ロゴ。

Office でサポートされているイメージ形式を挿入する場合も同じ方法を使用します。

図 4. 画像のスタイルと効果を使用して書式設定された画像

Word 内の書式設定された画像。

高品質の書式設定と効果をイメージに追加するとき、必要なマークアップは予想よりずっと少なくなります。

図 5. コンテンツ コントロール

境界線コンテンツ コントロール内のテキスト。

アドインでコンテンツ コントロールを使用して、選択範囲ではなく、指定された (バインドされた) 場所にコンテンツを追加します。

図 6. ワードアートの書式設定を含むテキスト ボックス

ワードアート テキスト効果で書式設定されたテキスト。

Word では、テキスト ボックス (図参照) 内のテキストに、または通常の本文テキストにテキスト効果を利用できます。

図 7. 図形

Wordの描画図形。

テキストと書式設定の効果の有無にかかわらず、組み込みまたはカスタムの描画図形を挿入します。

図 8. 直接書式が設定されたテーブル

Word 内の書式設定されたテーブル。

テキストの書式設定、罫線、網かけ、セルのサイズ設定、または必要な任意のテーブルの書式設定を含めます。

図 9. テーブル スタイルを使用して書式設定されたテーブル

Wordのテーブル スタイルで書式設定されたテーブル。

テキストに段落スタイルを使用するのと同じくらい簡単に、組み込みまたはカスタムの表スタイルを使用します。

図 10. SmartArt ダイアグラム

Word 内の動的な SmartArt 図。

Office には、さまざまな SmartArt ダイアグラム レイアウトが用意されています (また、Office Open XML を使用して独自の図を作成することもできます)。

図 11. グラフ

Word 内のグラフ。

Excel グラフは、Word ドキュメントにライブ グラフとして挿入できます。つまり、アドインで使用してWordすることもできます。 前の例でわかるように、Office Open XML 強制を使用して、基本的にユーザーが独自のドキュメントに挿入できるあらゆる種類のコンテンツを挿入できます。 Office Open XML マークアップを取得するには、2 つの簡単な方法が必要です。 それ以外の場合は空白のWordドキュメントにリッチ コンテンツを追加し、ファイルWord XML ドキュメント形式で保存するか、getSelectedDataAsync メソッドを使用してテスト アドインを使用してマークアップを取得します。 いずれの方法でも基本的には同じ結果が得られます。

ヒント

Office Open XML ドキュメントは、実際にはドキュメントの内容を表すファイルの圧縮パッケージです。 ファイルを Word XML ドキュメント形式で保存すると、Office Open XML パッケージ全体が 1 つの XML ファイルにフラット化されます。これは、Office Open XML マークアップを取得するときにもgetSelectedDataAsync使用できます。

Wordから XML 形式にファイルを保存する場合は、[名前を付けて保存] ダイアログ ボックスの [名前を付けて保存] ボックスの一覧の下に、.xml フォーマット ファイルの 2 つのオプションがあることに注意してください。 Word 2003 オプションではなく、XML ドキュメントWord選択してください。

Word-Add-in-Get-Set-EditOpen-XML という名前のコード サンプルをダウンロードします。これは、マークアップを取得してテストするためのツールとして使用できます。

これですべてでしょうか。 そうではありません。 多くのシナリオについては、先ほどのメソッドのいずれかを使用して表示される、完全な、圧縮 Office Open XML 結果を使用できるし、それは機能するでしょう。 良いニュースは、おそらくそのマークアップのほとんどは必要ないということです。

Office Open XML マークアップを初めて見る多くのアドイン開発者の 1 人である場合は、最も単純なコンテンツに対して取得する大量のマークアップを理解しようとすると、圧倒的に感じられるかもしれませんが、そうする必要はありません。

このトピックでは、Office アドイン開発者コミュニティから寄せられるいくつかの一般的なシナリオを使用して、アドインで使用する Office Open XML を簡略化する手法について説明します。 前に示した一部の種類のコンテンツのマークアップと、Office Open XML ペイロードを最小限に抑えるために必要な情報について説明します。 また、作業中の選択範囲でリッチ コンテンツをドキュメントに挿入するために必要なコードと、Office Open XML と bindings オブジェクトを使用して、指定した場所のコンテンツを追加または置換する方法についても説明します。

Office Open XML ドキュメント パッケージを調べる

getSelectedDataAsync を使用して、選択したコンテンツの Office Open XML を取得する場合 (または、ドキュメントWord XML ドキュメント形式で保存する場合)、取得される内容は、選択したコンテンツを記述するマークアップだけではありません。これは、多くのオプションと設定を持つドキュメント全体であり、ほぼ確実に必要ありません。 事実、作業ウィンドウ アドインを含むドキュメントからそのメソッドを使用すると、取得するマークアップにはその作業ウィンドウ アプリまでもが含まれています。

単純な Word ドキュメント パッケージであっても、実際のコンテンツだけではなく、ドキュメント プロパティ、スタイル、テーマ (書式設定)、Web 設定、フォントなどが含まれています。

たとえば、先ほど図 1 で表示されていたように、直接書式が設定されたテキストの 1 段落だけを挿入するとします。 を使用して getSelectedDataAsync書式設定されたテキストの Office Open XML を取得すると、大量のマークアップが表示されます。 このマークアップには、ドキュメント全体を表すパッケージ要素が含まれています。これには、図 13 に示すように、複数のパーツ (一般にドキュメント パーツと呼ばれるか、Office Open XML ではパッケージ パーツと呼ばれます) が含まれています。 各パーツは、パッケージ内の個別のファイルを表します。

メモ帳などのテキスト エディターで、Office Open XML マークアップを編集することができます。 Visual Studio で開く場合は、[詳細>書式ドキュメントの編集]> (Ctrl + K、Ctrl + D) を使用してパッケージの書式を設定し、編集を容易にします。 次に図 12 で示すように、ドキュメントの一部またはセクションを折りたたんだり、展開したりして、Office Open XML パッケージのコンテンツをより簡単に確認したり、編集したりすることができます。 各ドキュメントの部分は pkg:part タグから始まります。

図 12. Visual Studio で簡単に編集するためのパッケージ パーツの折りたたみと展開

Visual Studio のパッケージ パーツの Office Open XML コード スニペット。

図 13. 基本的な Word Office Open XML ドキュメント パッケージに含まれるパーツ

パッケージ部分の Office Open XML コード スニペット。

これだけたくさんマークアップが存在するのに、書式設定されたテキスト例を挿入するために実際に必要な要素は .rels パーツと document.xml パーツだけであることを知ったら驚かれることでしょう。

ヒント

パッケージ タグの上にある 2 行のマークアップ (バージョンと Office プログラム ID の XML 宣言) は、Office Open XML 強制型を使用する場合に想定されるため、それらを含める必要はありません。 Keep them if you want to open your edited markup as a Word document to test it.

このトピックの冒頭に示すその他の種類のコンテンツの中には、(図 13 を超えて) 追加の部分も必要です。このトピックの後半で説明します。 一方、図 13 に示すほとんどの部分は、Wordドキュメント パッケージのマークアップに表示されるため、これらの各パーツの目的と必要なタイミングの概要を次に示します。

  • パッケージ タグ内の最初の部分は .rels ファイルで、パッケージの最上位部分 (通常はドキュメント プロパティ、サムネイル (存在する場合)、ドキュメント本文メイン) 間のリレーションシップを定義します。 この部分のコンテンツの一部は、ドキュメント パッケージへの メインドキュメント パーツ (コンテンツが存在する場所) の関係を定義する必要があるため、マークアップでは常に必要です。

  • document.xml (本文) パーツに必要な追加パーツが存在する場合、そのリレーションシップが document.xml.rels パーツにより定義されます。

    重要

    パッケージの .rels ファイル (top-level .rels、document.xml.rels、および特定のタイプのコンテンツで遭遇するその他のファイル) はガイドとして使用できる非常に重要なツールであり、Office Open XML パッケージをすばやく編集できます。 これを行う方法の詳細については、このトピックで後述する 「独自のマークアップの作成: ベスト プラクティス 」を参照してください。

  • document.xml パーツはドキュメントの本文のコンテンツです。 コンテンツが表示される部分であるため、もちろんこのパーツの要素は必要です。 しかしながら、このパーツに表示されるすべてが必要なわけではありません。 これについては後で詳しく説明します。

  • 多くの部分は、Office Open XML 強制を使用してドキュメントにコンテンツを挿入するときに Set メソッドによって自動的に無視されるため、削除することもできます。 これには、theme1.xml ファイル (ドキュメントの書式設定テーマ)、ドキュメント プロパティ パーツ (コア、アドイン、サムネイル)、設定ファイル (設定、webSettings、fontTable を含む) が含まれます。

  • 図 1 の例では、テキストの書式設定が直接適用されています (つまり、各フォントおよび段落の書式設定が個別に適用されます)。 ただし、先の図 2 のように、スタイルを使用する場合 (たとえば、変換先ドキュメントの見出し 1 スタイルの書式設定をテキストに自動的に適用する場合)、styles.xml パーツとそのリレーションシップ定義が必要になります。 詳細については、「 追加の Office Open XML パーツを使用するオブジェクトを追加する」セクションを参照してください。

選択範囲にドキュメント コンテンツを挿入する

それでは、図 1 の書式設定テキスト例に必要な最小 Office Open XML マークアップと、ドキュメントでアクティブになっている選択箇所に挿入するために必要な JavaScript について見てみましょう。

単純化された Office Open XML マークアップ

ここで示す Office Open XML の例は、前のセクションで説明したように編集され、必要なドキュメント パーツだけを残し、それらの各部分に必要な要素のみを残しました。 このトピックの次のセクションでは、マークアップを自分で編集する方法 (および、ここに残っている部分についてもう少し説明します) について説明します。

<pkg:package xmlns:pkg="http://schemas.microsoft.com/office/2006/xmlPackage">
  <pkg:part pkg:name="/_rels/.rels" pkg:contentType="application/vnd.openxmlformats-package.relationships+xml" pkg:padding="512">
    <pkg:xmlData>
      <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
        <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
      </Relationships>
    </pkg:xmlData>
  </pkg:part>
  <pkg:part pkg:name="/word/document.xml" pkg:contentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml">
    <pkg:xmlData>
      <w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" >
        <w:body>
          <w:p>
            <w:pPr>
              <w:spacing w:before="360" w:after="0" w:line="480" w:lineRule="auto"/>
              <w:rPr>
                <w:color w:val="70AD47" w:themeColor="accent6"/>
                <w:sz w:val="28"/>
              </w:rPr>
            </w:pPr>
            <w:r>
              <w:rPr>
                <w:color w:val="70AD47" w:themeColor="accent6"/>
                <w:sz w:val="28"/>
              </w:rPr>
              <w:t>This text has formatting directly applied to achieve its font size, color, line spacing, and paragraph spacing.</w:t>
            </w:r>
          </w:p>
        </w:body>
      </w:document>
    </pkg:xmlData>
  </pkg:part>
</pkg:package>

注:

ここに示すマークアップを XML ファイルに追加し、バージョンと mso アプリケーションの XML 宣言タグ (図 13) をファイルの先頭に追加すると、そのファイルを Word ドキュメントとして Word で開くことができます。 または、これらのタグがない場合でも、Wordで [ファイルを開く] を>使用して開くことができます。 Word ドキュメントであることを示す設定を削除したため、Wordのタイトル バーに互換モードWord表示されます。 このマークアップを既存のWordドキュメントに追加しているため、コンテンツにはまったく影響しません。

setSelectedDataAsync を使用するための JavaScript

前の Office Open XML をソリューションからアクセスできる XML ファイルとして保存したら、次の関数を使用して、Office Open XML 強制を使用してドキュメント内の書式設定されたテキスト コンテンツを設定します。

次の関数では、最後の行以外はすべて、関数の末尾にある setSelectedDataAsync メソッド呼び出しで使用するために保存されたマークアップを取得するために使用されます。 setSelectedDataASync では、挿入するコンテンツと強制型を指定する必要があります。

ソリューションに保存した XML ファイルの名前とパスに、 yourXMLfilename を置き換えます。 ソリューションに XML ファイルを含める場所や、それらをコードで参照する方法がわからない場合は、Word アドイン のコード サンプルで Open XML を読み込んで書き込む方法に関するページを参照してください。その例と、マークアップと JavaScript の実際の例を次に示します。

function writeContent() {
    const myOOXMLRequest = new XMLHttpRequest();
    let myXML;
    myOOXMLRequest.open('GET', 'yourXMLfilename', false);
    myOOXMLRequest.send();
    if (myOOXMLRequest.status === 200) {
        myXML = myOOXMLRequest.responseText;
    }
    Office.context.document.setSelectedDataAsync(myXML, { coercionType: 'ooxml' });
}

独自のマークアップを作成する: ベスト プラクティス

それでは、先ほどの書式設定テキスト例を挿入するために必要なマークアップについて詳しく見てみましょう。

この例では、.rels と document.xml 以外のすべてのドキュメント パーツをパッケージから削除することから始めます。 次に、これら 2 つの必要な部分を編集して、さらに簡略化します。

重要

.rels パーツは、パッケージに含めるパーツをすばやく判断し、完全に削除できるパーツ (つまり、コンテンツに関係ない、またはコンテンツに参照されないパーツ) を判断するためのマップとして使用します。 すべてのドキュメント パーツについて、パッケージにリレーションシップを定義する必要があることと、それらのリレーションシップが .rels ファイルに表示されることに注意してください。 そのため、.rels、document.xml.rels、コンテンツ固有 .rels ファイルのいずれかにそれらのすべてが一覧表示される必要があります。

次のマークアップは、編集前に必要な .rels パーツを示しています。 アドインとコア ドキュメント プロパティ パーツとサムネイル パーツを削除するため、これらのリレーションシップも .rels から削除する必要があります。 document.xml のリレーションシップのみが残ることに注意してください (次の例で関係 ID が "rID1" のもの)。

<pkg:part pkg:name="/_rels/.rels" pkg:contentType="application/vnd.openxmlformats-package.relationships+xml" pkg:padding="512">
  <pkg:xmlData>
    <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
      <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/>
      <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail" Target="docProps/thumbnail.emf"/>
      <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
      <Relationship Id="rId4" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties" Target="docProps/app.xml"/>
    </Relationships>
  </pkg:xmlData>
</pkg:part>

パッケージから完全に削除するパーツのリレーションシップ (つまり、Relationship タグ) を削除します。 対応するリレーションシップなしでパーツを追加するか、パーツを除外してもパッケージにそのリレーションシップを残した場合、エラーが発生します。

次のマークアップは、書式設定されたテキスト コンテンツのサンプルを含む、編集前の document.xml パーツを示しています。

<pkg:part pkg:name="/word/document.xml" pkg:contentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml">
    <pkg:xmlData>
      <w:document mc:Ignorable="w14 w15 wp14" xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape">
        <w:body>
          <w:p>
            <w:pPr>
              <w:spacing w:before="360" w:after="0" w:line="480" w:lineRule="auto"/>
              <w:rPr>
                <w:color w:val="70AD47" w:themeColor="accent6"/>
                <w:sz w:val="28"/>
              </w:rPr>
            </w:pPr>
            <w:r>
              <w:rPr>
                <w:color w:val="70AD47" w:themeColor="accent6"/>
                <w:sz w:val="28"/>
              </w:rPr>
              <w:t>This text has formatting directly applied to achieve its font size, color, line spacing, and paragraph spacing.</w:t>
            </w:r>
            <w:bookmarkStart w:id="0" w:name="_GoBack"/>
            <w:bookmarkEnd w:id="0"/>
          </w:p>
          <w:p/>
          <w:sectPr>
            <w:pgSz w:w="12240" w:h="15840"/>
            <w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720" w:gutter="0"/>
            <w:cols w:space="720"/>
          </w:sectPr>
        </w:body>
      </w:document>
    </pkg:xmlData>
</pkg:part>

document.xml はコンテンツを配置する主要なドキュメント パーツであるため、その部分について簡単に説明します。 (この一覧に続く図 14 は、ここで説明する主要なコンテンツと書式設定タグの一部が、Word ドキュメントに表示されているものとどのように関連しているかを示す視覚的な参照を提供します)。

  • 冒頭の w:document タグには、いくつかの名前空間 (xmlns) のリストが含まれます。 これらの名前空間の多くは特定のタイプのコンテンツを参照するため、お使いのコンテンツに関連する場合にのみ必要です。

    ドキュメント パーツ全体のタグのプレフィックスが名前空間を参照していることに注意してください。 この例では、document.xml 部分全体のタグで使用されるプレフィックスは w: のみであるため、開く w:document タグに残す必要がある名前空間は xmlns:w のみです。

    ヒント

    Visual Studio でマークアップを編集している場合は、任意の部分で名前空間を削除した後、その部分のすべてのタグを調びます。 If you've removed a namespace that's required for your markup, you'll see a red squiggly underline on the relevant prefix for affected tags. If you remove the xmlns:mc namespace, you must also remove the mc:Ignorable attribute that precedes the namespace listings.

  • 冒頭の body タグの内部に、段落タグ (w:p) が表示され、この例のサンプル コンテンツが表示されます。

  • w:pPr タグには、段落の前後の空間、段落の位置合わせ、字下げなど、直接適用される段落書式設定のプロパティが含まれます (直接書式設定は、スタイルの一部としてではなく、コンテンツに個別に適用する属性を参照します)。 またこのタグには、段落全体に適用されるフォントの直接書式設定が、サンプルに設定されたフォントの色とサイズを含む、入れ子になった w:rPr (run プロパティ) タグ内に含まれます。

    Office Open XML マークアップのフォント サイズやその他の書式設定Word実際のサイズの 2 倍に見える場合があります。 That's because paragraph and line spacing, as well some section formatting properties shown in the preceding markup, are specified in twips (one-twentieth of a point). Depending on the types of content you work with in Office Open XML, you may see several additional units of measure, including English Metric Units (914,400 EMUs to an inch), which are used for some Office Art (drawingML) values and 100,000 times actual value, which is used in both drawingML and PowerPoint markup. PowerPoint also expresses some values as 100 times actual and Excel commonly uses actual values.

  • 段落内では、like プロパティを持つすべてのコンテンツが実行 ( w:r ) に含まれます(例: サンプル テキストの場合)。 書式設定またはコンテンツ タイプに変更が加わるたびに、新しい実行が開始されます。 (つまり、サンプル テキスト内の 1 つの単語が太字の場合は、それ自体の実行に分割されます)。この例では、コンテンツには 1 つのテキスト実行だけが含まれています。

    このサンプルに含まれる書式設定はフォントの書式設定 (つまり、わずか 1 文字に適用される書式設定) であるため、個別実行のプロパティにも表示されることに注意してください。

  • また、非表示の "_GoBack" ブックマーク (w:bookmarkStart と w:bookmarkEnd) のタグが、既定でWordドキュメントに表示されます。 マークアップからいつでも、GoBack ブックマークの開始タグと終了タグを削除することができます。

  • ドキュメント本体の最後の部分は w:sectPr タグまたはセクション プロパティです。 このタグには余白やページ方向などの設定が含まれます。 setSelectedDataAsync を利用して挿入したコンテンツは、既定でターゲット ドキュメントのアクティブなセクションのプロパティを獲得します。 そのため、コンテンツにセクション区切り (その場合は複数の w:sectPr タグが 表示される) が含まれている場合を除き、このタグを削除できます。

図 14. document.xml の一般的なタグが、Word ドキュメントのコンテンツとレイアウトにどのように関連しているか

Word 文書内の Office Open XML 要素。

ヒント

作成するマークアップでは、このトピックで使用されている例では見られない w:rsid 文字を含む複数のタグに別の属性が表示される場合があります。 These are revision identifiers. They're used in Word for the Combine Documents feature and they're on by default. You'll never need them in markup you're inserting with your add-in and turning them off makes for much cleaner markup. 既存の RSID タグを簡単に削除するか、(次の手順で説明するように) 機能を無効にして、新しいコンテンツのマークアップに追加されないようにすることができます。

Word の共同作成機能 (他の人と同時にドキュメントを編集する機能など) を使用する場合、アドインのマークアップ生成を完了したときに、機能を再度有効にする必要があることに注意してください。

将来作成するドキュメントのために Word の RSID 属性をオフにするには、次のように操作します。

  1. Word で、[ファイル] を選択し、[オプション] を選択します。
  2. [Word オプション] ダイアログ ボックスで、[セキュリティ センター] を選択し、[セキュリティ センターの設定] を選択します。
  3. [セキュリティ センター] ダイアログ ボックスで、[プライバシー オプション] を選択し、[組み込みの精度を向上させるためランダムな番号を保存する] という設定を無効にします。 この設定は、新しいバージョンのWordでは使用できない場合があることに注意してください。

既存のドキュメントから RSID タグを削除するには、Office Open XML でドキュメントを開いた状態で次のショートカットを試してください。

  1. ドキュメントの本文にカーソルを置き、Ctrl キー + Home キーを押してドキュメントの先頭に移動します。
  2. キーボードで、Space キー、Del キー、Space キーを押します。 次にドキュメントを保存します。

このパッケージからマークアップの大部分を削除すると、前のセクションに示すように、サンプルに挿入する必要がある最小限のマークアップが残ります。

異なるコンテンツ タイプに同じ Office Open XML 構造を使用する

一部のタイプのリッチ コンテンツでは、前の例で見たような、コンテンツ コントロール、Office 描画図形、テキスト ボックス、表 (スタイルが表に適用されない限り) など、.rels および document.xml コンポーネントのみが必要です。 実際は、編集済みの同じパッケージ パーツを再利用したり、document.xml の body コンテンツを自分のコンテンツのマークアップと交換したりします。

図 5 から図 8 で前に示した各コンテンツ タイプの例について Office Open XML マークアップをチェックするには、概要セクションで参照されているWord アドイン コード サンプルの Open XML の読み込みと書き込みを調べてみます。

次に進む前に、これらのコンテンツ タイプの相違点と、必要な部分を交換する方法を確認してください。

Wordでの drawingML マークアップ (Office グラフィックス) について

図形またはテキスト ボックスのマークアップが予想よりもはるかに複雑に見える場合は、その理由があります。 Office 2007 のリリースでは、Office Open XML 形式の導入と、PowerPoint と Excel が完全に採用した新しい Office グラフィックス エンジンの導入を確認しました。 2007 リリースでは、Wordそのグラフィックス エンジンの一部のみを組み込み、更新された Excel グラフ エンジン、SmartArt グラフィックス、および高度な画像ツールを採用しました。 図形とテキスト ボックスの場合、Word 2007 では引き続きレガシ描画オブジェクト (VML) が使用されます。 2010 年のリリースでは、更新された図形と描画ツールを組み込むため、グラフィックス エンジンで追加の手順をWordしました。

通常、Word アドインのコード サンプルの Open XML の読み込みと書き込みに含まれる図形とテキスト ボックスの例に関するページでわかるように、フォールバック マークアップを削除できます。 Wordドキュメントの保存時に、不足しているフォールバック マークアップが図形に自動的に追加されます。 ただし、すべてのユーザー シナリオが確実にサポートされるようにフォールバック マークアップをそのままにしておいても、まったく問題はありません。

コンテンツに含まれる描画オブジェクトをグループ化している場合、追加の (明らかに繰り返しである) マークアップが表示されますが、これはそのままにしておく必要があります。 オブジェクトがグループに追加されると、描画図形のマークアップの部分が重複します。

重要

テキスト ボックスと描画図形を操作するときは、名前空間を慎重に確認してから document.xml から削除してください (あるいは、別のオブジェクト タイプからマークアップを再利用する場合、document.xml から以前に削除した名前空間が必要であれば、それを戻します)。 既定で document.xml に含まれる名前空間の重要な部分は、図画オブジェクトの要件のためにあります。

グラフィックの位置に関する注記

コード サンプルでは、Word アドインと Word-Add-in-Get-Set-EditOpen-XML で Open XML を読み込んで書き込みます。テキスト ボックスと図形は、さまざまな種類のテキスト 折り返し設定と配置設定を使用して設定されます。 (また、これらのコード サンプルの画像の例は、テキストの書式設定に沿ってを使用して設定されていることに注意してください。これは、テキスト ベースラインにグラフィック オブジェクトを配置します)。

これらのコード サンプルの図形は右と下のページ余白との関連で位置付けられます。 相対的位置付けにより、簡単にユーザーの不明なドキュメント設定を調整でき (ユーザーの余白に合わせて調整されるため)、紙のサイズ、方向、余白の設定によってぎこちなく見えることもなくなります。 グラフィック オブジェクトを挿入するときに相対的位置付け設定を維持するには、位置付け (Word のアンカー) が保存される段落マーク (w:p) を維持する必要があります。 独自の段落マークを追加するのではなく、既存の段落マークにコンテンツを挿入する場合、同じ初期ビジュアルを維持できても、ユーザーのレイアウトに合わせて自動的に調整する位置付けを有効にする多くのタイプの相対参照が失われる可能性があります。

コンテンツ コントロールを操作する

コンテンツ コントロールは Word の重要な機能であり、さまざまな方法で Word 用アドインの機能を大幅に強化します。たとえば、選択範囲だけではなく、ドキュメントの指定の場所にコンテンツを挿入できます。

Word では、図 15 のように、コンテンツ コントロールはリボンの [開発] タブにあります。

図 15. Wordの [開発者] タブの [コントロール] グループ

Word のリボン上のコンテンツ コントロール グループ。

Word のコンテンツ コントロールの種類には、リッチ テキスト、プレーン テキスト、ピクチャ、構成要素ギャラリー、チェック ボックス、ドロップダウン リスト、コンボ ボックス、日付の選択、繰り返しセクションがあります。

  • 図 15 にある [プロパティ] コマンドを使用し、コントロールのタイトルを編集したり、コントロール コンテナーを非表示にするなど、設定を追加します。

  • [デザイン モード] を有効化し、コントロールのプレースホルダー コンテンツを編集します。

アドインがWord テンプレートで動作する場合は、そのテンプレートにコントロールを含め、コンテンツの動作を強化できます。 また、Word ドキュメント内の XML データ バインドを使用して、コンテンツ コントロールをドキュメント プロパティなどのデータにバインドして、フォームの完了や同様のタスクを簡単に行うこともできます。 ([挿入] タブの [クイック パーツ] のWordで、組み込みのドキュメント プロパティに既にバインドされているコントロールを検索します)。

アドインでコンテンツ コントロールを使用すると、異なるタイプのバインドを使用してアドインで可能なオプションを大幅に拡張できます。 アドインの中からコンテンツ コントロールをバインドし、アクティブな選択範囲ではなく、バインドにコンテンツを記述できます。

Word の XML データ バインドと、アドインを介してコントロールにバインドする機能を混同しないでください。 これらはまったく別の機能です。 ただし、OOXML 強制型変換を利用してアドイン経由で挿入したコンテンツに指定のコンテンツ コントロールを追加し、アドインのコードを使用してこれらのコントロールにバインドすることができます。

また、XML データ バインディングと Office.js の両方がアプリ内のカスタム XML パーツと対話できるため、これらの強力なツールを統合できます。 Office JavaScript API でカスタム XML パーツを操作する方法については、このトピックの 「関連項目」セクションを参照 してください。

Word アドインでのバインドの操作については、このトピックの次のセクションで説明します。 まず、アドインを使用してバインドできるリッチ テキスト コンテンツ コントロールを挿入するために必要な Office Open XML の例を見てみましょう。

重要

リッチ テキスト コントロールは、アドイン内からコンテンツ コントロールにバインドできる唯一のタイプのコンテンツ コントロールです。

<pkg:package xmlns:pkg="http://schemas.microsoft.com/office/2006/xmlPackage">
  <pkg:part pkg:name="/_rels/.rels" pkg:contentType="application/vnd.openxmlformats-package.relationships+xml" pkg:padding="512">
    <pkg:xmlData>
      <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
        <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
      </Relationships>
    </pkg:xmlData>
  </pkg:part>
  <pkg:part pkg:name="/word/document.xml" pkg:contentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml">
    <pkg:xmlData>
      <w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" >
        <w:body>
          <w:p/>
          <w:sdt>
              <w:sdtPr>
                <w:alias w:val="MyContentControlTitle"/>
                <w:id w:val="1382295294"/>
                <w15:appearance w15:val="hidden"/>
                <w:showingPlcHdr/>
              </w:sdtPr>
              <w:sdtContent>
                <w:p>
                  <w:r>
                  <w:t>[This text is inside a content control that has its container hidden. You can bind to a content control to add or interact with content at a specified location in the document.]</w:t>
                </w:r>
                </w:p>
              </w:sdtContent>
            </w:sdt>
          </w:body>
      </w:document>
    </pkg:xmlData>
  </pkg:part>
 </pkg:package>

すでに説明したように、コンテンツ コンテキストは書式設定されたテキストと同様、追加のドキュメント パーツを必要としません。そのため、編集された .rels および document.xml パーツのみがここに含まれています。

document.xml 本文内に表示される w:sdt タグはコンテンツ コントロールを表します。 コンテンツ コントロールの Office Open XML マークアップを生成すると、タグおよびドキュメント パーツ プロパティなど、いくつかの属性がこの例から削除されていることに気付くでしょう。 次の内容を含む、不可欠な (そして、いくつかのベスト プラクティスの) 要素のみが維持されています。

  • エイリアスは、Wordの [コンテンツ コントロールのプロパティ] ダイアログ ボックスの title プロパティです。 アドイン内からコントロールにバインドする場合、これは必須のプロパティです (アイテムの名前を表します)。

  • 一意の id は必須のプロパティです。 アドイン内からコントロールにバインドする場合、この ID は、該当する名前付きコンテンツ コントロールを識別するためにドキュメントのバインド機能で使用されるプロパティです。

  • 外観属性は、コントロール コンテナーを非表示にして、よりクリーンな外観を実現するために使用されます。 この機能は、w15 名前空間の使用に従って、2013 年Wordに導入されました。 このプロパティが使用されるため、w15 名前空間が document.xml パーツの先頭で維持されます。

  • showingPlcHdr 属性は省略可能な設定であり、コントロール内に含める既定のコンテンツ (この例ではテキスト) をプレースホルダー コンテンツとして設定します。 そのため、ユーザーがコントロール領域をクリックするか、タップすると、ユーザーが変更できる編集可能コンテンツのように動作する代わりに、コンテンツ全体が選択されます。

  • sdt タグの前にある空の段落マーク ( w:p/ ) は、コンテンツ コントロールを追加するために必要ありません (また、Word ドキュメント内のコントロールの上に垂直スペースを追加します)、コントロールが独自の段落に配置されます。 コントロールに追加されるコンテンツのタイプと書式設定によっては、これが重要になる場合があります。

  • コントロールにバインドする場合、バインドで複数の段落から構成されるリッチ コンテンツを受け入れるために、コントロールの既定のコンテンツ (sdtContent タグの内容) に少なくとも 1 つの完全な段落を含める必要があります。

このサンプルの w:sdt タグから削除されたドキュメント パーツ属性は、プレースホルダー コンテンツ情報を保存できるパッケージの別個のパーツ (Office Open XML パッケージの用語集ディレクトリに置かれているパーツ) を参照するために、コンテンツ コントロールに表示される場合があります。 ドキュメント パーツは Office Open XML パッケージ内の XML パーツ (つまりファイル) に使用される用語ですが、sdt プロパティで使用されるドキュメント パーツという用語は、文書パーツとドキュメント プロパティクイック パーツ (組み込みの XML データバインド コントロールなど) を含む一部のコンテンツ タイプを記述するために使用される、Wordの同じ用語を指します。 Office Open XML パッケージの用語集ディレクトリの下にパーツが表示される場合、挿入するコンテンツにこれらの機能が含まれるのであれば、そのパーツは維持する必要がある可能性があります。 アドインからのバインドに使用する一般的なコンテンツ コントロールの場合は、必須ではありません。 パッケージから用語集パーツを削除する場合、w:sdt タグからもドキュメント パーツ属性を削除する必要があることを覚えておいてください。

次のセクションでは、Word アドインでバインドを作成し、使用する方法について考察します。

指定された場所にコンテンツを挿入する

既に、Word ドキュメント内のアクティブな選択範囲にコンテンツを挿入する方法について説明しました。 ドキュメントの名前付きコンテンツ コントロールにバインドする場合、同じコンテンツ タイプをそのコントロールに挿入できます。

それでは、どのような場合にこの手法を使用するのでしょうか。

  • データベースからドキュメントの一部を設定するなど、テンプレート内の指定した場所にあるコンテンツを追加または置換する必要がある場合。

  • ユーザーにデザイン要素オプションを提供するなど、アクティブな選択で挿入するコンテンツを置き換えるオプションが必要な場合。

  • ユーザーがドキュメントに追加した情報に基づいて作業ウィンドウ内のフィールドを設定するなど、アドインで使用するためにアクセスできるデータをドキュメントに追加する場合。

コード サンプル Word-Add-in-JavaScript-AddPopulateBindings をダウンロードします。このサンプルは、コンテンツ コントロールを挿入し、それにバインドする方法と、バインドにデータを入力する方法の実際の例を提供します。

名前付きコンテンツ コントロールを追加し、それにバインドする

続く JavaScript を確認し、これらの要件について考察してください。

  • すでに説明したように、Word アドインからコントロールにバインドするには、リッチ テキスト コンテンツ コントロールを使用する必要があります。

  • コンテンツ コントロールには名前が必要です (これは、[コンテンツ コントロールのプロパティ] ダイアログ ボックスの [タイトル ] フィールドで、Office Open XML マークアップの Alias タグに対応します)。 これにより、コードはバインドを配置する場所を識別します。

  • 複数の名前付きコントロールを用意し、必要に応じてそれらにバインドできます。 一意のコンテンツ コントロール名、一意のコンテンツ コントロール ID、一意のバインド ID を使用します。

function addAndBindControl() {
    Office.context.document.bindings.addFromNamedItemAsync("MyContentControlTitle", "text", { id: 'myBinding' }, function (result) {
        if (result.status == "failed") {
            if (result.error.message == "The named item does not exist.")
                const myOOXMLRequest = new XMLHttpRequest();
                let myXML;
                myOOXMLRequest.open('GET', '../../Snippets_BindAndPopulate/ContentControl.xml', false);
                myOOXMLRequest.send();
                if (myOOXMLRequest.status === 200) {
                    myXML = myOOXMLRequest.responseText;
                }
                Office.context.document.setSelectedDataAsync(myXML, { coercionType: 'ooxml' }, function (result) {
                    Office.context.document.bindings.addFromNamedItemAsync("MyContentControlTitle", "text", { id: 'myBinding' });
                });
        }
    });
}

ここに示すコードでは、次の手順を実行します。

  • addFromNamedItemAsync を使用して、名前付きコンテンツ コントロールにバインドしようとします。

    コードの実行時に、名前付きコントロールがドキュメントに既に存在する可能性があるアドインのシナリオが考えられる場合は、まずこの手順を実行します。 たとえば、コントロールが事前に配置されているアドインで動作するように設計されているテンプレートにアドインが挿入されて、テンプレート共に保存される場合は、これを実行します。 また、アドインによって前に配置されたコントロールにバインドする必要がある場合にも、これを行う必要があります。

  • メソッドの addFromNamedItemAsync 最初の呼び出しのコールバックは、結果の状態をチェックして、名前付き項目がドキュメントに存在しないためにバインドが失敗したかどうかを確認します (つまり、この例では MyContentControlTitle という名前のコンテンツ コントロール)。 その場合、コードはアクティブな選択ポイント (を使用) にコントロールを setSelectedDataAsync追加し、それにバインドします。

前のコードで説明したように、コンテンツ コントロールの名前を使用し、バインドを作成する場所が決まります。 ただし、Office Open XML マークアップでは、コードにより、コンテンツ コントロールの名前と ID 属性の両方を使用し、ドキュメントにバインドが追加されます。

コードを実行した後、アドインがバインドを作成したドキュメントのマークアップを調べると、各バインドに対して 2 つの部分が表示されます。 バインドが追加されたコンテンツ コントロールのマークアップ (document.xml) には、 w15:webExtensionLinked/という属性が表示されます。

In the document part named webExtensions1.xml, you'll see a list of the bindings you've created. それぞれは、次のような該当するコントロールのバインド ID と ID 属性を使用して識別されます。 ここで、appref 属性はコンテンツ コントロール ID です。 we:binding id="myBinding" type="text" appref="1382295294"/。

重要

バインディングを操作する予定の時点で、バインドを追加する必要があります。 Don't include the markup for the binding in the Office Open XML for inserting the content control because the process of inserting that markup will strip the binding.

バインドにデータを入力する

バインドにコンテンツを書き込むためのコードは、選択範囲にコンテンツを書き込むためのコードに似ています。

function populateBinding(filename) {
  const myOOXMLRequest = new XMLHttpRequest();
  let myXML;
  myOOXMLRequest.open('GET', filename, false);
  myOOXMLRequest.send();
  if (myOOXMLRequest.status === 200) {
      myXML = myOOXMLRequest.responseText;
  }
  Office.select("bindings#myBinding").setDataAsync(myXML, { coercionType: 'ooxml' });
}

と setSelectedDataAsync同様に、挿入するコンテンツと強制型を指定します。 バインドに書き込むための唯一の追加要件は、ID によりバインドを識別することです。 このコードで使用されるバインド ID (bindings#myBinding) が、前の関数でバインドが作成されたときに確立されたバインド ID (myBinding) にどのように対応しているかに注目してください。

ヒント

前のコードは、最初にバインディング内のコンテンツを設定または置き換える場合に必要なすべてです。 When you insert a new piece of content at a bound location, the existing content in that binding is automatically replaced. Check out an example of this in the previously-referenced code sample Word-Add-in-JavaScript-AddPopulateBindings, which provides two separate content samples that you can use interchangeably to populate the same binding.

追加の Office Open XML パーツを使用するオブジェクトを追加する

多くのタイプのコンテンツで、Office Open XML パッケージの追加ドキュメント パーツが必要です。つまり、別のパーツの情報を参照するか、1 つまたは複数のパーツに格納され、document.xml で参照されるコンテンツ自体を参照します。

たとえば、次の内容を考慮します。

  • 書式設定にスタイルを使用するコンテンツ (先ほどの図 2 のスタイル設定されたテキストまたは図 9 のスタイル設定された表など) には styles.xml パーツが必要です。

  • 画像 (図 3 および図 4 のような画像など) では、1 つ (2 つの場合もある) の追加パーツにバイナリ画像が含まれます。

  • SmartArt 図 (図 10 のような図) では、レイアウトとコンテンツを表現するために、複数の追加パーツが必要です。

  • グラフ (図 11 のようなグラフなど) では、独自のリレーションシップ (.rels) パーツを含む、複数の追加パーツが必要です。

前述のコード サンプル「Load and write Open XML in your Word アドイン」では、これらのすべてのコンテンツ タイプのマークアップの編集された例を確認できます。 バインディングを使用して現在の選択範囲にコンテンツを挿入したり、指定した場所にコンテンツを書き込んだりする場合は、前に表示した (および参照したコード サンプルで提供された) ものと同じ JavaScript コードを使用してこれらのコンテンツ タイプをすべて挿入できます。

document.xml で参照されている追加のパーツを保持する場合は、styles.xml やイメージ ファイルなど、保持する該当するパーツの document.xml.rels とリレーションシップ定義を保持する必要があります。

サンプルを調べる前に、これらの各コンテンツ タイプを操作するためのヒントをいくつか見てみましょう。

スタイルを使用する

段落スタイルまたは表スタイルを使用してコンテンツの書式設定を行う場合、前の例で見たマークアップを直接書式設定したテキストで編集するのと同じ方法が適用されます。 ただし、段落スタイルを操作するためのマークアップはかなり簡単なので、ここで説明する例です。

段落スタイルを使用してコンテンツのマークアップを編集する

次のマークアップは、図 2 で示した、スタイル設定されたテキスト例の本文コンテンツを表します。

<w:body>
  <w:p>
    <w:pPr>
      <w:pStyle w:val="Heading1"/>
    </w:pPr>
    <w:r>
      <w:t>This text is formatted using the Heading 1 paragraph style.</w:t>
    </w:r>
  </w:p>
</w:body>

ご覧のように、スタイルを使用する場合は、document.xml の書式設定されたテキストのマークアップが大幅に簡単になります。スタイルには、個別に参照する必要がある段落とフォントの書式設定がすべて含まれているためです。 However, as explained earlier, you might want to use styles or direct formatting for different purposes: use direct formatting to specify the appearance of your text regardless of the formatting in the user's document; use a paragraph style (particularly a built-in paragraph style name, such as Heading 1 shown here) to have the text formatting automatically coordinate with the user's document.

スタイルの使用は、挿入するコンテンツのマークアップを読み取って理解することがいかに重要であるかを示す良い例です。これは、別のドキュメント パーツがここで参照されていることが明確ではないのでです。 このマークアップにスタイル定義を含め、styles.xml パーツを含めない場合、そのスタイルがユーザーのドキュメントで使用されているかどうかに関係なく、document.xml のスタイル情報は無視されます。

ただし、styles.xml part をよく見ると、この長いマークアップのほんの一部だけがアドインで使用するマークアップを編集するときに必要であることがわかります。

  • styles.xml パーツには既定で複数の名前空間が含まれます。 コンテンツに必要なスタイル情報のみを維持するのであれば、ほとんどの場合、xmlns:w 名前空間のみを維持するだけで問題ありません。

  • スタイル パーツの上部にある w:docDefaults タグ コンテンツは、マークアップがアドイン経由で挿入されたときは無視されます。これは削除してもかまいません。

  • styles.xml パーツのマークアップの最大の部分は、docDefaults の後に表示される w:latentStyles タグ用です。これにより、使用可能なすべてのスタイルの情報 (スタイル ウィンドウの外観属性やスタイル ギャラリーなど) が提供されます。 この情報は、アドインを介してコンテンツを挿入するときにも無視されるため、削除できます。

  • 潜在的なスタイル情報を追うと、マークアップの生成元になったドキュメントで使用されている各スタイルの定義がわかります。 これには、ドキュメントを新規作成するときに使用される既定のスタイルが含まれ、お使いのコンテンツには関係ない場合があります。 お使いのコンテンツで使用されないスタイルの定義は削除できます。

    組み込みの各見出しスタイルには、同じ見出し形式の文字スタイル バージョンである Char スタイルが関連付けられています。 Unless you've applied the heading style as a character style, you can remove it. If the style is used as a character style, it appears in document.xml in a run properties tag ( w:rPr ) rather than a paragraph properties ( w:pPr ) tag. This should only be the case if you've applied the style to just part of a paragraph, but it can occur inadvertently if the style was incorrectly applied.

  • コンテンツに組み込みスタイルを使用している場合、完全な定義を含める必要はありません。 挿入時に型強制 Office Open XML でコンテンツにスタイルを適用する目的で、スタイル名、スタイル ID、そして少なくとも 1 つの書式設定属性だけを含める必要があります。

    ただし、完全なスタイル定義を含めるのがベスト プラクティスです (組み込みスタイルに対して既定の場合であっても)。 スタイルがターゲット ドキュメントで既に使用されている場合は、styles.xml の内容に関係なく、コンテンツはスタイルの常駐定義を使用します。 スタイルがターゲット ドキュメントでまだ使用されていない場合は、コンテンツはマークアップで指定されているスタイル定義を使用します。

そのため、たとえば、図 2 に示すサンプル テキストの styles.xml 部分から保持する必要があるコンテンツは、見出し 1 スタイルを使用して書式設定されているだけです。

注:

この例では、見出し 1 スタイルの完全な Word 定義が維持されています。

<pkg:part pkg:name="/word/styles.xml" pkg:contentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml">
  <pkg:xmlData>
    <w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" >
      <w:style w:type="paragraph" w:styleId="Heading1">
        <w:name w:val="heading 1"/>
        <w:basedOn w:val="Normal"/>
        <w:next w:val="Normal"/>
        <w:link w:val="Heading1Char"/>
        <w:uiPriority w:val="9"/>
        <w:qFormat/>
        <w:pPr>
          <w:keepNext/>
          <w:keepLines/>
          <w:spacing w:before="240" w:after="0" w:line="259" w:lineRule="auto"/>
          <w:outlineLvl w:val="0"/>
        </w:pPr>
        <w:rPr>
          <w:rFonts w:asciiTheme="majorHAnsi" w:eastAsiaTheme="majorEastAsia" w:hAnsiTheme="majorHAnsi" w:cstheme="majorBidi"/>
          <w:color w:val="2E74B5" w:themeColor="accent1" w:themeShade="BF"/>
          <w:sz w:val="32"/>
          <w:szCs w:val="32"/>
        </w:rPr>
      </w:style>
    </w:styles>
  </pkg:xmlData>
</pkg:part>

テーブル スタイルを使用してコンテンツのマークアップを編集する

コンテンツでテーブル スタイルを使用する場合は、段落スタイルの操作に関する説明と同じ styles.xml の相対部分が必要です。 つまり、コンテンツで使用しているスタイルの情報のみを保持する必要があり、名前、ID、および少なくとも 1 つの書式設定属性を含める必要がありますが、潜在的なすべてのユーザー シナリオに対処するための完全なスタイル定義を含めることをお勧めします。

ただし、document.xml の表と styles.xml の表スタイル定義の両方のマークアップを見ると、段落スタイルを使用するときより、はるかに多くのマークアップがあるのがわかります。

  • document.xml では、書式設定はスタイルに含まれている場合でも、セルごとに適用されます。 表スタイルを使用してマークアップの量が減ることはありません。 コンテンツに表スタイルを使用すると、複数の表を簡単に更新し、簡単に調整できるメリットがあります。

  • styles.xml では、たった 1 つの表スタイルでもかなりの量のマークアップがあります。これは、表全体、見出し行、奇数と偶数の縞付き行および列 (別個)、最初の列など、表スタイルに表領域別のさまざまな書式設定属性が含まれるためです。

画像を操作する

イメージのマークアップには、画像を記述するためのバイナリ データを含む少なくとも 1 つの部分への参照が含まれています。 複雑な画像の場合、これは数百ページのマークアップであり、編集できません。 バイナリ部分に触れる必要はないので、Visual Studio などの構造化エディターを使用している場合は単純に折りたたんで、パッケージの残りの部分を簡単に確認および編集できます。

図 3 で前に示した単純な画像のマークアップ例をチェックした場合は、前に参照したコード サンプルの Word アドインで Open XML を読み込んで書き込みます。document.xml の画像のマークアップには、サイズと位置情報、およびバイナリ イメージ データを含む部分へのリレーションシップ参照が含まれていることがわかります。 その参照は、次のように、 a:blip タグに含まれています。

<a:blip r:embed="rId4" cstate="print">

リレーションシップ参照 ( r:embed="rID4" ) が明示的に使用され、イメージをレンダリングするには関連パーツが必要であるため、Office Open XML パッケージにバイナリ データを含めないと、エラーが発生します。 これは、前に説明した styles.xml とは異なります。これは、リレーションシップが明示的に参照されておらず、リレーションシップがコンテンツ自体の一部ではなく、コンテンツ (書式設定) に属性を提供する部分であるため、省略してもエラーはスローされません。

マークアップを確認するときは、a:blip タグで使用される追加の名前空間に注目してください。 document.xml では、xlmns:a 名前空間 (メイン drawingML 名前空間) が、document.xml パーツの先頭ではなく、drawingML 参照の使用の開始時に動的に配置されていることがわかります。 However, the relationships namespace (r) must be retained where it appears at the start of document.xml. Check your picture markup for additional namespace requirements. Remember that you don't have to memorize which types of content require what namespaces, you can easily tell by reviewing the prefixes of the tags throughout document.xml.

追加の画像パーツと書式設定について理解する

図 4 の (ピクチャのスタイル設定に加えて) 調整済みの明るさやコントラストの設定を使用する画像のように、画像に Office ピクチャ書式設定効果を使用する場合、画像データの HD 書式コピーの二次バイナリ データ パーツが必要になる場合があります。 この追加 HD 書式は、レイヤー効果を設定するために必要であり、その書式への参照は document.xml に次のように表示されます。

<a14:imgLayer r:embed="rId5">

Word アドイン のコード サンプルの「Open XML を読み込んで書き込む」の図 4 (レイヤー効果を使用する) に示されている書式設定された画像に必要なマークアップを参照してください。

SmartArt ダイアグラムの操作

SmartArt 図には 4 つの関連パーツがありますが、常に必要なのは 2 つだけです。 SmartArt マークアップの例は、Word アドインのコード サンプルの Open XML の読み込みと書き込みで確認できます。 まず、各パーツの簡単な説明と、それらが必要な理由と不要な理由を見てみましょう。

ヒント

コンテンツに複数の図が含まれている場合は、ここに示されているファイル名の '1' を置き換えて、連続して番号が付けられます。

  • layout1.xml: このパーツは必須です。 これには、レイアウトの外観と機能のマークアップ定義が含まれます。

  • data1.xml: このパーツは必須です。 これには、図のインスタンスで使用されるデータが含まれます。

  • drawing1.xml: この部分は必ずしも必要ではありませんが、個々の図形を直接書式設定するなど、図のインスタンス内の要素にカスタム書式を適用する場合は、保持する必要がある場合があります。

  • colors1.xml: この部分は必要ありません。 色のスタイル定義が含まれますが、図の色は既定で、Office Open XML マークアップを保存する前に Word の SmartArt ツールの [デザイン] タブから適用する SmartArt 色スタイルに基づき、ターゲット ドキュメントのアクティブな書式設定テーマの色に合わせて調整されます。

  • quickStyles1.xml: この部分は必要ありません。 ターゲット ドキュメントで利用できる、適用済みの SmartArt スタイルの定義を図が取得するため色パーツと同様に、このパーツは削除できます(つまり、パーツはターゲット ドキュメントの書式設定テーマに合わせて自動的に調整されます)。

SmartArt layout1.xml ファイルは、マークアップをさらにトリミングできる可能性がある場所の良い例ですが、余分な時間を費やすことはできません (パッケージ全体に対してこのような少量のマークアップが削除されるため)。 マークアップで削除できる最後の行まで削除する場合、dgm:sampData タグとそのコンテンツを削除します。 このサンプル データにより、SmartArt スタイル ギャラリーにおける図のサムネイル プレビューの表示が定義されます。 ただし、それを省略した場合、既定のサンプル データが使用されます。

document.xml の SmartArt ダイアグラムのマークアップには、レイアウト、データ、色、クイック スタイルの各部分へのリレーションシップ ID 参照が含まれていることに注意してください。 これらのパーツとそのリレーションシップ定義を削除するときに、色とスタイルの部分に対する document.xml の参照を削除できますが (これらのリレーションシップを削除する場合は、確実にこれを行うことをお勧めします)。ただし、図面をドキュメントに挿入する必要がないため、そのままにしてもエラーは発生しません。 これらの参照は、 dgm:relIds タグの document.xml にあります。 この手順を実行するかどうかに関係なく、必要なレイアウトとデータ パーツのリレーションシップ ID 参照を保持します。

グラフを操作する

SmartArt 図と同様に、グラフにはいくつかの追加のパーツが含まれます。 ただし、グラフの設定は SmartArt とは少し異なり、グラフには独自のリレーションシップ ファイルがあります。 グラフに必要なドキュメント パーツとリムーバブル ドキュメント パーツの説明を次に示します。

ヒント

SmartArt 図と同様に、コンテンツに複数のグラフが含まれている場合は、ここに一覧表示されているファイル名の '1' を置き換えて、連続して番号が付けられます。

  • document.xml.rels には、グラフ (chart1.xml) を表すデータを含む必須パーツへの参照があります。

  • また、chart1.xml.rels など、Office Open XML パッケージのグラフ別のリレーションシップ ファイルがあります。

    chart1.xml.rels では 3 つのファイルが参照されますが、1 つだけが必須です。 この中にバイナリ Excel ワークブック データ (必須) と、削除できる色およびスタイル パーツ (colors1.xml と styles1.xml) があります。

Wordでネイティブに作成および編集できるグラフは Excel グラフであり、そのデータは Office Open XML パッケージにバイナリ データとして埋め込まれた Excel ワークシートに保持されます。 画像のバイナリ データ パーツと同様に、この Excel バイナリ データは必要ですが、この部分では編集する必要はありません。 そのため、エディターでパーツを折りたたむだけで、Office Open XML パッケージの残りの部分を調べるためにすべてを手動でスクロールする必要がなくなります。

ただし、SmartArt と同様に、色およびスタイル パーツを削除できます。 で使用できるグラフスタイルと色スタイルを使用してグラフの書式を設定した場合、グラフは目的のドキュメントに挿入されたときに自動的に適用される書式設定を受け取ります。

図 11 に示すグラフ例については、Word アドインのコード サンプルの Open XML の読み込みと書き込みの編集済みマークアップを参照してください。

作業ウィンドウ アドインで使用する Office Open XML を編集する

マークアップのコンテンツの識別方法と編集方法はすでに確認しました。 ドキュメント用に生成された大規模な Office Open XML パッケージを見ると、タスクが難しいと思われる場合は、そのパッケージをすばやく編集するのに役立つ推奨手順の概要を次に示します。

パッケージのすべての .rels パーツをマップとして使用し、削除できるドキュメント パーツをすばやく確認できることを覚えておいてください。

  1. Visual Studio でフラット化された XML ファイルを開き、Ctrl + K キー、Ctrl + D キーを押してファイルの書式を設定します。 次に、左側の折りたたみ/展開ボタンを使用して、削除する必要があることがわかっている部分を折りたたみます。 また、必要な長い部分を折りたたむことができますが、編集する必要がない (画像ファイルの base64 バイナリ データなど) ため、マークアップをより迅速かつ視覚的にスキャンしやすくなります。

  2. ドキュメント パッケージのいくつかのパーツは、アドインに使用する Office Open XML マークアップを準備しているときにほとんどの場合は削除できます。 まずは、そのようなパーツ (およびそれらに関連付けられているリレーションシップの定義) を削除すれば、パッケージのサイズをすぐに大幅に減らすことができます。 そのようなパーツには、theme1、fontTable、settings、webSettings、サムネイル、コア プロパティ ファイルとアドイン プロパティ ファイルの両方、任意の taskpane、webExtension パーツなどがあります。

  3. 必要のない脚注、ヘッダー、フッターなど、自分のコンテンツに関連しないパーツを削除できます。 ここでも、関連付けられているリレーションシップを必ず削除してください。

  4. document.xml.rels パーツをレビューし、画像ファイル、スタイル パーツ、SmartArt 図パーツなど、そのパーツで参照されるファイルが自分のコンテンツに必要かどうかを確認します。 自分のコンテンツに必要のないパーツがあれば、そのリレーションシップを削除し、関連パーツも削除されていることを確認します。 自分のコンテンツには document.xml.rels で参照されるドキュメント パーツがいずれも必要でない場合、そのファイルを削除することもできます。

  5. 自分のコンテンツに .rels パーツ (chart#.xml.rels など) を追加している場合、それをレビューし、そこで参照されているその他のパーツで、削除できるパーツがないかどうかを確認し (グラフのクイック スタイルなど)、そのファイルからのリレーションシップと関連パーツの両方を削除します。

  6. document.xml を編集して、パーツで参照されていない名前空間、セクション区切りが含まれていない場合のセクション プロパティ、挿入するコンテンツに関連しないマークアップを削除します。 図形またはテキスト ボックスを挿入する場合、広範囲のフォールバック マークアップを削除することもできます。

  7. スタイル パーツなど、コンテンツに影響を与えずに重要なマークアップを削除できることがわかっている必須の追加パーツを編集します。

前の 7 つの手順を終えると、コンテンツにもよりますが、削除できるマークアップの約 90 から 100% を削除していることになります。 ほとんどの場合、削除作業はこれで終了でしょう。

ここで終了するか、削除できる最後の行まで見つけるためにコンテンツをさらに深く調査するかにかかわらず、前に参照したコード サンプル Word-Add-in-Get-Set-EditOpen-XML をスクラッチ パッドとして使用し、編集したマークアップをすばやくかつ簡単にテストできることを覚えておいてください。

ヒント

開発中に既存のソリューションで Office Open XML スニペットを更新する場合は、ソリューションをもう一度実行する前に一時インターネット ファイルをクリアして、コードで使用される Office Open XML を更新します。 Markup that's included in your solution in XML files is cached on your computer. You can, of course, clear temporary Internet files from your default web browser. インターネット オプションにアクセスし、Visual Studio 2019 内からこれらの設定を削除するには、[ デバッグ ] メニューの [オプション] を選択します。 次に、[環境] で、[Web ブラウザー] を選択し、[Internet Explorer オプション] を選択します。

テンプレートとスタンドアロンの両方で使用するアドインを作成する

このトピックでは、アドインで Office Open XML を使用して実行できる操作の例をいくつか見てきました。Office Open XML 強制型を使用してドキュメントに挿入できる豊富なコンテンツ タイプの例を、そのコンテンツを選択範囲または指定された (バインドされた) 場所に挿入するための JavaScript メソッドと共に確認しました。

そのため、スタンドアロンの使用 (ストアまたは専用サーバーの場所から挿入) と、アドインを操作するように設計された事前に作成されたテンプレートで使用するために、アドインを作成する場合は、他に何を知る必要がありますか? 必要なことはすべて知っているというのが答えかもしれません。

特定のコンテンツ タイプのマークアップと、それを挿入するためのメソッドは、アドインがスタンドアロンに設計されているか、テンプレートを使用するように設計されているかに関係なく同じです。 自分のアドインで作動するように設計されたテンプレートを使用する場合、参照コンテンツがドキュメントにすでに存在するシナリオを構成するコールバックを必ず JavaScript に含めます (セクション「指定コンテンツ コントロールを追加し、それにバインドする」のバインド例)。

ユーザーがドキュメントを作成したときにアドインがテンプレートに常駐しているか、アドインがテンプレートを挿入するかに関係なく、自分のアドインでテンプレートを使用するときは、API のその他の要素を組み込み、さらに強固でインタラクティブな体験を作ることもできます。 たとえば、テンプレート固有のオプションをユーザーに提供するために、customXML パーツに識別データを含め、それを使用し、テンプレート タイプを決定できます。 アドインにおける customXML の動作に関する詳細は、以下のその他の技術情報を参照してください。

関連項目