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 |
|---|---|---|
| AnnotationPopupActionEventArgs | action | Specifies the chosen action in the pop-up menu. |
| critiqueSuggestion | Specifies the accepted suggestion (only populated when accepting a critique suggestion). | |
| id | Specifies the annotation ID for which the event was fired. | |
| Border | color | Specifies the color for the border. |
| location | Gets the location of the border. | |
| type | Specifies the border type for the border. | |
| visible | Specifies whether the border is visible. | |
| width | Specifies the width for the border. | |
| BorderCollection | getByLocation(borderLocation: Word.BorderLocation.top | Word.BorderLocation.left | Word.BorderLocation.bottom | Word.BorderLocation.right | Word.BorderLocation.insideHorizontal | Word.BorderLocation.insideVertical | "Top" | "Left" | "Bottom" | "Right" | "InsideHorizontal" | "InsideVertical") | Gets the border that has the specified location. |
| getFirst() | Gets the first border in this collection. | |
| getFirstOrNullObject() | Gets the first border in this collection. | |
| getItem(index: number) | Gets a Border object by its index in the collection. | |
| insideBorderColor | Specifies the 24-bit color of the inside borders. | |
| insideBorderType | Specifies the border type of the inside borders. | |
| insideBorderWidth | Specifies the width of the inside borders. | |
| items | Gets the loaded child items in this collection. | |
| outsideBorderColor | Specifies the 24-bit color of the outside borders. | |
| outsideBorderType | Specifies the border type of the outside borders. | |
| outsideBorderWidth | Specifies the width of the outside borders. | |
| ContentControlAddedEventArgs | eventType | The event type. |
| ContentControlDataChangedEventArgs | eventType | The event type. |
| ContentControlDeletedEventArgs | eventType | The event type. |
| ContentControlEnteredEventArgs | eventType | The event type. |
| ContentControlEventArgs | contentControl | The object that raised the event. |
| eventType | The event type. | |
| ids | Gets the content control IDs. | |
| source | The source of the event. | |
| ContentControlExitedEventArgs | eventType | The event type. |
| ContentControlSelectionChangedEventArgs | eventType | The event type. |
| Critique | popupOptions | Specifies the behavior of the pop-up menu for the critique. |
| CritiquePopupOptions | brandingTextResourceId | Gets the manifest resource ID of the string to use for branding. |
| subtitleResourceId | Gets the manifest resource ID of the string to use as the subtitle. | |
| suggestions | Gets the suggestions to display in the critique pop-up menu. | |
| titleResourceId | Gets the manifest resource ID of the string to use as the title. | |
| Document | compare(filePath: string, documentCompareOptions?: Word.DocumentCompareOptions) | Displays revision marks that indicate where the specified document differs from another document. |
| onAnnotationPopupAction | Occurs when the user performs an action in an annotation pop-up menu. | |
| DocumentCompareOptions | addToRecentFiles | True adds the document to the list of recently used files on the File menu. |
| authorName | The reviewer name associated with the differences generated by the comparison. | |
| compareTarget | The target document for the comparison. | |
| detectFormatChanges | True (default) for the comparison to include detection of format changes. | |
| ignoreAllComparisonWarnings | True compares the documents without notifying a user of problems. | |
| removeDateAndTime | True removes date and time stamp information from tracked changes in the returned Document object. | |
| removePersonalInformation | True removes all user information from comments, revisions, and the properties dialog box in the returned Document object. | |
| Field | showCodes | Specifies whether the field codes are displayed for the specified field. |
| Font | hidden | Specifies a value that indicates whether the font is tagged as hidden. |
| InlinePicture | imageFormat | Gets the format of the inline image. |
| 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. | |
| ListLevel | alignment | Specifies the horizontal alignment of the list level. |
| font | Gets a Font object that represents the character formatting of the specified object. | |
| linkedStyle | Specifies the name of the style that's linked to the specified list level object. | |
| numberFormat | Specifies the number format for the specified list level. | |
| numberPosition | Specifies the position (in points) of the number or bullet for the specified list level object. | |
| numberStyle | Specifies the number style for the list level object. | |
| resetOnHigher | Specifies the list level that must appear before the specified list level restarts numbering at 1. | |
| startAt | Specifies the starting number for the specified list level object. | |
| tabPosition | Specifies the tab position for the specified list level object. | |
| textPosition | Specifies the position (in points) for the second line of wrapping text for the specified list level object. | |
| trailingCharacter | Specifies the character inserted after the number for the specified list level. | |
| ListLevelCollection | getFirst() | Gets the first list level in this collection. |
| getFirstOrNullObject() | Gets the first list level in this collection. | |
| items | Gets the loaded child items in this collection. | |
| ListTemplate | listLevels | Gets a ListLevels collection that represents all the levels for the specified ListTemplate. |
| outlineNumbered | Specifies whether the specified ListTemplate object is outline numbered. | |
| ParagraphAddedEventArgs | type | The event type. |
| ParagraphChangedEventArgs | type | The event type. |
| ParagraphDeletedEventArgs | type | The event type. |
| Range | highlight() | Highlights the range temporarily without changing document content. |
| removeHighlight() | Removes the highlight added by the Highlight function if any. | |
| Shading | foregroundPatternColor | Specifies the color for the foreground of the object. |
| texture | Specifies the shading texture of the object. | |
| Style | borders | Specifies a BorderCollection object that represents all the borders for the specified style. |
| description | Gets the description of the specified style. | |
| listTemplate | Gets a ListTemplate object that represents the list formatting for the specified Style object. | |
| TableRow | insertContentControl() | Inserts a content control on the row. |
| TableStyle | alignment | Specifies the table's alignment against the page margin. |
| allowBreakAcrossPage | Specifies whether lines in tables formatted with a specified style break across pages. |
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
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