Word JavaScript object model in Office Add-ins

This article describes concepts that are fundamental to using the Word JavaScript API to build add-ins. It introduces core concepts that are fundamental to using the API.

Important

See Using the application-specific API model to learn about the asynchronous nature of the Word APIs and how they work with the document.

Office.js APIs for Word

A Word add-in interacts with objects in Excel by using the Office JavaScript API, which includes two JavaScript object models:

  • Word JavaScript API: The Word JavaScript API provides strongly-typed objects that you can use to access the document, ranges, tables, lists, formatting, and more.

  • Common APIs: The Common API can be used to access features such as UI, dialogs, and client settings that are common across multiple types of Office applications.

While you'll likely use the Word JavaScript API to develop the majority of functionality in add-ins that target Word, you'll also use objects in the Common API. For example:

  • Context: The Context object represents the runtime environment of the add-in and provides access to key objects of the API. It consists of document configuration details such as contentLanguage and officeTheme and also provides information about the add-in's runtime environment such as host and platform. Additionally, it provides the requirements.isSetSupported() method, which you can use to check whether a specified requirement set is supported by the Excel application where the add-in is running.
  • Document: The Document object provides the getFileAsync() method, which you can use to download the Word file where the add-in is running.

Differences between the Word JS API and Common APIs.

Word-specific object model

To understand the Word APIs, you must understand how the components of a document are related to one another.

  • The Document contains the Sections, and document-level entities such as settings and custom XML parts.
  • A Section contains a Body.
  • A Body gives access to Paragraphs, ContentControls, and Range objects, among others.
  • A Range represents a contiguous area of content, including text, white space, Tables, and images. It also contains most of the text manipulation methods.
  • A List represents text in a numbered or bulleted list.

See also