Word.ContentControlCollection class

包含 Word 集合。ContentControl 对象。内容控件是文档中绑定的、有可能添加标签的区域，它们充当特定类型的内容的容器。各个内容控件可能包含诸如图像、表格或格式化文本段落等内容。目前仅支持格式文本、纯文本、复选框、下拉列表和组合框内容控件。

注解

API 集：WordApi 1.1

使用方

示例

// 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	获取此集合中已加载的子项。

方法

getByChangeTrackingStates(changeTrackingStates)	获取具有指定跟踪状态的内容控件。
getById(id)	按其标识符获取内容控件。如果此集合中没有具有标识符的内容控件，则引发 `ItemNotFound` 错误。
getByIdOrNullObject(id)	按其标识符获取内容控件。如果此集合中没有具有标识符的内容控件，则此方法将返回其 `isNullObject` 属性设置为 `true`的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。
getByTag(tag)	获取具有指定标记的内容控件。
getByTitle(title)	获取具有指定标题的内容控件。
getByTypes(types)	获取具有指定类型的内容控件。
getFirst()	获取此集合中的第一个内容控件。如果此集合为空，则引发 `ItemNotFound` 错误。
getFirstOrNullObject()	获取此集合中的第一个内容控件。如果此集合为空，则此方法将返回其 `isNullObject` 属性设置为 `true`的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。
getItem(id)	按 ID 获取内容控件。
load(options)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNames)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNamesAndPaths)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
toJSON()	覆盖 JavaScript `toJSON()` 方法，以便在将 API 对象传递给 `JSON.stringify()`时提供更有用的输出。 (`JSON.stringify`反过来调用 `toJSON` 传递给它的对象的方法。) 虽然原始 `Word.ContentControlCollection` 对象是 API 对象，但该 `toJSON` 方法返回一个纯 JavaScript 对象， (类型为 `Word.Interfaces.ContentControlCollectionData`) ，其中包含一个“items”数组，其中包含从集合的 items 中加载的任何属性的浅层副本。
track()	根据文档中的相应更改来跟踪对象，以便进行自动调整。此调用是 context.trackedObjects.add (thisObject) 的简写。如果在调用中 `.sync` 使用此对象，并且在“.run”批处理的顺序执行之外使用此对象，并且在设置属性或对对象调用方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将对象添加到跟踪对象集合。如果此对象是集合的一部分，您还应跟踪父集合。
untrack()	释放与此对象关联的内存（如果先前已跟踪过）。此调用是 context.trackedObjects.remove (thisObject) 的简写。拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。需要在内存释放生效之前调用 `context.sync()` 。

context

与对象关联的请求上下文。这将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Word.RequestContext

items

获取此集合中已加载的子项。

readonly items: Word.ContentControl[];

属性值

Word.ContentControl[]

getByChangeTrackingStates(changeTrackingStates)

获取具有指定跟踪状态的内容控件。

getByChangeTrackingStates(changeTrackingStates: Word.ChangeTrackingState[]): Word.ContentControlCollection;

参数

changeTrackingStates: Word.ChangeTrackingState[]

内容控件更改跟踪状态的数组。

返回

Word.ContentControlCollection

注解

API 集：WordApi 1.5

getById(id)

按其标识符获取内容控件。如果此集合中没有具有标识符的内容控件，则引发 ItemNotFound 错误。

getById(id: number): Word.ContentControl;

参数

id: number

内容控件的标识符。

返回

Word.ContentControl

注解

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 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

内容控件的标识符。

返回

Word.ContentControl

注解

API 集：WordApi 1.3

示例

// 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

在内容控件上设置的标记。

返回

Word.ContentControlCollection

注解

API 集：WordApi 1.1

示例

// 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

内容控件的标题。

返回

Word.ContentControlCollection

注解

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 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: Word.ContentControlType[]

内容控件类型的数组。

返回

Word.ContentControlCollection

注解

API 集：WordApi 1.3

getFirst()

获取此集合中的第一个内容控件。如果此集合为空，则引发 ItemNotFound 错误。

getFirst(): Word.ContentControl;

返回

Word.ContentControl

注解

API 集：WordApi 1.3

示例

// 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;

返回

Word.ContentControl

注解

API 集：WordApi 1.3

示例

// 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。

返回

Word.ContentControl

注解

API 集：WordApi 1.1

load(options)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(options?: Word.Interfaces.ContentControlCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ContentControlCollection;

参数

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[]

指定要加载的属性的逗号分隔的字符串或字符串数组。

返回

Word.ContentControlCollection

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ContentControlCollection;

参数

propertyNamesAndPaths: OfficeExtension.LoadOption

propertyNamesAndPaths.select 是指定要加载的属性的逗号分隔字符串，以及 propertyNamesAndPaths.expand 指定要加载的导航属性的逗号分隔字符串。

返回

Word.ContentControlCollection

toJSON()

覆盖 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Word.ContentControlCollection 对象是 API 对象，但该 toJSON 方法返回一个纯 JavaScript 对象， (类型为 Word.Interfaces.ContentControlCollectionData) ，其中包含一个“items”数组，其中包含从集合的 items 中加载的任何属性的浅层副本。

toJSON(): Word.Interfaces.ContentControlCollectionData;

返回

Word.Interfaces.ContentControlCollectionData

track()

根据文档中的相应更改来跟踪对象，以便进行自动调整。此调用是 context.trackedObjects.add (thisObject) 的简写。如果在调用中 .sync 使用此对象，并且在“.run”批处理的顺序执行之外使用此对象，并且在设置属性或对对象调用方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将对象添加到跟踪对象集合。如果此对象是集合的一部分，您还应跟踪父集合。

track(): Word.ContentControlCollection;

返回

Word.ContentControlCollection

untrack()

释放与此对象关联的内存（如果先前已跟踪过）。此调用是 context.trackedObjects.remove (thisObject) 的简写。拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。需要在内存释放生效之前调用 context.sync() 。

untrack(): Word.ContentControlCollection;

返回

Word.ContentControlCollection

注解

使用方

示例

属性

方法

属性详细信息

context

属性值

items

属性值

方法详细信息

getByChangeTrackingStates(changeTrackingStates)

参数

返回

注解

getById(id)

参数

返回

注解

示例

getByIdOrNullObject(id)

参数

返回

注解

示例

getByTag(tag)

参数

返回

注解

示例

getByTitle(title)

参数

返回

注解

示例

getByTypes(types)

参数

返回

注解

getFirst()

返回

注解

示例

getFirstOrNullObject()

返回

注解

示例

getItem(id)

参数

返回

注解

load(options)

参数

返回

示例

load(propertyNames)

参数

返回

load(propertyNamesAndPaths)

参数

返回

toJSON()

返回

track()

返回

untrack()

返回

反馈