Edit

Share via

Word JavaScript API desktop-only requirement set 1.2

  • Article

The WordApiDesktop requirement set is a special requirement set that includes features that are only available for Word on Windows, on Mac, and on iPad. APIs in this requirement set are considered to be production APIs for the Word application on Windows, on Mac, and on iPad. They follow Microsoft 365 developer support policies. WordApiDesktop APIs are considered to be "preview" APIs for other platforms (web) and may not be supported by any of those platforms.

When APIs in the WordApiDesktop requirement set are supported across all platforms, they'll be added to the next released requirement set (WordApi 1.[NEXT]). Once that new requirement set is public, those APIs will also continue to be tagged in this WordApiDesktop requirement set. To learn more about platform-specific requirements in general, see Understanding platform-specific requirement sets.

Important

WordApiDesktop 1.2 is a desktop-only requirement set. It's a superset of the WordApi 1.9 and WordApiDesktop 1.1.

Because the WordApiDesktop 1.2 APIs are only supported by Word on Windows, on Mac, and on iPad, your add-in should check if the requirement set is supported before calling these APIs. This avoids any attempt to use desktop-only APIs on an unsupported platform.

if (Office.context.requirements.isSetSupported("WordApiDesktop", "1.2")) {
   // Any API exclusive to this WordApiDesktop requirement set.
}

Once the API is in a cross-platform requirement set, you should remove or edit the isSetSupported check. This will enable your add-in's feature on other platforms. Be sure to test the feature on those platforms when making this change.

Important

Your manifest cannot specify WordApiDesktop 1.2 as an activation requirement. It isn't a valid value to use in the Set element.

API list

The following table lists the Word JavaScript APIs currently included in the WordApiDesktop 1.2 requirement set. For a complete list of all Word JavaScript APIs (including WordApiDesktop 1.2 APIs and previously released APIs), see all Word JavaScript APIs.

Class Fields Description
Body shapes Gets the collection of shape objects in the body, including both inline and floating shapes.
Canvas id Gets an integer that represents the canvas identifier.
shape Gets the Shape object associated with the canvas.
shapes Gets the collection of Shape objects.
Document activeWindow Gets the active window for the document.
compareFromBase64(base64File: string, documentCompareOptions?: Word.DocumentCompareOptions) Displays revision marks that indicate where the specified document differs from another document.
windows Gets the collection of Word.Window objects for the document.
InsertShapeOptions height Represents the height of the shape being inserted.
left Represents the left position of the shape being inserted.
top Represents the top position of the shape being inserted.
width Represents the width of the shape being inserted.
Page getNext() Gets the next page in the pane.
getNextOrNullObject() Gets the next page.
getRange(rangeLocation?: Word.RangeLocation.whole | Word.RangeLocation.start | Word.RangeLocation.end | "Whole" | "Start" | "End") Gets the whole page, or the starting or ending point of the page, as a range.
height Gets the height, in points, of the paper defined in the Page Setup dialog box.
index Gets the index of the page.
width Gets the width, in points, of the paper defined in the Page Setup dialog box.
PageCollection getFirst() Gets the first page in this collection.
getFirstOrNullObject() Gets the first page in this collection.
items Gets the loaded child items in this collection.
Pane getNext() Gets the next pane in the window.
getNextOrNullObject() Gets the next pane.
pages Gets the collection of pages in the pane.
pagesEnclosingViewport Gets the PageCollection shown in the viewport of the pane.
PaneCollection getFirst() Gets the first pane in this collection.
getFirstOrNullObject() Gets the first pane in this collection.
items Gets the loaded child items in this collection.
Paragraph insertCanvas(insertShapeOptions?: Word.InsertShapeOptions) Inserts a floating canvas in front of text with its anchor at the beginning of the paragraph.
insertGeometricShape(geometricShapeType: Word.GeometricShapeType, insertShapeOptions?: Word.InsertShapeOptions) Inserts a geometric shape in front of text with its anchor at the beginning of the paragraph.
insertPictureFromBase64(base64EncodedImage: string, insertShapeOptions?: Word.InsertShapeOptions) Inserts a floating picture in front of text with its anchor at the beginning of the paragraph.
insertTextBox(text?: string, insertShapeOptions?: Word.InsertShapeOptions) Inserts a floating text box in front of text with its anchor at the beginning of the paragraph.
shapes Gets the collection of shape objects anchored in the paragraph, including both inline and floating shapes.
Range insertCanvas(insertShapeOptions?: Word.InsertShapeOptions) Inserts a floating canvas in front of text with its anchor at the beginning of the range.
insertGeometricShape(geometricShapeType: Word.GeometricShapeType, insertShapeOptions?: Word.InsertShapeOptions) Inserts a geometric shape in front of text with its anchor at the beginning of the range.
insertPictureFromBase64(base64EncodedImage: string, insertShapeOptions?: Word.InsertShapeOptions) Inserts a floating picture in front of text with its anchor at the beginning of the range.
insertTextBox(text?: string, insertShapeOptions?: Word.InsertShapeOptions) Inserts a floating text box in front of text with its anchor at the beginning of the range.
pages Gets the collection of pages in the range.
shapes Gets the collection of shape objects anchored in the range, including both inline and floating shapes.
Shape allowOverlap Specifies whether a given shape can overlap other shapes.
altTextDescription Specifies a string that represents the alternative text associated with the shape.
body Represents the body object of the shape.
canvas Gets the canvas associated with the shape.
delete() Deletes the shape and its content.
fill Returns the fill formatting of the shape.
geometricShapeType The geometric shape type of the shape.
height The height, in points, of the shape.
heightRelative The percentage of shape height to vertical relative size, see Word.RelativeSize.
id Gets an integer that represents the shape identifier.
isChild Check whether this shape is a child of a group shape or a canvas shape.
left The distance, in points, from the left side of the shape to the horizontal relative position, see Word.RelativeHorizontalPosition.
leftRelative The relative left position as a percentage from the left side of the shape to the horizontal relative position, see Word.RelativeHorizontalPosition.
lockAspectRatio Specifies if the aspect ratio of this shape is locked.
moveHorizontally(distance: number) Moves the shape horizontally by the number of points.
moveVertically(distance: number) Moves the shape vertically by the number of points.
name The name of the shape.
parentCanvas Gets the top-level parent canvas shape of this child shape.
parentGroup Gets the top-level parent group shape of this child shape.
relativeHorizontalPosition The relative horizontal position of the shape.
relativeHorizontalSize The relative horizontal size of the shape.
relativeVerticalPosition The relative vertical position of the shape.
relativeVerticalSize The relative vertical size of the shape.
rotation Specifies the rotation, in degrees, of the shape.
scaleHeight(scaleFactor: number, scaleType: Word.ShapeScaleType, scaleFrom?: Word.ShapeScaleFrom) Scales the height of the shape by a specified factor.
scaleWidth(scaleFactor: number, scaleType: Word.ShapeScaleType, scaleFrom?: Word.ShapeScaleFrom) Scales the width of the shape by a specified factor.
select(selectMultipleShapes?: boolean) Selects the shape.
shapeGroup Gets the shape group associated with the shape.
textFrame Gets the text frame object of the shape.
textWrap Returns the text wrap formatting of the shape.
top The distance, in points, from the top edge of the shape to the vertical relative position, see Word.RelativeVerticalPosition.
topRelative The relative top position as a percentage from the top edge of the shape to the vertical relative position, see Word.RelativeVerticalPosition.
type Gets the shape type.
visible Specifies if the shape is visible.
width The width, in points, of the shape.
widthRelative The percentage of shape width to horizontal relative size, see Word.RelativeSize.
ShapeCollection getByGeometricTypes(types: Word.GeometricShapeType[]) Gets the shapes that have the specified geometric types.
getById(id: number) Gets a shape by its identifier.
getByIdOrNullObject(id: number) Gets a shape by its identifier.
getByIds(ids: number[]) Gets the shapes by the identifiers.
getByNames(names: string[]) Gets the shapes that have the specified names.
getByTypes(types: Word.ShapeType[]) Gets the shapes that have the specified types.
getFirst() Gets the first shape in this collection.
getFirstOrNullObject() Gets the first shape in this collection.
group() Groups floating shapes in this collection, inline shapes will be skipped.
items Gets the loaded child items in this collection.
ShapeFill backgroundColor Specifies the shape fill background color.
clear() Clears the fill formatting of this shape and set it to Word.ShapeFillType.NoFill;
foregroundColor Specifies the shape fill foreground color.
setSolidColor(color: string) Sets the fill formatting of the shape to a uniform color.
transparency Specifies the transparency percentage of the fill as a value from 0.0 (opaque) through 1.0 (clear).
type Returns the fill type of the shape.
ShapeGroup id Gets an integer that represents the shape group identifier.
shape Gets the Shape object associated with the group.
shapes Gets the collection of Shape objects.
ungroup() Ungroups any grouped shapes in the specified shape group.
ShapeTextWrap bottomDistance Specifies the distance (in points) between the document text and the bottom edge of the text-free area surrounding the specified shape.
leftDistance Specifies the distance (in points) between the document text and the left edge of the text-free area surrounding the specified shape.
rightDistance Specifies the distance (in points) between the document text and the right edge of the text-free area surrounding the specified shape.
side Specifies whether the document text should wrap on both sides of the specified shape, on either the left or right side only, or on the side of the shape that's farthest from the page margin.
topDistance Specifies the distance (in points) between the document text and the top edge of the text-free area surrounding the specified shape.
type Specifies the text wrap type around the shape.
TextFrame autoSizeSetting The automatic sizing settings for the text frame.
bottomMargin Represents the bottom margin, in points, of the text frame.
hasText Specifies if the text frame contains text.
leftMargin Represents the left margin, in points, of the text frame.
noTextRotation Returns True if text in the text frame shouldn't rotate when the shape is rotated.
orientation Represents the angle to which the text is oriented for the text frame.
rightMargin Represents the right margin, in points, of the text frame.
topMargin Represents the top margin, in points, of the text frame.
verticalAlignment Represents the vertical alignment of the text frame.
wordWrap Determines whether lines break automatically to fit text inside the shape.
Window activePane Gets the active pane in the window.
panes Gets the collection of panes in the window.
WindowCollection getFirst() Gets the first window in this collection.
getFirstOrNullObject() Gets the first window in this collection.
items Gets the loaded child items in this collection.

See also