Word.ContentControlCollection class
Contains a collection of Word.ContentControl objects. Content controls are bounded and potentially labeled regions in a document that serve as containers for specific types of content. Individual content controls may contain contents such as images, tables, or paragraphs of formatted text. Currently, only rich text and plain text content controls are supported.
- Extends
Remarks
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| items | Gets the loaded child items in this collection. |
Methods
| get |
Gets the content controls that have the specified tracking state. |
| get |
Gets a content control by its identifier. Throws an |
| get |
Gets a content control by its identifier. If there isn't a content control with the identifier in this collection, then this method will return an object with its |
| get |
Gets the content controls that have the specified tag. |
| get |
Gets the content controls that have the specified title. |
| get |
Gets the content controls that have the specified types. |
| get |
Gets the first content control in this collection. Throws an |
| get |
Gets the first content control in this collection. If this collection is empty, then this method will return an object with its |
| get |
Gets a content control by its ID. |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| toJSON() | Overrides the JavaScript |
| track() | Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across |
| untrack() | Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call |
Property Details
context
The request context associated with the object. This connects the add-in's process to the Office host application's process.
context: RequestContext;Property Value
items
Gets the loaded child items in this collection.
readonly items: Word.ContentControl[];Property Value
Method Details
getByChangeTrackingStates(changeTrackingStates)
Gets the content controls that have the specified tracking state.
getByChangeTrackingStates(changeTrackingStates: Word.ChangeTrackingState[]): Word.ContentControlCollection;Parameters
- changeTrackingStates
Required. An array of content control change tracking states.
Returns
Remarks
getById(id)
Gets a content control by its identifier. Throws an ItemNotFound error if there isn't a content control with the identifier in this collection.
getById(id: number): Word.ContentControl;Parameters
- id
-
number
Required. A content control identifier.
Returns
Remarks
Examples
// 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)
Gets a content control by its identifier. If there isn't a content control with the identifier in this collection, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getByIdOrNullObject(id: number): Word.ContentControl;Parameters
- id
-
number
Required. A content control identifier.
Returns
Remarks
Examples
// 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)
Gets the content controls that have the specified tag.
getByTag(tag: string): Word.ContentControlCollection;Parameters
- tag
-
string
Required. A tag set on a content control.
Returns
Remarks
Examples
// 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 = 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)
Gets the content controls that have the specified title.
getByTitle(title: string): Word.ContentControlCollection;Parameters
- title
-
string
Required. The title of a content control.
Returns
Remarks
Examples
// 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)
Gets the content controls that have the specified types.
getByTypes(types: Word.ContentControlType[]): Word.ContentControlCollection;Parameters
- types
Required. An array of content control types.
Returns
Remarks
getFirst()
Gets the first content control in this collection. Throws an ItemNotFound error if this collection is empty.
getFirst(): Word.ContentControl;Returns
Remarks
Examples
// 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()
Gets the first content control in this collection. If this collection is empty, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getFirstOrNullObject(): Word.ContentControl;Returns
Remarks
getItem(id)
Gets a content control by its ID.
getItem(id: number): Word.ContentControl;Parameters
- id
-
number
The content control's ID.
Returns
Remarks
load(options)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: Word.Interfaces.ContentControlCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ContentControlCollection;Parameters
Provides options for which properties of the object to load.
Returns
Examples
// 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)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames?: string | string[]): Word.ContentControlCollection;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
load(propertyNamesAndPaths)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ContentControlCollection;Parameters
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
toJSON()
Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Word.ContentControlCollection object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.ContentControlCollectionData) that contains an "items" array with shallow copies of any loaded properties from the collection's items.
toJSON(): Word.Interfaces.ContentControlCollectionData;Returns
track()
Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.
track(): Word.ContentControlCollection;Returns
untrack()
Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.
untrack(): Word.ContentControlCollection;Returns
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for