Word 文書におけるコンテンツ コントロールを操作する

  • 12 分

このユニットでは、コンテンツ コントロールの概要と、それらを Microsoft Word 文書で使用する方法について説明します。

コンテンツ コントロールとは

コンテンツ コントロールは、特定の種類のコンテンツ (フィールドと同様) のコンテナーとして機能するドキュメント内で境界付けされます。 作成者は、コンテンツ コントロールにラベルを付けて、そのコンテンツの使用方法をユーザーに示すことができます。

Word 文書のコンテンツ コントロールのスクリーンショット。

コンテンツ コントロールは、テキストの非構造化範囲に構造を追加するために使用されます。 特に、文書テンプレートで役立ちます。

個々のコンテンツ コントロールには、画像、テーブル、書式設定されたテキストの段落などのコンテンツが含まれていることがあります。 開発者は Word JavaScript API、Office.js を使用して、リッチ テキスト コンテンツ コントロールを操作できます。

Word 文書にコンテンツ コントロールを挿入する

文書の本文と任意のテーブル、インライン画像、段落、または範囲を、コンテンツ コントロールでラップできます。

まず、サポートされているオブジェクトへの参照を取得し、insertContentControl() メソッドを使用して、コンテンツ コントロールを作成します。 このメソッドにより、ContentControl オブジェクトのインスタンスが返されます。

コンテンツ コントロールには、より簡単に使用できる、あるいは後日そのコンテンツを簡単に参照したり更新したりするための多くのプロパティがあります。

コンテンツ コントロールでのコンテンツの更新

コンテンツ コントロールは、オブジェクトの contentControls コレクションを介してアクセスされ、ID、Tag、Title、または Type 個別にフィルター処理されます。

コンテンツ コントロール内のコンテンツにアクセスするには、getHtml() や insertTable() などの、対応するオブジェクトに対して get*() メソッドと insert*() メソッドを使用します。

ContentControl オブジェクトのプロパティ

次のテーブルは、ContentControl オブジェクトに対して開発者が使用できるプロパティのリストです。 これらの各プロパティは、Office.js を使用して設定できます。

多くのプロパティによって、コンテンツの外観が決定されることに注意してください。 プロパティの多くは tag プロパティのように、コントロールを簡単に参照するために使用されます。

プロパティ 説明
appearance コンテンツ コントロールの外観は、boundingBox、tags、または hidden とすることができます
cannotDelete ユーザーがコンテンツ コントロールを削除できるかどうかを示します
cannotEdit ユーザーがコンテンツ コントロールのコンテンツを編集できるかどうかを示します
color #RRGGBB 形式または名前で指定する任意指定のカラー
placeholderText コンテンツ コントロールのプレースホルダー テキスト
removedWhenEdited 編集後にコントロールが削除されるかどうかを示します
style カスタム スタイルを使用したコンテンツ コントロールのスタイル名
styleBuiltIn コンテンツ コントロールの組み込みスタイル名
subtype リッチ テキスト コンテンツ コントロールの場合は、サブタイプを RichTextInline、RichTextParagraphs、RichTextTableCell、RichTextTableRow、RichTextTable にできます
tag コンテンツ コントロールを識別するタグ
text コンテンツ コントロールのテキスト
title コンテンツ コントロールのタイトル
type コンテンツ コントロールのタイプ (RichText のみサポートされています)

次のコード例では、Office.js およびコンテンツ コントロールを使用する場合に開発者が直面する一般的なシナリオを示します。

  • 文書内のすべてのコンテンツ コントロールを取得します:

    const ctrl = context.document.contentControls;

  • タブ名により最初のコンテンツ コントロールを取得します:

    const ctrl = context.document.contentControls.getByTag("MyContentControl").getFirst();

  • コンテンツ コントロールのコンテンツの HTML 表記を取得します:

    const html = ctrl.getHtml();

  • 文書内で選択した内容に基づいて、コンテンツ コントロールを挿入します:

    const selectionRange = context.document.getSelection();
const ctrl = selectionRange.insertContentControl();
ctrl.title = "Invoice Number";
ctrl.tag = "InvoiceNumber";
ctrl.appearance = "BoundingBox";
ctrl.color = "#FF9900";

概要

このユニットでは、コンテンツ コントロールの概要と、それらを Microsoft Word 文書で使用する方法について説明しました。