Word.ContentControl class

リファレンス

パッケージ:: word

コンテンツコントロールを表します。コンテンツコントロールは、特定の種類のコンテンツのコンテナーとして機能し、ドキュメント内で境界線で区切られ、ラベルが付いた領域になる場合もあります。個々のコンテンツコントロールには、画像、テーブル、書式設定されたテキストの段落などのコンテンツが含まれていることがあります。現時点では、リッチテキスト、プレーンテキスト、およびチェックボックスコンテンツコントロールのみがサポートされています。

Extends: OfficeExtension.ClientObject

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;

    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to load the properties on the first content control.
        contentControls.items[0].load(  'appearance,' +
                                        'cannotDelete,' +
                                        'cannotEdit,' +
                                        'color,' +
                                        'id,' +
                                        'placeHolderText,' +
                                        'removeWhenEdited,' +
                                        'title,' +
                                        'text,' +
                                        'type,' +
                                        'style,' +
                                        'tag,' +
                                        'font/size,' +
                                        'font/name,' +
                                        'font/color');

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Property values of the first content control:' +
            '   ----- appearance: ' + contentControls.items[0].appearance +
            '   ----- cannotDelete: ' + contentControls.items[0].cannotDelete +
            '   ----- cannotEdit: ' + contentControls.items[0].cannotEdit +
            '   ----- color: ' + contentControls.items[0].color +
            '   ----- id: ' + contentControls.items[0].id +
            '   ----- placeHolderText: ' + contentControls.items[0].placeholderText +
            '   ----- removeWhenEdited: ' + contentControls.items[0].removeWhenEdited +
            '   ----- title: ' + contentControls.items[0].title +
            '   ----- text: ' + contentControls.items[0].text +
            '   ----- type: ' + contentControls.items[0].type +
            '   ----- style: ' + contentControls.items[0].style +
            '   ----- tag: ' + contentControls.items[0].tag +
            '   ----- font size: ' + contentControls.items[0].font.size +
            '   ----- font name: ' + contentControls.items[0].font.name +
            '   ----- font color: ' + contentControls.items[0].font.color);
    }
});

プロパティ

appearance	コンテンツコントロールの外観を指定します。値には、'BoundingBox'、'Tags'、または 'Hidden' を指定できます。
cannotDelete	ユーザーがコンテンツコントロールを削除できるかどうかを示す値を指定します。 removeWhenEdited と同時に使用することはできません。
cannotEdit	ユーザーがコンテンツコントロールの内容を編集できるかどうかを示す値を指定します。
color	コンテンツコントロールの色を指定します。色は、'#RRGGBB' 形式で指定するか、色名を使用して指定します。
contentControls	コンテンツコントロールのコンテンツコントロールオブジェクトのコレクションを取得します。
context	オブジェクトに関連付けられている要求コンテキスト。これにより、アドインのプロセスが Office ホストアプリケーションのプロセスに接続されます。
font	コンテンツコントロールのテキストの書式設定を取得します。これを使用して、フォント名、サイズ、色、およびその他のプロパティを取得および設定します。
id	コンテンツコントロールの識別子を表す整数値を取得します。
inlinePictures	コンテンツコントロール内の InlinePicture オブジェクトのコレクションを取得します。コレクションにはフローティングイメージは含まれません。
paragraphs	コンテンツコントロール内の段落オブジェクトのコレクションを取得します。
parentContentControl	コンテンツコントロールを含むコンテンツコントロールを取得します。親コンテンツコントロールがない場合は、 `ItemNotFound` エラーをスローします。
placeholderText	コンテンツコントロールのプレースホルダーテキストを指定します。コンテンツコントロールが空の場合は、淡色のテキストが表示されます。
removeWhenEdited	コンテンツコントロールが編集後に削除されるかどうかを示す値を指定します。 cannotDelete と同時に使用することはできません。
style	コンテンツコントロールのスタイル名を指定します。カスタムスタイルとローカライズされたスタイルの名前には、このプロパティを使用します。ロケール間で移植可能な組み込みスタイルを使用するには、"styleBuiltIn" プロパティを参照してください。
tag	コンテンツコントロールを識別するタグを指定します。
text	コンテンツコントロールのテキストを取得します。
title	コンテンツコントロールのタイトルを指定します。
type	コンテンツコントロールの種類を取得します。現在サポートされているのは、リッチテキスト、プレーンテキスト、チェックボックスコンテンツコントロールのみです。

メソッド

clear()	コンテンツコントロールの内容をクリアします。ユーザーは、消去された内容を元に戻す操作を実行できます。
delete(keepContent)	コンテンツコントロールとそのコンテンツを削除します。 `keepContent`が true に設定されている場合、コンテンツは削除されません。
getHtml()	コンテンツコントロールオブジェクトの HTML 表現を取得します。 Web ページまたは HTML ビューアーでレンダリングされた場合、書式設定は、ドキュメントの書式設定と完全に一致しませんが、近い形式になります。このメソッドは、異なるプラットフォーム (Windows、Mac、web 上のWordなど) 上の同じドキュメントに対してまったく同じ HTML を返しません。正確な忠実性、またはプラットフォーム間の整合性が必要な場合は、 `ContentControl.getOoxml()` を使用し、返された XML を HTML に変換します。
getOoxml()	コンテンツコントロールオブジェクトの Office Open XML (OOXML) 表記を取得します。
insertBreak(breakType, insertLocation)	メイン文書の指定した位置に、区切りを挿入します。このメソッドは、'RichTextTable'、'RichTextTableRow' および 'RichTextTableCell' コンテンツコントロールでは使用できません。
insertFileFromBase64(base64File, insertLocation)	指定した場所にあるコンテンツコントロールにドキュメントを挿入します。
insertHtml(html, insertLocation)	コンテンツコントロール内の指定された位置に HTML を挿入します。
insertOoxml(ooxml, insertLocation)	指定した場所にあるコンテンツコントロールに OOXML を挿入します。
insertParagraph(paragraphText, insertLocation)	指定した位置に、段落を挿入します。
insertText(text, insertLocation)	コンテンツコントロール内の指定された位置にテキストを挿入します。
load(options)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。プロパティを読み取る前に、`context.sync()` を呼び出す必要があります。
load(propertyNames)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。プロパティを読み取る前に、`context.sync()` を呼び出す必要があります。
load(propertyNamesAndPaths)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。プロパティを読み取る前に、`context.sync()` を呼び出す必要があります。
search(searchText, searchOptions)	コンテンツコントロールオブジェクトのスコープで、指定した SearchOptions を使用して検索を実行します。検索結果は、範囲オブジェクトのコレクションです。
select(selectionMode)	コンテンツコントロールを選択します。その結果、Word は選択範囲にスクロールされます。
select(selectionModeString)	コンテンツコントロールを選択します。その結果、Word は選択範囲にスクロールされます。
set(properties, options)	オブジェクトの複数のプロパティを同時に設定します。適切なプロパティを持つプレーンオブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。
set(properties)	既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。
toJSON()	API オブジェクトが`JSON.stringify()`に渡されたときにより便利な出力を提供するために、JavaScript `toJSON()` メソッドをオーバーライドします。 (`JSON.stringify`、それに渡されるオブジェクトの `toJSON` メソッドを呼び出します)。元の `Word.ContentControl` オブジェクトは API オブジェクトですが、 `toJSON` メソッドは、元のオブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト ( `Word.Interfaces.ContentControlData` として型指定) を返します。
track()	ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。このオブジェクトを `.sync` 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部でプロパティを設定するとき、またはオブジェクトに対してメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクトコレクションにオブジェクトを追加する必要があります。このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。
untrack()	前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。この呼び出しは、context.trackedObjects.remove(thisObject)の短縮形です。追跡対象オブジェクトが多いとホストアプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。メモリ解放が有効になる前に、 `context.sync()` を呼び出す必要があります。

プロパティの詳細

appearance

コンテンツコントロールの外観を指定します。値には、'BoundingBox'、'Tags'、または 'Hidden' を指定できます。

appearance: Word.ContentControlAppearance | "BoundingBox" | "Tags" | "Hidden";

プロパティ値

Word.ContentControlAppearance | "BoundingBox" | "Tags" | "Hidden"

注釈

[ API セット: WordApi 1.1 ]

cannotDelete

ユーザーがコンテンツコントロールを削除できるかどうかを示す値を指定します。 removeWhenEdited と同時に使用することはできません。

cannotDelete: boolean;

プロパティ値

boolean

注釈

[ API セット: WordApi 1.1 ]

cannotEdit

ユーザーがコンテンツコントロールの内容を編集できるかどうかを示す値を指定します。

cannotEdit: boolean;

プロパティ値

boolean

注釈

[ API セット: WordApi 1.1 ]

color

コンテンツコントロールの色を指定します。色は、'#RRGGBB' 形式で指定するか、色名を使用して指定します。

color: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.1 ]

contentControls

コンテンツコントロールのコンテンツコントロールオブジェクトのコレクションを取得します。

readonly contentControls: Word.ContentControlCollection;

プロパティ値

Word.ContentControlCollection

注釈

[ API セット: WordApi 1.1 ]

context

オブジェクトに関連付けられている要求コンテキスト。これにより、アドインのプロセスが Office ホストアプリケーションのプロセスに接続されます。

context: RequestContext;

プロパティ値

Word.RequestContext

font

コンテンツコントロールのテキストの書式設定を取得します。これを使用して、フォント名、サイズ、色、およびその他のプロパティを取得および設定します。

readonly font: Word.Font;

プロパティ値

Word.Font

注釈

[ API セット: WordApi 1.1 ]

id

コンテンツコントロールの識別子を表す整数値を取得します。

readonly id: number;

プロパティ値

number

注釈

[ API セット: WordApi 1.1 ]

inlinePictures

コンテンツコントロール内の InlinePicture オブジェクトのコレクションを取得します。コレクションにはフローティングイメージは含まれません。

readonly inlinePictures: Word.InlinePictureCollection;

プロパティ値

Word.InlinePictureCollection

注釈

[ API セット: WordApi 1.1 ]

paragraphs

コンテンツコントロール内の段落オブジェクトのコレクションを取得します。

readonly paragraphs: Word.ParagraphCollection;

プロパティ値

Word.ParagraphCollection

注釈

[ API セット: WordApi 1.1 ]

重要: 要件セット 1.1 と 1.2 の場合、このコンテンツコントロールに完全に含まれるテーブル内の段落は返されません。要件セット 1.3 から、そのようなテーブル内の段落も返されます。

parentContentControl

コンテンツコントロールを含むコンテンツコントロールを取得します。親コンテンツコントロールがない場合は、 ItemNotFound エラーをスローします。

readonly parentContentControl: Word.ContentControl;

プロパティ値

Word.ContentControl

注釈

[ API セット: WordApi 1.1 ]

placeholderText

コンテンツコントロールのプレースホルダーテキストを指定します。コンテンツコントロールが空の場合は、淡色のテキストが表示されます。

placeholderText: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.1 ]

removeWhenEdited

コンテンツコントロールが編集後に削除されるかどうかを示す値を指定します。 cannotDelete と同時に使用することはできません。

removeWhenEdited: boolean;

プロパティ値

boolean

注釈

[ API セット: WordApi 1.1 ]

style

コンテンツコントロールのスタイル名を指定します。カスタムスタイルとローカライズされたスタイルの名前には、このプロパティを使用します。ロケール間で移植可能な組み込みスタイルを使用するには、"styleBuiltIn" プロパティを参照してください。

style: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.1 ]

tag

コンテンツコントロールを識別するタグを指定します。

tag: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.1 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/insert-and-change-content-controls.yaml

// Traverses each paragraph of the document and wraps a content control on each with either a even or odd tags.
await Word.run(async (context) => {
  let paragraphs = context.document.body.paragraphs;
  paragraphs.load("$none"); // Don't need any properties; just wrap each paragraph with a content control.

  await context.sync();

  for (let i = 0; i < paragraphs.items.length; i++) {
    let contentControl = paragraphs.items[i].insertContentControl();
    // For even, tag "even".
    if (i % 2 === 0) {
      contentControl.tag = "even";
    } else {
      contentControl.tag = "odd";
    }
  }
  console.log("Content controls inserted: " + paragraphs.items.length);

  await context.sync();
});

text

コンテンツコントロールのテキストを取得します。

readonly text: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.1 ]

title

コンテンツコントロールのタイトルを指定します。

title: string;

プロパティ値

string

注釈

[ API セット: WordApi 1.1 ]

type

コンテンツコントロールの種類を取得します。現在サポートされているのは、リッチテキスト、プレーンテキスト、チェックボックスコンテンツコントロールのみです。

readonly type: Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText";

プロパティ値

注釈

[ API セット: WordApi 1.1 ]

メソッドの詳細

clear()

コンテンツコントロールの内容をクリアします。ユーザーは、消去された内容を元に戻す操作を実行できます。

clear(): void;

戻り値

void

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the content controls collection.
    contentControls.load('text');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
        
    if (contentControls.items.length === 0) {
        console.log("There isn't a content control in this document.");
    } else {
        // Queue a command to clear the contents of the first content control.
        contentControls.items[0].clear();

        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control cleared of contents.');
    }
});

delete(keepContent)

コンテンツコントロールとそのコンテンツを削除します。 keepContentが true に設定されている場合、コンテンツは削除されません。

delete(keepContent: boolean): void;

パラメーター

keepContent: boolean

必須です。コンテンツコントロールを使用してコンテンツを削除する必要があるかどうかを示します。 keepContentが true に設定されている場合、コンテンツは削除されません。

戻り値

void

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the content controls collection.
    contentControls.load('text');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
        
    if (contentControls.items.length === 0) {
        console.log("There isn't a content control in this document.");
    } else {            
        // Queue a command to delete the first content control. 
        // The contents will remain in the document.
        contentControls.items[0].delete(true);

        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control cleared of contents.'); 
    }
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-ondeleted-event.yaml

await Word.run(async (context) => {
  const contentControls: Word.ContentControlCollection = context.document.contentControls.getByTag("forTesting");
  contentControls.load("items");
  await context.sync();

  if (contentControls.items.length === 0) {
    console.log("There are no content controls in this document.");
  } else {
    console.log("Control to be deleted:", contentControls.items[0]);
    contentControls.items[0].delete(false);
    await context.sync();
  }
});

getHtml()

コンテンツコントロールオブジェクトの HTML 表現を取得します。 Web ページまたは HTML ビューアーでレンダリングされた場合、書式設定は、ドキュメントの書式設定と完全に一致しませんが、近い形式になります。このメソッドは、異なるプラットフォーム (Windows、Mac、web 上のWordなど) 上の同じドキュメントに対してまったく同じ HTML を返しません。正確な忠実性、またはプラットフォーム間の整合性が必要な場合は、 ContentControl.getOoxml() を使用し、返された XML を HTML に変換します。

getHtml(): OfficeExtension.ClientResult<string>;

戻り値

OfficeExtension.ClientResult<string>

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection that contains a specific tag.
    const contentControlsWithTag = context.document.contentControls.getByTag('Customer-Address');
    
    // Queue a command to load the tag property for all of content controls.
    contentControlsWithTag.load('tag');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControlsWithTag.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to get the HTML contents of the first content control.
        const html = contentControlsWithTag.items[0].getHtml();
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control HTML: ' + html.value);
    }
});

getOoxml()

コンテンツコントロールオブジェクトの Office Open XML (OOXML) 表記を取得します。

getOoxml(): OfficeExtension.ClientResult<string>;

戻り値

OfficeExtension.ClientResult<string>

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to get the OOXML contents of the first content control.
        const ooxml = contentControls.items[0].getOoxml();
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Content control OOXML: ' + ooxml.value);
    }
});

insertBreak(breakType, insertLocation)

メイン文書の指定した位置に、区切りを挿入します。このメソッドは、'RichTextTable'、'RichTextTableRow' および 'RichTextTableCell' コンテンツコントロールでは使用できません。

insertBreak(breakType: Word.BreakType | "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line", insertLocation: Word.InsertLocation.start | Word.InsertLocation.end | Word.InsertLocation.before | Word.InsertLocation.after | "Start" | "End" | "Before" | "After"): void;

パラメーター

breakType: Word.BreakType | "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line"

必須。中断の種類。

insertLocation: start | end | before | after | "Start" | "End" | "Before" | "After"

必須。値は、'Start'、'End'、'Before'、または 'After' である必要があります。

戻り値

void

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of content controls.
    contentControls.load('id');
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    // We now will have access to the content control collection.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to insert a page break after the first content control.
        contentControls.items[0].insertBreak(Word.BreakType.page, Word.InsertLocation.after);
        
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted a page break after the first content control.');    
    }
});

insertFileFromBase64(base64File, insertLocation)

指定した場所にあるコンテンツコントロールにドキュメントを挿入します。

insertFileFromBase64(base64File: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

パラメーター

base64File: string

必須。 .docx ファイルの Base64 でエンコードされたコンテンツ。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

必須。値は、'Replace'、'Start'、または 'End' である必要があります。 'Replace' は、'RichTextTable' および 'RichTextTableRow' コンテンツコントロールでは使用できません。

戻り値

Word.Range

注釈

[ API セット: WordApi 1.1 ]

注: 挿入するドキュメントに ActiveX コントロールが含まれている場合 (フォームフィールドの可能性があります)、挿入はサポートされません。このようなフォームフィールドを、シナリオに適したコンテンツコントロールまたはその他のオプションに置き換えることを検討してください。

insertHtml(html, insertLocation)

コンテンツコントロール内の指定された位置に HTML を挿入します。

insertHtml(html: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

パラメーター

html: string

必須です。コンテンツコントロールに挿入する HTML。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

必須です。値は、'Replace'、'Start'、または 'End' である必要があります。 'Replace' は、'RichTextTable' および 'RichTextTableRow' コンテンツコントロールでは使用できません。

戻り値

Word.Range

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to put HTML into the contents of the first content control.
        contentControls.items[0].insertHtml(
            '<strong>HTML content inserted into the content control.</strong>',
            'Start');
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted HTML in the first content control.');
    }
});

insertOoxml(ooxml, insertLocation)

指定した場所にあるコンテンツコントロールに OOXML を挿入します。

insertOoxml(ooxml: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

パラメーター

ooxml: string

必須。コンテンツコントロールに挿入する OOXML。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

戻り値

Word.Range

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to put OOXML into the contents of the first content control.
        contentControls.items[0].insertOoxml("<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>", "End");
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted OOXML in the first content control.');
    }
});  

// Read "Create better add-ins for Word with Office Open XML" for guidance on working with OOXML.
// https://learn.microsoft.com/office/dev/add-ins/word/create-better-add-ins-for-word-with-office-open-xml

insertParagraph(paragraphText, insertLocation)

指定した位置に、段落を挿入します。

insertParagraph(paragraphText: string, insertLocation: Word.InsertLocation.start | Word.InsertLocation.end | Word.InsertLocation.before | Word.InsertLocation.after | "Start" | "End" | "Before" | "After"): Word.Paragraph;

パラメーター

paragraphText: string

必須。挿入する段落テキスト。

insertLocation: start | end | before | after | "Start" | "End" | "Before" | "After"

必須です。値は、'Start'、'End'、'Before'、または 'After' である必要があります。 'Before' と 'After' は、'RichTextTable'、'RichTextTableRow' および 'RichTextTableCell' コンテンツコントロールでは使用できません。

戻り値

Word.Paragraph

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to insert a paragraph after the first content control.
        contentControls.items[0].insertParagraph('Text of the inserted paragraph.', 'After');
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Inserted a paragraph after the first content control.');
    }
});

insertText(text, insertLocation)

コンテンツコントロール内の指定された位置にテキストを挿入します。

insertText(text: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;

パラメーター

text: string

必須。コンテンツコントロールに挿入するテキスト。

insertLocation: replace | start | end | "Replace" | "Start" | "End"

戻り値

Word.Range

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to replace text in the first content control.
        contentControls.items[0].insertText('Replaced text in the first content control.', 'Replace');
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Replaced text in the first content control.');
    }
});  

// The Silly stories add-in sample shows how to use the insertText method.
// https://aka.ms/sillystorywordaddin

load(options)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(options?: Word.Interfaces.ContentControlLoadOptions): Word.ContentControl;

パラメーター

options: Word.Interfaces.ContentControlLoadOptions

読み込むオブジェクトのプロパティのオプションを提供します。

戻り値

Word.ContentControl

例

// Load all of the content control properties
// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    } else {
        // Queue a command to load the properties on the first content control.
        contentControls.items[0].load(  'appearance,' +
                                        'cannotDelete,' +
                                        'cannotEdit,' +
                                        'id,' +
                                        'placeHolderText,' +
                                        'removeWhenEdited,' +
                                        'title,' +
                                        'text,' +
                                        'type,' +
                                        'style,' +
                                        'tag,' +
                                        'font/size,' +
                                        'font/name,' +
                                        'font/color');             
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Property values of the first content control:' + 
            '   ----- appearance: ' + contentControls.items[0].appearance + 
            '   ----- cannotDelete: ' + contentControls.items[0].cannotDelete +
            '   ----- cannotEdit: ' + contentControls.items[0].cannotEdit +
            '   ----- color: ' + contentControls.items[0].color +
            '   ----- id: ' + contentControls.items[0].id +
            '   ----- placeHolderText: ' + contentControls.items[0].placeholderText +
            '   ----- removeWhenEdited: ' + contentControls.items[0].removeWhenEdited +
            '   ----- title: ' + contentControls.items[0].title +
            '   ----- text: ' + contentControls.items[0].text +
            '   ----- type: ' + contentControls.items[0].type +
            '   ----- style: ' + contentControls.items[0].style +
            '   ----- tag: ' + contentControls.items[0].tag +
            '   ----- font size: ' + contentControls.items[0].font.size +
            '   ----- font name: ' + contentControls.items[0].font.name +
            '   ----- font color: ' + contentControls.items[0].font.color);
    }
});

load(propertyNames)

load(propertyNames?: string | string[]): Word.ContentControl;

パラメーター

propertyNames: string | string[]

読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。

戻り値

Word.ContentControl

load(propertyNamesAndPaths)

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.ContentControl;

パラメーター

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select は読み込むプロパティを指定するコンマ区切りの文字列で、 propertyNamesAndPaths.expand は読み込むナビゲーションプロパティを指定するコンマ区切りの文字列です。

戻り値

Word.ContentControl

search(searchText, searchOptions)

コンテンツコントロールオブジェクトのスコープで、指定した SearchOptions を使用して検索を実行します。検索結果は、範囲オブジェクトのコレクションです。

search(searchText: string, searchOptions?: Word.SearchOptions | {
            ignorePunct?: boolean;
            ignoreSpace?: boolean;
            matchCase?: boolean;
            matchPrefix?: boolean;
            matchSuffix?: boolean;
            matchWholeWord?: boolean;
            matchWildcards?: boolean;
        }): Word.RangeCollection;

パラメーター

searchText: string

必須。検索テキスト。

searchOptions: Word.SearchOptions | { ignorePunct?: boolean; ignoreSpace?: boolean; matchCase?: boolean; matchPrefix?: boolean; matchSuffix?: boolean; matchWholeWord?: boolean; matchWildcards?: boolean; }

省略可能。検索のオプション。

戻り値

Word.RangeCollection

注釈

[ API セット: WordApi 1.1 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the content controls collection.
    const contentControls = context.document.contentControls;
    
    // Queue a command to load the id property for all of the content controls.
    contentControls.load('id');
     
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (contentControls.items.length === 0) {
        console.log('No content control found.');
    }
    else {
        // Queue a command to select the first content control.
        contentControls.items[0].select();
    
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Selected the first content control.');
    }
});

select(selectionMode)

コンテンツコントロールを選択します。その結果、Word は選択範囲にスクロールされます。

select(selectionMode?: Word.SelectionMode): void;

パラメーター

selectionMode: Word.SelectionMode

省略可能。選択モードは、'Select'、'Start'、または 'End' である必要があります。 'Select' が既定値です。

戻り値

void

注釈

[ API セット: WordApi 1.1 ]

select(selectionModeString)

コンテンツコントロールを選択します。その結果、Word は選択範囲にスクロールされます。

select(selectionModeString?: "Select" | "Start" | "End"): void;

パラメーター

selectionModeString: "Select" | "Start" | "End"

省略可能。選択モードは、'Select'、'Start'、または 'End' である必要があります。 'Select' が既定値です。

戻り値

void

注釈

[ API セット: WordApi 1.1 ]

set(properties, options)

オブジェクトの複数のプロパティを同時に設定します。適切なプロパティを持つプレーンオブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。

set(properties: Interfaces.ContentControlUpdateData, options?: OfficeExtension.UpdateOptions): void;

パラメーター

properties: Word.Interfaces.ContentControlUpdateData

メソッドが呼び出されるオブジェクトのプロパティに等形的に構造化されたプロパティを持つ JavaScript オブジェクト。

options: OfficeExtension.UpdateOptions

properties オブジェクトが読み取り専用プロパティを設定しようとした場合にエラーを抑制するオプションを提供します。

戻り値

void

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/insert-and-change-content-controls.yaml

// Adds title and colors to odd and even content controls and changes their appearance.
await Word.run(async (context) => {
  // Get the complete sentence (as range) associated with the insertion point.
  let evenContentControls = context.document.contentControls.getByTag("even");
  let oddContentControls = context.document.contentControls.getByTag("odd");
  evenContentControls.load("length");
  oddContentControls.load("length");

  await context.sync();

  for (let i = 0; i < evenContentControls.items.length; i++) {
    // Change a few properties and append a paragraph.
    evenContentControls.items[i].set({
      color: "red",
      title: "Odd ContentControl #" + (i + 1),
      appearance: Word.ContentControlAppearance.tags
    });
    evenContentControls.items[i].insertParagraph("This is an odd content control", "End");
  }

  for (let j = 0; j < oddContentControls.items.length; j++) {
    // Change a few properties and append a paragraph.
    oddContentControls.items[j].set({
      color: "green",
      title: "Even ContentControl #" + (j + 1),
      appearance: "Tags"
    });
    oddContentControls.items[j].insertHtml("This is an <b>even</b> content control", "End");
  }

  await context.sync();
});

set(properties)

既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。

set(properties: Word.ContentControl): void;

パラメーター

properties: Word.ContentControl

戻り値

void

toJSON()

API オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (JSON.stringify、それに渡されるオブジェクトの toJSON メソッドを呼び出します)。元の Word.ContentControl オブジェクトは API オブジェクトですが、 toJSON メソッドは、元のオブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト ( Word.Interfaces.ContentControlData として型指定) を返します。

toJSON(): Word.Interfaces.ContentControlData;

戻り値

Word.Interfaces.ContentControlData

track()

ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。このオブジェクトを .sync 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部でプロパティを設定するとき、またはオブジェクトに対してメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクトコレクションにオブジェクトを追加する必要があります。このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。

track(): Word.ContentControl;

戻り値

Word.ContentControl

untrack()

前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。この呼び出しは、context.trackedObjects.remove(thisObject)の短縮形です。追跡対象オブジェクトが多いとホストアプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。メモリ解放が有効になる前に、 context.sync() を呼び出す必要があります。

untrack(): Word.ContentControl;

戻り値

Word.ContentControl

次の方法で共有

Word.ContentControl class

注釈

例

プロパティ

メソッド

プロパティの詳細

appearance

プロパティ値

注釈

cannotDelete

プロパティ値

注釈

cannotEdit

プロパティ値

注釈

color

プロパティ値

注釈

contentControls

プロパティ値

注釈

context

プロパティ値

font

プロパティ値

注釈

id

プロパティ値

注釈

inlinePictures

プロパティ値

注釈

paragraphs

プロパティ値

注釈

parentContentControl

プロパティ値

注釈

placeholderText

プロパティ値

注釈

removeWhenEdited

プロパティ値

注釈

style

プロパティ値

注釈

tag

プロパティ値

注釈

例

text

プロパティ値

注釈

title

プロパティ値

注釈

type

プロパティ値

注釈

メソッドの詳細

clear()

戻り値

注釈

例

delete(keepContent)

パラメーター

戻り値

注釈

例

getHtml()

戻り値

注釈

例

getOoxml()

戻り値

注釈

例

insertBreak(breakType, insertLocation)