Word JavaScript preview APIs
New Word JavaScript APIs are first introduced in "preview" and later become part of a specific, numbered requirement set after sufficient testing occurs and user feedback is acquired.
Important
Note that the following Word preview APIs may be available on the following platforms.
- Word on Windows
- Word on Mac
Word preview APIs are currently not supported on iPad. However, several APIs may also be available in Word on the web. For APIs available only in Word on the web, see the Web-only API list.
Note
Preview APIs are subject to change and are not intended for use in a production environment. We recommend that you try them out in test and development environments only. Do not use preview APIs in a production environment or within business-critical documents.
To use preview APIs:
- You must use the preview version of the Office JavaScript API library from the Office.js content delivery network (CDN). The type definition file for TypeScript compilation and IntelliSense is found at the CDN and DefinitelyTyped. You can install these types with
npm install --save-dev @types/office-js-preview(be sure to remove the types for@types/office-jsif you've previously installed them). - You may need to join the Microsoft 365 Insider program for access to more recent Office builds.
API list
The following table lists the Word JavaScript APIs currently in preview, except those that are available only in Word on the web. To see a complete list of all Word JavaScript APIs (including preview APIs and previously released APIs), see all Word JavaScript APIs.
| Class | Fields | Description |
|---|---|---|
| Body | insertContentControl(contentControlType?: Word.ContentControlType.richText | Word.ContentControlType.plainText | Word.ContentControlType.checkBox | Word.ContentControlType.dropDownList | Word.ContentControlType.comboBox | "RichText" | "PlainText" | "CheckBox" | "DropDownList" | "ComboBox") | Wraps the Body object with a content control. |
| ComboBoxContentControl | addListItem(displayText: string, value?: string, index?: number) | Adds a new list item to this combo box content control and returns a Word.ContentControlListItem object. |
| deleteAllListItems() | Deletes all list items in this combo box content control. | |
| listItems | Gets the collection of list items in the combo box content control. | |
| ContentControl | comboBoxContentControl | Specifies the combo box-related data if the content control's type is 'ComboBox'. |
| dropDownListContentControl | Specifies the dropdown list-related data if the content control's type is 'DropDownList'. | |
| resetState() | Resets the state of the content control. | |
| setState(contentControlState: Word.ContentControlState) | Sets the state of the content control. | |
| ContentControlListItem | delete() | Deletes the list item. |
| displayText | Specifies the display text of a list item for a dropdown list or combo box content control. | |
| index | Specifies the index location of a content control list item in the collection of list items. | |
| select() | Selects the list item and sets the text of the content control to the value of the list item. | |
| value | Specifies the programmatic value of a list item for a dropdown list or combo box content control. | |
| ContentControlListItemCollection | getFirst() | Gets the first list item in this collection. |
| getFirstOrNullObject() | Gets the first list item in this collection. | |
| items | Gets the loaded child items in this collection. | |
| DropDownListContentControl | addListItem(displayText: string, value?: string, index?: number) | Adds a new list item to this dropdown list content control and returns a Word.ContentControlListItem object. |
| deleteAllListItems() | Deletes all list items in this dropdown list content control. | |
| listItems | Gets the collection of list items in the dropdown list content control. | |
| Font | hidden | Specifies a value that indicates whether the font is tagged as hidden. |
| Paragraph | insertContentControl(contentControlType?: Word.ContentControlType.richText | Word.ContentControlType.plainText | Word.ContentControlType.checkBox | Word.ContentControlType.dropDownList | Word.ContentControlType.comboBox | "RichText" | "PlainText" | "CheckBox" | "DropDownList" | "ComboBox") | Wraps the Paragraph object with a content control. |
| Range | insertContentControl(contentControlType?: Word.ContentControlType.richText | Word.ContentControlType.plainText | Word.ContentControlType.checkBox | Word.ContentControlType.dropDownList | Word.ContentControlType.comboBox | "RichText" | "PlainText" | "CheckBox" | "DropDownList" | "ComboBox") | Wraps the Range object with a content control. |
| Style | description | Gets the description of the specified style. |
Web-only API list
The following table lists the Word JavaScript APIs currently in preview only in Word on the web. To see a complete list of all Word JavaScript APIs (including preview APIs and previously released APIs), see all Word JavaScript APIs.
| Class | Fields | Description |
|---|---|---|
| Body | onCommentAdded | Occurs when new comments are added. |
| onCommentChanged | Occurs when a comment or its reply is changed. | |
| onCommentDeleted | Occurs when comments are deleted. | |
| onCommentDeselected | Occurs when a comment is deselected. | |
| onCommentSelected | Occurs when a comment is selected. | |
| CommentDetail | id | Represents the ID of this comment. |
| replyIds | Represents the IDs of the replies to this comment. | |
| CommentEventArgs | changeType | Represents how the comment changed event is triggered. |
| commentDetails | Gets the CommentDetail array which contains the IDs and reply IDs of the involved comments. | |
| source | The source of the event. | |
| type | The event type. | |
| ContentControl | onCommentAdded | Occurs when new comments are added. |
| onCommentChanged | Occurs when a comment or its reply is changed. | |
| onCommentDeselected | Occurs when a comment is deselected. | |
| onCommentSelected | Occurs when a comment is selected. | |
| Paragraph | onCommentAdded | Occurs when new comments are added. |
| onCommentChanged | Occurs when a comment or its reply is changed. | |
| onCommentDeleted | Occurs when comments are deleted. | |
| onCommentDeselected | Occurs when a comment is deselected. | |
| onCommentSelected | Occurs when a comment is selected. | |
| Range | onCommentAdded | Occurs when new comments are added. |
| onCommentChanged | Occurs when a comment or its reply is changed. | |
| onCommentDeselected | Occurs when a comment is deselected. | |
| onCommentSelected | Occurs when a comment is selected. |
See also
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins