Word.ContentControl class
Represents a content control. 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, plain text, and checkbox content controls are supported.
- Extends
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.
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);
}
});
Properties
| appearance | Specifies the appearance of the content control. The value can be 'BoundingBox', 'Tags', or 'Hidden'. |
| cannot |
Specifies a value that indicates whether the user can delete the content control. Mutually exclusive with removeWhenEdited. |
| cannot |
Specifies a value that indicates whether the user can edit the contents of the content control. |
| checkbox |
Specifies the checkbox-related data if the content control's type is 'CheckBox'. It's null otherwise. |
| color | Specifies the color of the content control. Color is specified in '#RRGGBB' format or by using the color name. |
| content |
Gets the collection of content control objects in the content control. |
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| endnotes | Gets the collection of endnotes in the content control. |
| fields | Gets the collection of field objects in the content control. |
| font | Gets the text format of the content control. Use this to get and set font name, size, color, and other properties. |
| footnotes | Gets the collection of footnotes in the content control. |
| id | Gets an integer that represents the content control identifier. |
| inline |
Gets the collection of InlinePicture objects in the content control. The collection doesn't include floating images. |
| lists | Gets the collection of list objects in the content control. |
| paragraphs | Gets the collection of paragraph objects in the content control. |
| parent |
Gets the parent body of the content control. |
| parent |
Gets the content control that contains the content control. Throws an |
| parent |
Gets the content control that contains the content control. If there isn't a parent content control, then this method will return an object with its |
| parent |
Gets the table that contains the content control. Throws an |
| parent |
Gets the table cell that contains the content control. Throws an |
| parent |
Gets the table cell that contains the content control. If it isn't contained in a table cell, then this method will return an object with its |
| parent |
Gets the table that contains the content control. If it isn't contained in a table, then this method will return an object with its |
| placeholder |
Specifies the placeholder text of the content control. Dimmed text will be displayed when the content control is empty. Note: The set operation for this property isn't supported in Word on the web. |
| remove |
Specifies a value that indicates whether the content control is removed after it is edited. Mutually exclusive with cannotDelete. |
| style | Specifies the style name for the content control. Use this property for custom styles and localized style names. To use the built-in styles that are portable between locales, see the "styleBuiltIn" property. |
| style |
Specifies the built-in style name for the content control. Use this property for built-in styles that are portable between locales. To use custom styles or localized style names, see the "style" property. |
| subtype | Gets the content control subtype. The subtype can be 'RichTextInline', 'RichTextParagraphs', 'RichTextTableCell', 'RichTextTableRow' and 'RichTextTable' for rich text content controls, or 'PlainTextInline' and 'PlainTextParagraph' for plain text content controls, or 'CheckBox' for checkbox content controls. |
| tables | Gets the collection of table objects in the content control. |
| tag | Specifies a tag to identify a content control. |
| text | Gets the text of the content control. |
| title | Specifies the title for a content control. |
| type | Gets the content control type. Only rich text, plain text, and checkbox content controls are supported currently. |
Methods
| clear() | Clears the contents of the content control. The user can perform the undo operation on the cleared content. |
| delete(keep |
Deletes the content control and its content. If |
| get |
Gets comments associated with the content control. |
| get |
Gets the currently supported child content controls in this content control. |
| get |
Gets an HTML representation of the content control object. When rendered in a web page or HTML viewer, the formatting will be a close, but not exact, match for of the formatting of the document. This method doesn't return the exact same HTML for the same document on different platforms (Windows, Mac, Word on the web, etc.). If you need exact fidelity, or consistency across platforms, use |
| get |
Gets the Office Open XML (OOXML) representation of the content control object. |
| get |
Gets the whole content control, or the starting or ending point of the content control, as a range. |
| get |
Gets reviewed text based on ChangeTrackingVersion selection. |
| get |
Gets reviewed text based on ChangeTrackingVersion selection. |
| get |
Gets the text ranges in the content control by using punctuation marks and/or other ending marks. |
| get |
Gets the collection of the TrackedChange objects in the content control. |
| insert |
Inserts a break at the specified location in the main document. This method cannot be used with 'RichTextTable', 'RichTextTableRow' and 'RichTextTableCell' content controls. |
| insert |
Inserts a document into the content control at the specified location. |
| insert |
Inserts HTML into the content control at the specified location. |
| insert |
Inserts an inline picture into the content control at the specified location. |
| insert |
Inserts OOXML into the content control at the specified location. |
| insert |
Inserts a paragraph at the specified location. |
| insert |
Inserts a table with the specified number of rows and columns into, or next to, a content control. |
| insert |
Inserts text into the content control at the specified location. |
| 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 |
| reset |
Resets the state of the content control. |
| search(search |
Performs a search with the specified SearchOptions on the scope of the content control object. The search results are a collection of range objects. |
| select(selection |
Selects the content control. This causes Word to scroll to the selection. |
| select(selection |
Selects the content control. This causes Word to scroll to the selection. |
| set(properties, options) | Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type. |
| set(properties) | Sets multiple properties on the object at the same time, based on an existing loaded object. |
| set |
Sets the state of the content control. |
| set |
Sets the state of the content control. |
| split(delimiters, multi |
Splits the content control into child ranges by using delimiters. |
| 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 |
Events
| on |
Occurs when new comments are added. |
| on |
Occurs when a comment or its reply is changed. |
| on |
Occurs when a comment is deselected. |
| on |
Occurs when a comment is selected. |
| on |
Occurs when data within the content control are changed. To get the new text, load this content control in the handler. To get the old text, do not load it. |
| on |
Occurs when the content control is deleted. Do not load this content control in the handler, otherwise you won't be able to get its original properties. |
| on |
Occurs when the content control is entered. |
| on |
Occurs when the content control is exited, for example, when the cursor leaves the content control. |
| on |
Occurs when selection within the content control is changed. |
Property Details
appearance
Specifies the appearance of the content control. The value can be 'BoundingBox', 'Tags', or 'Hidden'.
appearance: Word.ContentControlAppearance | "BoundingBox" | "Tags" | "Hidden";Property Value
Word.ContentControlAppearance | "BoundingBox" | "Tags" | "Hidden"
Remarks
cannotDelete
Specifies a value that indicates whether the user can delete the content control. Mutually exclusive with removeWhenEdited.
cannotDelete: boolean;Property Value
boolean
Remarks
cannotEdit
Specifies a value that indicates whether the user can edit the contents of the content control.
cannotEdit: boolean;Property Value
boolean
Remarks
checkboxContentControl
Specifies the checkbox-related data if the content control's type is 'CheckBox'. It's null otherwise.
readonly checkboxContentControl: Word.CheckboxContentControl;Property Value
Remarks
color
Specifies the color of the content control. Color is specified in '#RRGGBB' format or by using the color name.
color: string;Property Value
string
Remarks
contentControls
Gets the collection of content control objects in the content control.
readonly contentControls: Word.ContentControlCollection;Property Value
Remarks
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
endnotes
Gets the collection of endnotes in the content control.
readonly endnotes: Word.NoteItemCollection;Property Value
Remarks
fields
Gets the collection of field objects in the content control.
readonly fields: Word.FieldCollection;Property Value
Remarks
font
Gets the text format of the content control. Use this to get and set font name, size, color, and other properties.
readonly font: Word.Font;Property Value
Remarks
footnotes
Gets the collection of footnotes in the content control.
readonly footnotes: Word.NoteItemCollection;Property Value
Remarks
id
Gets an integer that represents the content control identifier.
readonly id: number;Property Value
number
Remarks
inlinePictures
Gets the collection of InlinePicture objects in the content control. The collection doesn't include floating images.
readonly inlinePictures: Word.InlinePictureCollection;Property Value
Remarks
lists
Gets the collection of list objects in the content control.
readonly lists: Word.ListCollection;Property Value
Remarks
paragraphs
Gets the collection of paragraph objects in the content control.
readonly paragraphs: Word.ParagraphCollection;Property Value
Remarks
Important: For requirement sets 1.1 and 1.2, paragraphs in tables wholly contained within this content control aren't returned. From requirement set 1.3, paragraphs in such tables are also returned.
parentBody
Gets the parent body of the content control.
readonly parentBody: Word.Body;Property Value
Remarks
parentContentControl
Gets the content control that contains the content control. Throws an ItemNotFound error if there isn't a parent content control.
readonly parentContentControl: Word.ContentControl;Property Value
Remarks
parentContentControlOrNullObject
Gets the content control that contains the content control. If there isn't a parent content control, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
readonly parentContentControlOrNullObject: Word.ContentControl;Property Value
Remarks
parentTable
Gets the table that contains the content control. Throws an ItemNotFound error if it isn't contained in a table.
readonly parentTable: Word.Table;Property Value
Remarks
parentTableCell
Gets the table cell that contains the content control. Throws an ItemNotFound error if it isn't contained in a table cell.
readonly parentTableCell: Word.TableCell;Property Value
Remarks
parentTableCellOrNullObject
Gets the table cell that contains the content control. If it isn't contained in a table cell, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
readonly parentTableCellOrNullObject: Word.TableCell;Property Value
Remarks
parentTableOrNullObject
Gets the table that contains the content control. If it isn't contained in a table, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
readonly parentTableOrNullObject: Word.Table;Property Value
Remarks
placeholderText
Specifies the placeholder text of the content control. Dimmed text will be displayed when the content control is empty.
Note: The set operation for this property isn't supported in Word on the web.
placeholderText: string;Property Value
string
Remarks
removeWhenEdited
Specifies a value that indicates whether the content control is removed after it is edited. Mutually exclusive with cannotDelete.
removeWhenEdited: boolean;Property Value
boolean
Remarks
style
Specifies the style name for the content control. Use this property for custom styles and localized style names. To use the built-in styles that are portable between locales, see the "styleBuiltIn" property.
style: string;Property Value
string
Remarks
styleBuiltIn
Specifies the built-in style name for the content control. Use this property for built-in styles that are portable between locales. To use custom styles or localized style names, see the "style" property.
styleBuiltIn: Word.BuiltInStyleName | "Other" | "Normal" | "Heading1" | "Heading2" | "Heading3" | "Heading4" | "Heading5" | "Heading6" | "Heading7" | "Heading8" | "Heading9" | "Toc1" | "Toc2" | "Toc3" | "Toc4" | "Toc5" | "Toc6" | "Toc7" | "Toc8" | "Toc9" | "FootnoteText" | "Header" | "Footer" | "Caption" | "FootnoteReference" | "EndnoteReference" | "EndnoteText" | "Title" | "Subtitle" | "Hyperlink" | "Strong" | "Emphasis" | "NoSpacing" | "ListParagraph" | "Quote" | "IntenseQuote" | "SubtleEmphasis" | "IntenseEmphasis" | "SubtleReference" | "IntenseReference" | "BookTitle" | "Bibliography" | "TocHeading" | "TableGrid" | "PlainTable1" | "PlainTable2" | "PlainTable3" | "PlainTable4" | "PlainTable5" | "TableGridLight" | "GridTable1Light" | "GridTable1Light_Accent1" | "GridTable1Light_Accent2" | "GridTable1Light_Accent3" | "GridTable1Light_Accent4" | "GridTable1Light_Accent5" | "GridTable1Light_Accent6" | "GridTable2" | "GridTable2_Accent1" | "GridTable2_Accent2" | "GridTable2_Accent3" | "GridTable2_Accent4" | "GridTable2_Accent5" | "GridTable2_Accent6" | "GridTable3" | "GridTable3_Accent1" | "GridTable3_Accent2" | "GridTable3_Accent3" | "GridTable3_Accent4" | "GridTable3_Accent5" | "GridTable3_Accent6" | "GridTable4" | "GridTable4_Accent1" | "GridTable4_Accent2" | "GridTable4_Accent3" | "GridTable4_Accent4" | "GridTable4_Accent5" | "GridTable4_Accent6" | "GridTable5Dark" | "GridTable5Dark_Accent1" | "GridTable5Dark_Accent2" | "GridTable5Dark_Accent3" | "GridTable5Dark_Accent4" | "GridTable5Dark_Accent5" | "GridTable5Dark_Accent6" | "GridTable6Colorful" | "GridTable6Colorful_Accent1" | "GridTable6Colorful_Accent2" | "GridTable6Colorful_Accent3" | "GridTable6Colorful_Accent4" | "GridTable6Colorful_Accent5" | "GridTable6Colorful_Accent6" | "GridTable7Colorful" | "GridTable7Colorful_Accent1" | "GridTable7Colorful_Accent2" | "GridTable7Colorful_Accent3" | "GridTable7Colorful_Accent4" | "GridTable7Colorful_Accent5" | "GridTable7Colorful_Accent6" | "ListTable1Light" | "ListTable1Light_Accent1" | "ListTable1Light_Accent2" | "ListTable1Light_Accent3" | "ListTable1Light_Accent4" | "ListTable1Light_Accent5" | "ListTable1Light_Accent6" | "ListTable2" | "ListTable2_Accent1" | "ListTable2_Accent2" | "ListTable2_Accent3" | "ListTable2_Accent4" | "ListTable2_Accent5" | "ListTable2_Accent6" | "ListTable3" | "ListTable3_Accent1" | "ListTable3_Accent2" | "ListTable3_Accent3" | "ListTable3_Accent4" | "ListTable3_Accent5" | "ListTable3_Accent6" | "ListTable4" | "ListTable4_Accent1" | "ListTable4_Accent2" | "ListTable4_Accent3" | "ListTable4_Accent4" | "ListTable4_Accent5" | "ListTable4_Accent6" | "ListTable5Dark" | "ListTable5Dark_Accent1" | "ListTable5Dark_Accent2" | "ListTable5Dark_Accent3" | "ListTable5Dark_Accent4" | "ListTable5Dark_Accent5" | "ListTable5Dark_Accent6" | "ListTable6Colorful" | "ListTable6Colorful_Accent1" | "ListTable6Colorful_Accent2" | "ListTable6Colorful_Accent3" | "ListTable6Colorful_Accent4" | "ListTable6Colorful_Accent5" | "ListTable6Colorful_Accent6" | "ListTable7Colorful" | "ListTable7Colorful_Accent1" | "ListTable7Colorful_Accent2" | "ListTable7Colorful_Accent3" | "ListTable7Colorful_Accent4" | "ListTable7Colorful_Accent5" | "ListTable7Colorful_Accent6";Property Value
Word.BuiltInStyleName | "Other" | "Normal" | "Heading1" | "Heading2" | "Heading3" | "Heading4" | "Heading5" | "Heading6" | "Heading7" | "Heading8" | "Heading9" | "Toc1" | "Toc2" | "Toc3" | "Toc4" | "Toc5" | "Toc6" | "Toc7" | "Toc8" | "Toc9" | "FootnoteText" | "Header" | "Footer" | "Caption" | "FootnoteReference" | "EndnoteReference" | "EndnoteText" | "Title" | "Subtitle" | "Hyperlink" | "Strong" | "Emphasis" | "NoSpacing" | "ListParagraph" | "Quote" | "IntenseQuote" | "SubtleEmphasis" | "IntenseEmphasis" | "SubtleReference" | "IntenseReference" | "BookTitle" | "Bibliography" | "TocHeading" | "TableGrid" | "PlainTable1" | "PlainTable2" | "PlainTable3" | "PlainTable4" | "PlainTable5" | "TableGridLight" | "GridTable1Light" | "GridTable1Light_Accent1" | "GridTable1Light_Accent2" | "GridTable1Light_Accent3" | "GridTable1Light_Accent4" | "GridTable1Light_Accent5" | "GridTable1Light_Accent6" | "GridTable2" | "GridTable2_Accent1" | "GridTable2_Accent2" | "GridTable2_Accent3" | "GridTable2_Accent4" | "GridTable2_Accent5" | "GridTable2_Accent6" | "GridTable3" | "GridTable3_Accent1" | "GridTable3_Accent2" | "GridTable3_Accent3" | "GridTable3_Accent4" | "GridTable3_Accent5" | "GridTable3_Accent6" | "GridTable4" | "GridTable4_Accent1" | "GridTable4_Accent2" | "GridTable4_Accent3" | "GridTable4_Accent4" | "GridTable4_Accent5" | "GridTable4_Accent6" | "GridTable5Dark" | "GridTable5Dark_Accent1" | "GridTable5Dark_Accent2" | "GridTable5Dark_Accent3" | "GridTable5Dark_Accent4" | "GridTable5Dark_Accent5" | "GridTable5Dark_Accent6" | "GridTable6Colorful" | "GridTable6Colorful_Accent1" | "GridTable6Colorful_Accent2" | "GridTable6Colorful_Accent3" | "GridTable6Colorful_Accent4" | "GridTable6Colorful_Accent5" | "GridTable6Colorful_Accent6" | "GridTable7Colorful" | "GridTable7Colorful_Accent1" | "GridTable7Colorful_Accent2" | "GridTable7Colorful_Accent3" | "GridTable7Colorful_Accent4" | "GridTable7Colorful_Accent5" | "GridTable7Colorful_Accent6" | "ListTable1Light" | "ListTable1Light_Accent1" | "ListTable1Light_Accent2" | "ListTable1Light_Accent3" | "ListTable1Light_Accent4" | "ListTable1Light_Accent5" | "ListTable1Light_Accent6" | "ListTable2" | "ListTable2_Accent1" | "ListTable2_Accent2" | "ListTable2_Accent3" | "ListTable2_Accent4" | "ListTable2_Accent5" | "ListTable2_Accent6" | "ListTable3" | "ListTable3_Accent1" | "ListTable3_Accent2" | "ListTable3_Accent3" | "ListTable3_Accent4" | "ListTable3_Accent5" | "ListTable3_Accent6" | "ListTable4" | "ListTable4_Accent1" | "ListTable4_Accent2" | "ListTable4_Accent3" | "ListTable4_Accent4" | "ListTable4_Accent5" | "ListTable4_Accent6" | "ListTable5Dark" | "ListTable5Dark_Accent1" | "ListTable5Dark_Accent2" | "ListTable5Dark_Accent3" | "ListTable5Dark_Accent4" | "ListTable5Dark_Accent5" | "ListTable5Dark_Accent6" | "ListTable6Colorful" | "ListTable6Colorful_Accent1" | "ListTable6Colorful_Accent2" | "ListTable6Colorful_Accent3" | "ListTable6Colorful_Accent4" | "ListTable6Colorful_Accent5" | "ListTable6Colorful_Accent6" | "ListTable7Colorful" | "ListTable7Colorful_Accent1" | "ListTable7Colorful_Accent2" | "ListTable7Colorful_Accent3" | "ListTable7Colorful_Accent4" | "ListTable7Colorful_Accent5" | "ListTable7Colorful_Accent6"
Remarks
subtype
Gets the content control subtype. The subtype can be 'RichTextInline', 'RichTextParagraphs', 'RichTextTableCell', 'RichTextTableRow' and 'RichTextTable' for rich text content controls, or 'PlainTextInline' and 'PlainTextParagraph' for plain text content controls, or 'CheckBox' for checkbox content controls.
readonly subtype: Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText";Property Value
Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText"
Remarks
tables
Gets the collection of table objects in the content control.
readonly tables: Word.TableCollection;Property Value
Remarks
tag
Specifies a tag to identify a content control.
tag: string;Property Value
string
Remarks
Examples
// 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
Gets the text of the content control.
readonly text: string;Property Value
string
Remarks
title
Specifies the title for a content control.
title: string;Property Value
string
Remarks
type
Gets the content control type. Only rich text, plain text, and checkbox content controls are supported currently.
readonly type: Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText";Property Value
Word.ContentControlType | "Unknown" | "RichTextInline" | "RichTextParagraphs" | "RichTextTableCell" | "RichTextTableRow" | "RichTextTable" | "PlainTextInline" | "PlainTextParagraph" | "Picture" | "BuildingBlockGallery" | "CheckBox" | "ComboBox" | "DropDownList" | "DatePicker" | "RepeatingSection" | "RichText" | "PlainText"
Remarks
Method Details
clear()
Clears the contents of the content control. The user can perform the undo operation on the cleared content.
clear(): void;Returns
void
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.
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)
Deletes the content control and its content. If keepContent is set to true, the content isn't deleted.
delete(keepContent: boolean): void;Parameters
- keepContent
-
boolean
Required. Indicates whether the content should be deleted with the content control. If keepContent is set to true, the content isn't deleted.
Returns
void
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.
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 = 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:");
console.log(contentControls.items[0]);
contentControls.items[0].delete(false);
await context.sync();
}
});
getComments()
Gets comments associated with the content control.
getComments(): Word.CommentCollection;Returns
Remarks
getContentControls(options)
Gets the currently supported child content controls in this content control.
getContentControls(options?: Word.ContentControlOptions): Word.ContentControlCollection;Parameters
- options
- Word.ContentControlOptions
Optional. Options that define which content controls are returned.
Returns
Remarks
Important: If specific types are provided in the options parameter, only content controls of supported types are returned. Be aware that an exception will be thrown on using methods of a generic Word.ContentControl that aren't relevant for the specific type. With time, additional types of content controls may be supported. Therefore, your add-in should request and handle specific types of content controls.
getHtml()
Gets an HTML representation of the content control object. When rendered in a web page or HTML viewer, the formatting will be a close, but not exact, match for of the formatting of the document. This method doesn't return the exact same HTML for the same document on different platforms (Windows, Mac, Word on the web, etc.). If you need exact fidelity, or consistency across platforms, use ContentControl.getOoxml() and convert the returned XML to HTML.
getHtml(): OfficeExtension.ClientResult<string>;Returns
OfficeExtension.ClientResult<string>
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 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()
Gets the Office Open XML (OOXML) representation of the content control object.
getOoxml(): OfficeExtension.ClientResult<string>;Returns
OfficeExtension.ClientResult<string>
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.
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);
}
});
getRange(rangeLocation)
Gets the whole content control, or the starting or ending point of the content control, as a range.
getRange(rangeLocation?: Word.RangeLocation | "Whole" | "Start" | "End" | "Before" | "After" | "Content"): Word.Range;Parameters
- rangeLocation
-
Word.RangeLocation | "Whole" | "Start" | "End" | "Before" | "After" | "Content"
Optional. The range location must be 'Whole', 'Start', 'End', 'Before', 'After', or 'Content'.
Returns
Remarks
getReviewedText(changeTrackingVersion)
Gets reviewed text based on ChangeTrackingVersion selection.
getReviewedText(changeTrackingVersion?: Word.ChangeTrackingVersion): OfficeExtension.ClientResult<string>;Parameters
- changeTrackingVersion
- Word.ChangeTrackingVersion
Optional. The value must be 'Original' or 'Current'. The default is 'Current'.
Returns
OfficeExtension.ClientResult<string>
Remarks
getReviewedText(changeTrackingVersionString)
Gets reviewed text based on ChangeTrackingVersion selection.
getReviewedText(changeTrackingVersionString?: "Original" | "Current"): OfficeExtension.ClientResult<string>;Parameters
- changeTrackingVersionString
-
"Original" | "Current"
Optional. The value must be 'Original' or 'Current'. The default is 'Current'.
Returns
OfficeExtension.ClientResult<string>
Remarks
getTextRanges(endingMarks, trimSpacing)
Gets the text ranges in the content control by using punctuation marks and/or other ending marks.
getTextRanges(endingMarks: string[], trimSpacing?: boolean): Word.RangeCollection;Parameters
- endingMarks
-
string[]
Required. The punctuation marks and/or other ending marks as an array of strings.
- trimSpacing
-
boolean
Optional. Indicates whether to trim spacing characters (spaces, tabs, column breaks, and paragraph end marks) from the start and end of the ranges returned in the range collection. Default is false which indicates that spacing characters at the start and end of the ranges are included in the range collection.
Returns
Remarks
getTrackedChanges()
Gets the collection of the TrackedChange objects in the content control.
getTrackedChanges(): Word.TrackedChangeCollection;Returns
Remarks
insertBreak(breakType, insertLocation)
Inserts a break at the specified location in the main document. This method cannot be used with 'RichTextTable', 'RichTextTableRow' and 'RichTextTableCell' content controls.
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;Parameters
- breakType
-
Word.BreakType | "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line"
Required. Type of break.
Required. The value must be 'Start', 'End', 'Before', or 'After'.
Returns
void
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.
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)
Inserts a document into the content control at the specified location.
insertFileFromBase64(base64File: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;Parameters
- base64File
-
string
Required. The Base64-encoded content of a .docx file.
Required. The value must be 'Replace', 'Start', or 'End'. 'Replace' cannot be used with 'RichTextTable' and 'RichTextTableRow' content controls.
Returns
Remarks
Note: Insertion isn't supported if the document being inserted contains an ActiveX control (likely in a form field). Consider replacing such a form field with a content control or other option appropriate for your scenario.
insertHtml(html, insertLocation)
Inserts HTML into the content control at the specified location.
insertHtml(html: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;Parameters
- html
-
string
Required. The HTML to be inserted in to the content control.
Required. The value must be 'Replace', 'Start', or 'End'. 'Replace' cannot be used with 'RichTextTable' and 'RichTextTableRow' content controls.
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.
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.');
}
});
insertInlinePictureFromBase64(base64EncodedImage, insertLocation)
Inserts an inline picture into the content control at the specified location.
insertInlinePictureFromBase64(base64EncodedImage: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.InlinePicture;Parameters
- base64EncodedImage
-
string
Required. The Base64-encoded image to be inserted in the content control.
Required. The value must be 'Replace', 'Start', or 'End'. 'Replace' cannot be used with 'RichTextTable' and 'RichTextTableRow' content controls.
Returns
Remarks
insertOoxml(ooxml, insertLocation)
Inserts OOXML into the content control at the specified location.
insertOoxml(ooxml: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;Parameters
- ooxml
-
string
Required. The OOXML to be inserted in to the content control.
Required. The value must be 'Replace', 'Start', or 'End'. 'Replace' cannot be used with 'RichTextTable' and 'RichTextTableRow' content controls.
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.
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)
Inserts a paragraph at the specified location.
insertParagraph(paragraphText: string, insertLocation: Word.InsertLocation.start | Word.InsertLocation.end | Word.InsertLocation.before | Word.InsertLocation.after | "Start" | "End" | "Before" | "After"): Word.Paragraph;Parameters
- paragraphText
-
string
Required. The paragraph text to be inserted.
Required. The value must be 'Start', 'End', 'Before', or 'After'. 'Before' and 'After' cannot be used with 'RichTextTable', 'RichTextTableRow' and 'RichTextTableCell' content controls.
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.
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.');
}
});
insertTable(rowCount, columnCount, insertLocation, values)
Inserts a table with the specified number of rows and columns into, or next to, a content control.
insertTable(rowCount: number, columnCount: number, insertLocation: Word.InsertLocation.start | Word.InsertLocation.end | Word.InsertLocation.before | Word.InsertLocation.after | "Start" | "End" | "Before" | "After", values?: string[][]): Word.Table;Parameters
- rowCount
-
number
Required. The number of rows in the table.
- columnCount
-
number
Required. The number of columns in the table.
Required. The value must be 'Start', 'End', 'Before', or 'After'. 'Before' and 'After' cannot be used with 'RichTextTable', 'RichTextTableRow' and 'RichTextTableCell' content controls.
- values
-
string[][]
Optional 2D array. Cells are filled if the corresponding strings are specified in the array.
Returns
Remarks
insertText(text, insertLocation)
Inserts text into the content control at the specified location.
insertText(text: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End"): Word.Range;Parameters
- text
-
string
Required. The text to be inserted in to the content control.
Required. The value must be 'Replace', 'Start', or 'End'. 'Replace' cannot be used with 'RichTextTable' and 'RichTextTableRow' content controls.
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.
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)
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.ContentControlLoadOptions): Word.ContentControl;Parameters
Provides options for which properties of the object to load.
Returns
Examples
// 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)
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.ContentControl;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?: {
select?: string;
expand?: string;
}): Word.ContentControl;Parameters
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
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
resetState()
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Resets the state of the content control.
resetState(): void;Returns
void
Remarks
search(searchText, searchOptions)
Performs a search with the specified SearchOptions on the scope of the content control object. The search results are a collection of range objects.
search(searchText: string, searchOptions?: Word.SearchOptions | {
ignorePunct?: boolean;
ignoreSpace?: boolean;
matchCase?: boolean;
matchPrefix?: boolean;
matchSuffix?: boolean;
matchWholeWord?: boolean;
matchWildcards?: boolean;
}): Word.RangeCollection;Parameters
- searchText
-
string
Required. The search text.
- searchOptions
-
Word.SearchOptions | { ignorePunct?: boolean; ignoreSpace?: boolean; matchCase?: boolean; matchPrefix?: boolean; matchSuffix?: boolean; matchWholeWord?: boolean; matchWildcards?: boolean; }
Optional. Options for the search.
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.
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)
Selects the content control. This causes Word to scroll to the selection.
select(selectionMode?: Word.SelectionMode): void;Parameters
- selectionMode
- Word.SelectionMode
Optional. The selection mode must be 'Select', 'Start', or 'End'. 'Select' is the default.
Returns
void
Remarks
select(selectionModeString)
Selects the content control. This causes Word to scroll to the selection.
select(selectionModeString?: "Select" | "Start" | "End"): void;Parameters
- selectionModeString
-
"Select" | "Start" | "End"
Optional. The selection mode must be 'Select', 'Start', or 'End'. 'Select' is the default.
Returns
void
Remarks
set(properties, options)
Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties: Interfaces.ContentControlUpdateData, options?: OfficeExtension.UpdateOptions): void;Parameters
- properties
- Word.Interfaces.ContentControlUpdateData
A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.
- options
- OfficeExtension.UpdateOptions
Provides an option to suppress errors if the properties object tries to set any read-only properties.
Returns
void
Examples
// 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)
Sets multiple properties on the object at the same time, based on an existing loaded object.
set(properties: Word.ContentControl): void;Parameters
- properties
- Word.ContentControl
Returns
void
setState(contentControlState)
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Sets the state of the content control.
setState(contentControlState: Word.ContentControlState): void;Parameters
- contentControlState
- Word.ContentControlState
State to be set.
Returns
void
Remarks
setState(contentControlStateString)
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Sets the state of the content control.
setState(contentControlStateString: "Error" | "Warning"): void;Parameters
- contentControlStateString
-
"Error" | "Warning"
State to be set.
Returns
void
Remarks
split(delimiters, multiParagraphs, trimDelimiters, trimSpacing)
Splits the content control into child ranges by using delimiters.
split(delimiters: string[], multiParagraphs?: boolean, trimDelimiters?: boolean, trimSpacing?: boolean): Word.RangeCollection;Parameters
- delimiters
-
string[]
Required. The delimiters as an array of strings.
- multiParagraphs
-
boolean
Optional. Indicates whether a returned child range can cover multiple paragraphs. Default is false which indicates that the paragraph boundaries are also used as delimiters.
- trimDelimiters
-
boolean
Optional. Indicates whether to trim delimiters from the ranges in the range collection. Default is false which indicates that the delimiters are included in the ranges returned in the range collection.
- trimSpacing
-
boolean
Optional. Indicates whether to trim spacing characters (spaces, tabs, column breaks, and paragraph end marks) from the start and end of the ranges returned in the range collection. Default is false which indicates that spacing characters at the start and end of the ranges are included in the range collection.
Returns
Remarks
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.ContentControl object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.ContentControlData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): Word.Interfaces.ContentControlData;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.ContentControl;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.ContentControl;Returns
Event Details
onCommentAdded
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Occurs when new comments are added.
readonly onCommentAdded: OfficeExtension.EventHandlers<Word.CommentEventArgs>;Event Type
Remarks
onCommentChanged
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Occurs when a comment or its reply is changed.
readonly onCommentChanged: OfficeExtension.EventHandlers<Word.CommentEventArgs>;Event Type
Remarks
onCommentDeselected
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Occurs when a comment is deselected.
readonly onCommentDeselected: OfficeExtension.EventHandlers<Word.CommentEventArgs>;Event Type
Remarks
onCommentSelected
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Occurs when a comment is selected.
readonly onCommentSelected: OfficeExtension.EventHandlers<Word.CommentEventArgs>;Event Type
Remarks
onDataChanged
Occurs when data within the content control are changed. To get the new text, load this content control in the handler. To get the old text, do not load it.
readonly onDataChanged: OfficeExtension.EventHandlers<Word.ContentControlDataChangedEventArgs>;Event Type
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-ondatachanged-event.yaml
await Word.run(async (context) => {
const contentControls = context.document.contentControls;
contentControls.load("items");
await context.sync();
// Register the onDataChanged event handler on each content control.
if (contentControls.items.length === 0) {
console.log("There aren't any content controls in this document so can't register event handlers.");
} else {
for (let i = 0; i < contentControls.items.length; i++) {
eventContexts[i] = contentControls.items[i].onDataChanged.add(contentControlDataChanged);
contentControls.items[i].track();
}
await context.sync();
console.log("Added event handlers for when data is changed in content controls.");
}
});
...
async function contentControlDataChanged(event: Word.ContentControlDataChangedEventArgs) {
await Word.run(async (context) => {
console.log(`${event.eventType} event detected. IDs of content controls where data was changed:`);
console.log(event.ids);
});
}
onDeleted
Occurs when the content control is deleted. Do not load this content control in the handler, otherwise you won't be able to get its original properties.
readonly onDeleted: OfficeExtension.EventHandlers<Word.ContentControlDeletedEventArgs>;Event Type
Remarks
Examples
// 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 = context.document.contentControls;
contentControls.load("items");
await context.sync();
// Register the onDeleted event handler on each content control.
if (contentControls.items.length === 0) {
console.log("There aren't any content controls in this document so can't register event handlers.");
} else {
for (let i = 0; i < contentControls.items.length; i++) {
eventContexts[i] = contentControls.items[i].onDeleted.add(contentControlDeleted);
contentControls.items[i].track();
}
await context.sync();
console.log("Added event handlers for when content controls are deleted.");
}
});
...
async function contentControlDeleted(event: Word.ContentControlDeletedEventArgs) {
await Word.run(async (context) => {
console.log(`${event.eventType} event detected. IDs of content controls that were deleted:`);
console.log(event.ids);
});
}
onEntered
Occurs when the content control is entered.
readonly onEntered: OfficeExtension.EventHandlers<Word.ContentControlEnteredEventArgs>;Event Type
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-onentered-event.yaml
await Word.run(async (context) => {
const contentControls = context.document.contentControls;
contentControls.load("items");
await context.sync();
// Register the onEntered event handler on each content control.
if (contentControls.items.length === 0) {
console.log("There aren't any content controls in this document so can't register event handlers.");
} else {
for (let i = 0; i < contentControls.items.length; i++) {
eventContexts[i] = contentControls.items[i].onEntered.add(contentControlEntered);
contentControls.items[i].track();
}
await context.sync();
console.log("Added event handlers for when the cursor is placed in content controls.");
}
});
...
async function contentControlEntered(event: Word.ContentControlEnteredEventArgs) {
await Word.run(async (context) => {
console.log(`${event.eventType} event detected. ID of content control that was entered: ${event.ids[0]}`);
});
}
onExited
Occurs when the content control is exited, for example, when the cursor leaves the content control.
readonly onExited: OfficeExtension.EventHandlers<Word.ContentControlExitedEventArgs>;Event Type
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-onexited-event.yaml
await Word.run(async (context) => {
const contentControls = context.document.contentControls;
contentControls.load("items");
await context.sync();
// Register the onExited event handler on each content control.
if (contentControls.items.length === 0) {
console.log("There aren't any content controls in this document so can't register event handlers.");
} else {
for (let i = 0; i < contentControls.items.length; i++) {
eventContexts[i] = contentControls.items[i].onExited.add(contentControlExited);
contentControls.items[i].track();
}
await context.sync();
console.log("Added event handlers for when the cursor is removed from within content controls.");
}
});
...
async function contentControlExited(event: Word.ContentControlExitedEventArgs) {
await Word.run(async (context) => {
console.log(`${event.eventType} event detected. ID of content control that was exited: ${event.ids[0]}`);
});
}
onSelectionChanged
Occurs when selection within the content control is changed.
readonly onSelectionChanged: OfficeExtension.EventHandlers<Word.ContentControlSelectionChangedEventArgs>;Event Type
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-onselectionchanged-event.yaml
await Word.run(async (context) => {
const contentControls = context.document.contentControls;
contentControls.load("items");
await context.sync();
if (contentControls.items.length === 0) {
console.log("There aren't any content controls in this document so can't register event handlers.");
} else {
for (let i = 0; i < contentControls.items.length; i++) {
eventContexts[i] = contentControls.items[i].onSelectionChanged.add(contentControlSelectionChanged);
contentControls.items[i].track();
}
await context.sync();
console.log("Added event handlers for when selections are changed in content controls.");
}
});
...
async function contentControlSelectionChanged(event: Word.ContentControlSelectionChangedEventArgs) {
await Word.run(async (context) => {
console.log(`${event.eventType} event detected. IDs of content controls where selection was changed:`);
console.log(event.ids);
});
}
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