Word JavaScript preview APIs
- 5 minutes to read
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.
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 reference the beta library on the CDN (https://appsforoffice.microsoft.com/lib/beta/hosted/office.js). 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. - You may need to join the Office Insider program for access to more recent Office builds.
API list
The following table lists the Word JavaScript APIs currently in preview. 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 |
|---|---|---|
| ContentControl | 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. |
| 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. | |
| onSelectionChanged | Occurs when selection within the content control is changed. | |
| ContentControlEventArgs | contentControl | The object that raised the event. Load this object to get its properties. |
| eventType | The event type. See Word.EventType for details. | |
| CustomXmlPart | delete() | Deletes the custom XML part. |
| deleteAttribute(xpath: string, namespaceMappings: any, name: string) | Deletes an attribute with the given name from the element identified by xpath. | |
| deleteElement(xpath: string, namespaceMappings: any) | Deletes the element identified by xpath. | |
| getXml() | Gets the full XML content of the custom XML part. | |
| insertAttribute(xpath: string, namespaceMappings: any, name: string, value: string) | Inserts an attribute with the given name and value to the element identified by xpath. | |
| insertElement(xpath: string, xml: string, namespaceMappings: any, index?: number) | Inserts the given XML under the parent element identified by xpath at child position index. | |
| query(xpath: string, namespaceMappings: any) | Queries the XML content of the custom XML part. | |
| id | Gets the ID of the custom XML part. Read only. | |
| namespaceUri | Gets the namespace URI of the custom XML part. Read only. | |
| setXml(xml: string) | Sets the full XML content of the custom XML part. | |
| updateAttribute(xpath: string, namespaceMappings: any, name: string, value: string) | Updates the value of an attribute with the given name of the element identified by xpath. | |
| updateElement(xpath: string, xml: string, namespaceMappings: any) | Updates the XML of the element identified by xpath. | |
| CustomXmlPartCollection | add(xml: string) | Adds a new custom XML part to the document. |
| getByNamespace(namespaceUri: string) | Gets a new scoped collection of custom XML parts whose namespaces match the given namespace. | |
| getCount() | Gets the number of items in the collection. | |
| getItem(id: string) | Gets a custom XML part based on its ID. Read only. | |
| getItemOrNullObject(id: string) | Gets a custom XML part based on its ID. Returns a null object if the CustomXmlPart does not exist. | |
| items | Gets the loaded child items in this collection. | |
| CustomXmlPartScopedCollection | getCount() | Gets the number of items in the collection. |
| getItem(id: string) | Gets a custom XML part based on its ID. Read only. | |
| getItemOrNullObject(id: string) | Gets a custom XML part based on its ID. Returns a null object if the CustomXmlPart does not exist in the collection. | |
| getOnlyItem() | If the collection contains exactly one item, this method returns it. Otherwise, this method produces an error. | |
| getOnlyItemOrNullObject() | If the collection contains exactly one item, this method returns it. Otherwise, this method returns a null object. | |
| items | Gets the loaded child items in this collection. | |
| Document | deleteBookmark(name: string) | Deletes a bookmark, if exists, from the document. |
| getBookmarkRange(name: string) | Gets a bookmark's range. Throws if the bookmark does not exist. | |
| getBookmarkRangeOrNullObject(name: string) | Gets a bookmark's range. Returns a null object if the bookmark does not exist. | |
| customXmlParts | Gets the custom XML parts in the document. Read-only. | |
| onContentControlAdded | Occurs when a content control is added. Run context.sync() in the handler to get the new content control's properties. | |
| settings | Gets the add-in's settings in the document. Read-only. | |
| DocumentCreated | deleteBookmark(name: string) | Deletes a bookmark, if exists, from the document. |
| getBookmarkRange(name: string) | Gets a bookmark's range. Throws if the bookmark does not exist. | |
| getBookmarkRangeOrNullObject(name: string) | Gets a bookmark's range. Returns a null object if the bookmark does not exist. | |
| customXmlParts | Gets the custom XML parts in the document. Read-only. | |
| settings | Gets the add-in's settings in the document. Read-only. | |
| InlinePicture | imageFormat | Gets the format of the inline image. Read-only. |
| List | getLevelFont(level: number) | Gets the font of the bullet, number or picture at the specified level in the list. |
| getLevelPicture(level: number) | Gets the base64 encoded string representation of the picture at the specified level in the list. | |
| resetLevelFont(level: number, resetFontName?: boolean) | Resets the font of the bullet, number or picture at the specified level in the list. | |
| setLevelPicture(level: number, base64EncodedImage?: string) | Sets the picture at the specified level in the list. | |
| Range | getBookmarks(includeHidden?: boolean, includeAdjacent?: boolean) | Gets the names all bookmarks in or overlapping the range. A bookmark is hidden if its name starts with the underscore character. |
| insertBookmark(name: string) | Inserts a bookmark on the range. If a bookmark of the same name exists somewhere, it is deleted first. | |
| Setting | delete() | Deletes the setting. |
| key | Gets the key of the setting. Read only. | |
| value | Gets or sets the value of the setting. | |
| SettingCollection | add(key: string, value: any) | Creates a new setting or sets an existing setting. |
| deleteAll() | Deletes all settings in this add-in. | |
| getCount() | Gets the count of settings. | |
| getItem(key: string) | Gets a setting object by its key, which is case-sensitive. Throws if the setting does not exist. | |
| getItemOrNullObject(key: string) | Gets a setting object by its key, which is case-sensitive. Returns a null object if the setting does not exist. | |
| items | Gets the loaded child items in this collection. | |
| Table | mergeCells(topRow: number, firstCell: number, bottomRow: number, lastCell: number) | Merges the cells bounded inclusively by a first and last cell. |
| TableCell | split(rowCount: number, columnCount: number) | Splits the cell into the specified number of rows and columns. |
| TableRow | insertContentControl() | Inserts a content control on the row. |
| merge() | Merges the row into one cell. |