Word.ContentControlCollection class
Wordのコレクションを格納します。ContentControl オブジェクト。 コンテンツ コントロールは、特定の種類のコンテンツのコンテナーとして機能する、ラベルを付けることのできる、境界線で区切られたドキュメント内の領域です。 個々のコンテンツ コントロールには、画像、テーブル、書式設定されたテキストの段落などのコンテンツが含まれていることがあります。 現時点では、リッチ テキストとプレーン テキスト コンテンツ コントロールのみがサポートされています。
- Extends
注釈
例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/90-scenarios/doc-assembly.yaml
await Word.run(async (context) => {
const contentControls: Word.ContentControlCollection = context.document.contentControls.getByTag("customer");
contentControls.load("text");
await context.sync();
for (let i = 0; i < contentControls.items.length; i++) {
contentControls.items[i].insertText("Fabrikam", "Replace");
}
await context.sync();
});
プロパティ
| context | オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。 |
| items | このコレクション内に読み込まれた子アイテムを取得します。 |
メソッド
| get |
指定した追跡状態のコンテンツ コントロールを取得します。 |
| get |
コンテンツ コントロールの識別子によってコンテンツ コントロールを取得します。 このコレクションに識別子を持つコンテンツ コントロールがない場合は、 |
| get |
コンテンツ コントロールの識別子によってコンテンツ コントロールを取得します。 このコレクションに識別子を持つコンテンツ コントロールがない場合、このメソッドは |
| get |
指定されたタグを含むコンテンツ コントロールを取得します。 |
| get |
指定されたタイトルを含むコンテンツ コントロールを取得します。 |
| get |
指定した型を持つコンテンツ コントロールを取得します。 |
| get |
このコレクション内の最初のコンテンツ コントロールを取得します。 このコレクションが空の場合は、 |
| get |
このコレクション内の最初のコンテンツ コントロールを取得します。 このコレクションが空の場合、このメソッドは |
| get |
ID でコンテンツ コントロールを取得します。 |
| load(options) | オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
| load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
| load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
| toJSON() | API オブジェクトが |
| track() | ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを |
| untrack() | 前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に、 |
プロパティの詳細
context
オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。
context: RequestContext;プロパティ値
items
メソッドの詳細
getByChangeTrackingStates(changeTrackingStates)
指定した追跡状態のコンテンツ コントロールを取得します。
getByChangeTrackingStates(changeTrackingStates: Word.ChangeTrackingState[]): Word.ContentControlCollection;パラメーター
- changeTrackingStates
必須です。 コンテンツ コントロールの変更追跡状態の配列。
戻り値
注釈
getById(id)
コンテンツ コントロールの識別子によってコンテンツ コントロールを取得します。 このコレクションに識別子を持つコンテンツ コントロールがない場合は、 ItemNotFound エラーをスローします。
getById(id: number): Word.ContentControl;パラメーター
- id
-
number
必須です。 コンテンツ コントロールの識別子。
戻り値
注釈
例
// Run a batch operation against the Word object model.
await Word.run(async (context) => {
// Create a proxy object for the content control that contains a specific id.
const contentControl = context.document.contentControls.getById(30086310);
// Queue a command to load the text property for a content control.
contentControl.load('text');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
console.log('The content control with that Id has been found in this document.');
});
getByIdOrNullObject(id)
コンテンツ コントロールの識別子によってコンテンツ コントロールを取得します。 このコレクションに識別子を持つコンテンツ コントロールがない場合、このメソッドは isNullObject プロパティを true に設定したオブジェクトを返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getByIdOrNullObject(id: number): Word.ContentControl;パラメーター
- id
-
number
必須です。 コンテンツ コントロールの識別子。
戻り値
注釈
例
// Run a batch operation against the Word object model.
await Word.run(async (context) => {
// Create a proxy object for the content control that contains a specific id.
const contentControl = context.document.contentControls.getByIdOrNullObject(30086310);
// Queue a command to load the text property for a content control.
contentControl.load('text');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
if (contentControl.isNullObject) {
console.log('There is no content control with that ID.')
} else {
console.log('The content control with that ID has been found in this document.');
}
});
getByTag(tag)
指定されたタグを含むコンテンツ コントロールを取得します。
getByTag(tag: string): Word.ContentControlCollection;パラメーター
- tag
-
string
必須です。 コンテンツ コントロールに設定するタグ。
戻り値
注釈
例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/90-scenarios/doc-assembly.yaml
await Word.run(async (context) => {
const contentControls: Word.ContentControlCollection = context.document.contentControls.getByTag("customer");
contentControls.load("text");
await context.sync();
for (let i = 0; i < contentControls.items.length; i++) {
contentControls.items[i].insertText("Fabrikam", "Replace");
}
await context.sync();
});
getByTitle(title)
指定されたタイトルを含むコンテンツ コントロールを取得します。
getByTitle(title: string): Word.ContentControlCollection;パラメーター
- title
-
string
必須です。 コンテンツ コントロールのタイトル。
戻り値
注釈
例
// 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 title.
const contentControlsWithTitle = context.document.contentControls.getByTitle('Enter Customer Address Here');
// Queue a command to load the text property for all of content controls with a specific title.
contentControlsWithTitle.load('text');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
if (contentControlsWithTitle.items.length === 0) {
console.log(
"There isn't a content control with a title of 'Enter Customer Address Here' in this document.");
} else {
console.log(
"The first content control with the title of 'Enter Customer Address Here' has this text: " +
contentControlsWithTitle.items[0].text);
}
});
// The Word-Add-in-DocumentAssembly sample has another example of using the getByTitle method.
// https://github.com/OfficeDev/Word-Add-in-DocumentAssembly
getByTypes(types)
指定した型を持つコンテンツ コントロールを取得します。
getByTypes(types: Word.ContentControlType[]): Word.ContentControlCollection;パラメーター
- types
必須です。 コンテンツ コントロールの種類の配列。
戻り値
注釈
getFirst()
このコレクション内の最初のコンテンツ コントロールを取得します。 このコレクションが空の場合は、 ItemNotFound エラーをスローします。
getFirst(): Word.ContentControl;戻り値
注釈
例
// Run a batch operation against the Word object model.
await Word.run(async (context) => {
// Create a proxy object for the first content control in the document.
const contentControl = context.document.contentControls.getFirstOrNullObject();
// Queue a command to load the text property for a content control.
contentControl.load('text');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
await context.sync();
if (contentControl.isNullObject) {
console.log('There are no content controls in this document.')
} else {
console.log('The first content control has been found in this document.');
}
});
getFirstOrNullObject()
このコレクション内の最初のコンテンツ コントロールを取得します。 このコレクションが空の場合、このメソッドは isNullObject プロパティを true に設定したオブジェクトを返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getFirstOrNullObject(): Word.ContentControl;戻り値
注釈
例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/insert-and-change-checkbox-content-control.yaml
// Toggles the isChecked property of the first checkbox content control found in the selection.
await Word.run(async (context) => {
const selectedRange: Word.Range = context.document.getSelection();
let selectedContentControl = selectedRange
.getContentControls({
types: [Word.ContentControlType.checkBox]
})
.getFirstOrNullObject();
selectedContentControl.load("id,checkboxContentControl/isChecked");
await context.sync();
if (selectedContentControl.isNullObject) {
const parentContentControl: Word.ContentControl = selectedRange.parentContentControl;
parentContentControl.load("id,type,checkboxContentControl/isChecked");
await context.sync();
if (parentContentControl.isNullObject || parentContentControl.type !== Word.ContentControlType.checkBox) {
console.warn("No checkbox content control is currently selected.");
return;
} else {
selectedContentControl = parentContentControl;
}
}
const isCheckedBefore = selectedContentControl.checkboxContentControl.isChecked;
console.log("isChecked state before:", `id: ${selectedContentControl.id} ... isChecked: ${isCheckedBefore}`);
selectedContentControl.checkboxContentControl.isChecked = !isCheckedBefore;
selectedContentControl.load("id,checkboxContentControl/isChecked");
await context.sync();
console.log(
"isChecked state after:",
`id: ${selectedContentControl.id} ... isChecked: ${selectedContentControl.checkboxContentControl.isChecked}`
);
});
getItem(id)
ID でコンテンツ コントロールを取得します。
getItem(id: number): Word.ContentControl;パラメーター
- id
-
number
コンテンツ コントロールの ID。
戻り値
注釈
load(options)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(options?: Word.Interfaces.ContentControlCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ContentControlCollection;パラメーター
読み込むオブジェクトのプロパティのオプションを提供します。
戻り値
例
// 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);
}
});
// The Silly stories add-in sample shows how the load method is used
// to load the content control collection with the tag and title properties.
// https://aka.ms/sillystorywordaddin
load(propertyNames)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNames?: string | string[]): Word.ContentControlCollection;パラメーター
- propertyNames
-
string | string[]
読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。
戻り値
load(propertyNamesAndPaths)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ContentControlCollection;パラメーター
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select は読み込むプロパティを指定するコンマ区切りの文字列で、 propertyNamesAndPaths.expand は読み込むナビゲーション プロパティを指定するコンマ区切りの文字列です。
戻り値
toJSON()
API オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (JSON.stringify、それに渡されるオブジェクトの toJSON メソッドを呼び出します)。元の Word.ContentControlCollection オブジェクトは API オブジェクトですが、 toJSON メソッドは、コレクションの項目から読み込まれたプロパティの浅いコピーを含む "items" 配列を含むプレーンな JavaScript オブジェクト ( Word.Interfaces.ContentControlCollectionDataとして型指定) を返します。
toJSON(): Word.Interfaces.ContentControlCollectionData;戻り値
track()
ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを .sync 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部でプロパティを設定するとき、またはオブジェクトに対してメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。 このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。
track(): Word.ContentControlCollection;戻り値
untrack()
前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に、 context.sync() を呼び出す必要があります。
untrack(): Word.ContentControlCollection;戻り値
Office Add-ins