Word.Document class

Gets the name of the active theme and formatting options.

readonly activeTheme: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the display name of the active theme.

readonly activeThemeDisplayName: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the active window for the document.

readonly activeWindow: Word.Window;

Property Value

Remarks

[ API set: WordApiDesktop 1.2 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/35-ranges/get-pages.yaml

await Word.run(async (context) => {
  // Gets the first paragraph of each page.
  console.log("Getting first paragraph of each page...");

  // Get the active window.
  const activeWindow: Word.Window = context.document.activeWindow;
  activeWindow.load();

  // Get the active pane.
  const activePane: Word.Pane = activeWindow.activePane;
  activePane.load();

  // Get all pages.
  const pages: Word.PageCollection = activePane.pages;
  pages.load();

  await context.sync();

  // Get page index and paragraphs of each page.
  const pagesIndexes = [];
  const pagesNumberOfParagraphs = [];
  const pagesFirstParagraphText = [];
  for (let i = 0; i < pages.items.length; i++) {
    const page = pages.items[i];
    page.load("index");
    pagesIndexes.push(page);

    const paragraphs = page.getRange().paragraphs;
    paragraphs.load("items/length");
    pagesNumberOfParagraphs.push(paragraphs);

    const firstParagraph = paragraphs.getFirst();
    firstParagraph.load("text");
    pagesFirstParagraphText.push(firstParagraph);
  }

  await context.sync();

  for (let i = 0; i < pagesIndexes.length; i++) {
    console.log(`Page index: ${pagesIndexes[i].index}`);
    console.log(`Number of paragraphs: ${pagesNumberOfParagraphs[i].items.length}`);
    console.log("First paragraph's text:", pagesFirstParagraphText[i].text);
  }
});

Gets whether Word encrypts file properties for password-protected documents.

readonly areFilePropertiesPasswordEncrypted: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether grammatical errors are marked by a wavy green line in the document.

areGrammaticalErrorsShown: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to use the default math settings when creating new equations.

areMathDefaultsUsed: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to disable features introduced after a specified version.

areNewerFeaturesDisabled: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Microsoft Word underlines spelling errors in the document.

areSpellingErrorsShown: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether the styles in this document are updated to match the styles in the attached template each time the document is opened.

areStylesUpdatedOnOpen: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Microsoft Word embeds TrueType fonts in the document when it's saved.

areTrueTypeFontsEmbedded: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies a Template object that represents the template attached to the document.

attachedTemplate: Word.Template;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Specifies if automatic hyphenation is turned on for the document.

autoHyphenation: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Specifies if the edits in the document are automatically saved.

autoSaveOn: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Gets a Shape object that represents the background image for the document.

readonly background: Word.Shape;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a Bibliography object that represents the bibliography references contained within the document.

readonly bibliography: Word.Bibliography;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Gets the Body object of the main document. The body is the text that excludes headers, footers, footnotes, textboxes, etc.

readonly body: Word.Body;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Returns a BookmarkCollection object that represents all the bookmarks in the document.

readonly bookmarks: Word.BookmarkCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a DocumentProperties object that represents all the built-in document properties for the document.

readonly builtInDocumentProperties: Word.DocumentProperties;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the ChangeTracking mode.

changeTrackingMode: Word.ChangeTrackingMode | "Off" | "TrackAll" | "TrackMineOnly";

Property Value

Remarks

[ API set: WordApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-change-tracking.yaml

// Gets the current change tracking mode.
await Word.run(async (context) => {
  const document: Word.Document = context.document;
  document.load("changeTrackingMode");
  await context.sync();

  if (document.changeTrackingMode === Word.ChangeTrackingMode.trackMineOnly) {
    console.log("Only my changes are being tracked.");
  } else if (document.changeTrackingMode === Word.ChangeTrackingMode.trackAll) {
    console.log("Everyone's changes are being tracked.");
  } else {
    console.log("No changes are being tracked.");
  }
});

Gets the RangeScopedCollection object that represents all the characters in the document.

readonly characters: Word.RangeScopedCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a Coauthoring object for managing coauthoring in the document.

readonly coauthoring: Word.Coauthoring;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the code name for the document.

readonly codeName: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a CommentCollection object that represents all the comments in the document.

readonly comments: Word.CommentCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the compatibility mode that Word uses when opening the document.

readonly compatibilityMode: Word.CompatibilityMode | "Word2003" | "Word2007" | "Word2010" | "Word2013" | "Current";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the maximum number of consecutive lines that can end with hyphens.

consecutiveHyphensLimit: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Gets a Range object that represents the main document story.

readonly content: Word.Range;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the collection of ContentControl objects in the document. This includes content controls in the body of the document, headers, footers, textboxes, etc.

readonly contentControls: Word.ContentControlCollection;

Property Value

Remarks

[ API set: WordApi 1.1 ]

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Gets a random number that Word assigns to changes in the document.

readonly currentRsid: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a DocumentProperties collection that represents all the custom document properties for the document.

readonly customDocumentProperties: Word.DocumentProperties;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the custom XML parts in the document.

readonly customXmlParts: Word.CustomXmlPartCollection;

Property Value

Remarks

[ API set: WordApi 1.4 ]

Specifies the interval (in points) between the default tab stops in the document.

defaultTabStop: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the browser frame for displaying a webpage via hyperlink.

defaultTargetFrame: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a DocumentLibraryVersionCollection object that represents the collection of versions of a shared document that has versioning enabled and that's stored in a document library on a server.

readonly documentLibraryVersions: Word.DocumentLibraryVersionCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Specifies whether Word should not embed common system fonts.

doNotEmbedSystemFonts: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the name of the algorithm encryption provider that Microsoft Word uses when encrypting documents.

encryptionProvider: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the East Asian language used for line breaking.

farEastLineBreakLanguage: Word.FarEastLineBreakLanguageId | "TraditionalChinese" | "Japanese" | "Korean" | "SimplifiedChinese";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the line break control level.

farEastLineBreakLevel: Word.FarEastLineBreakLevel | "Normal" | "Strict" | "Custom";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a FieldCollection object that represents all the fields in the document.

readonly fields: Word.FieldCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Word shows the next heading level when the previous is used.

formattingIsNextLevelShown: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to show user-defined styles.

formattingIsUserStyleNameShown: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a FrameCollection object that represents all the frames in the document.

readonly frames: Word.FrameCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Gets the name of a document, including the path.

readonly fullName: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a RangeCollection object that represents the sentences that failed the grammar check in the document.

readonly grammaticalErrors: Word.RangeCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the horizontal space between invisible gridlines that Microsoft Word uses when you draw, move, and resize AutoShapes or East Asian characters in the document.

gridDistanceHorizontal: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the vertical space between invisible gridlines that Microsoft Word uses when you draw, move, and resize AutoShapes or East Asian characters in the document.

gridDistanceVertical: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether the character grid starts from the upper-left corner of the page.

gridIsOriginFromMargin: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the horizontal origin point for the invisible grid.

gridOriginHorizontal: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the vertical origin point for the invisible grid.

gridOriginVertical: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the interval for horizontal character gridlines in print layout view.

gridSpaceBetweenHorizontalLines: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the interval for vertical character gridlines in print layout view.

gridSpaceBetweenVerticalLines: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether a password is required to open the document.

readonly hasPassword: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether the document has an attached Microsoft Visual Basic for Applications project.

readonly hasVbProject: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a HyperlinkCollection object that represents all the hyperlinks in the document.

readonly hyperlinks: Word.HyperlinkCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Specifies whether words in all capital letters can be hyphenated.

hyphenateCaps: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Specifies the width of the hyphenation zone, in points.

hyphenationZone: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns an IndexCollection object that represents all the indexes in the document.

readonly indexes: Word.IndexCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether automatic formatting options override formatting restrictions.

isAutoFormatOverrideOn: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether charts in the active document use cell-reference data-point tracking.

isChartDataPointTracked: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether the compatibility option specified by the type property is enabled.

isCompatible: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether the document is final.

isFinal: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Microsoft Word saves a subset of the embedded TrueType fonts with the document.

isFontsSubsetSaved: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Microsoft Word prints onto a preprinted form only the data entered in the corresponding online form.

isFormsDataPrinted: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Microsoft Word saves the data entered in a form as a tab-delimited record for use in a database.

isFormsDataSaved: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether a grammar check has been run on the document.

isGrammarChecked: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether the most recent firing of the Application.DocumentBeforeSave event was the result of an automatic save by the document or a manual save by the user.

readonly isInAutoSave: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether the document is in form design mode.

readonly isInFormsDesign: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Word kerns half-width Latin characters and punctuation marks.

isKerningByAlgorithm: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to embed speech and handwriting data.

isLinguisticDataEmbedded: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether this document is a master document.

readonly isMasterDocument: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Word optimizes the document for Word 97.

isOptimizedForWord97: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether PRINT field instructions (such as PostScript commands) in the document are to be printed on top of text and graphics when a PostScript printer is used.

isPostScriptPrintedOverText: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether users can change the Quick Style set.

isQuickStyleSetLocked: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether changes to the document cannot be saved to the original document.

readonly isReadOnly: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Microsoft Word displays a message box whenever a user opens the document, suggesting that it be opened as read-only.

isReadOnlyRecommended: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether AutoShapes or East Asian characters are automatically aligned with an invisible grid.

isSnappedToGrid: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether AutoShapes or East Asian characters align with invisible gridlines through other shapes.

isSnappedToShapes: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether spelling has been checked throughout the document.

isSpellingChecked: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether formatting restrictions are enforced in a protected document.

isStyleEnforced: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether this document is a subdocument of a master document.

readonly isSubdocument: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether users can change the document theme.

isThemeLocked: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether the document was created or opened by the user.

isUserControl: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether the VBA project is digitally signed.

readonly isVbaSigned: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets whether the document is protected with a write password.

readonly isWriteReserved: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the character spacing adjustment.

justificationMode: Word.JustificationMode | "Expand" | "Compress" | "CompressKana";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the format type that Microsoft Word uses when automatically formatting the document.

kind: Word.DocumentKind | "NotSpecified" | "Letter" | "Email";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Microsoft Word has detected the language of the document text.

languageDetected: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Gets a ParagraphCollection object that represents all the numbered paragraphs in the document.

readonly listParagraphs: Word.ParagraphCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a ListCollection object that contains all the formatted lists in the document.

readonly lists: Word.ListCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a ListTemplateCollection object that represents all the list templates in the document.

readonly listTemplates: Word.ListTemplateCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the kinsoku characters after which Word will not break a line.

noLineBreakAfter: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the kinsoku characters before which Word will not break a line.

noLineBreakBefore: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the encoding used to open the document.

readonly openEncoding: Word.DocumentEncoding | "Thai" | "JapaneseShiftJis" | "SimplifiedChineseGbk" | "Korean" | "TraditionalChineseBig5" | "UnicodeLittleEndian" | "UnicodeBigEndian" | "CentralEuropean" | "Cyrillic" | "Western" | "Greek" | "Turkish" | "Hebrew" | "Arabic" | "Baltic" | "Vietnamese" | "AutoDetect" | "JapaneseAutoDetect" | "SimplifiedChineseAutoDetect" | "KoreanAutoDetect" | "TraditionalChineseAutoDetect" | "CyrillicAutoDetect" | "GreekAutoDetect" | "ArabicAutoDetect" | "Iso88591Latin1" | "Iso88592CentralEurope" | "Iso88593Latin3" | "Iso88594Baltic" | "Iso88595Cyrillic" | "Iso88596Arabic" | "Iso88597Greek" | "Iso88598Hebrew" | "Iso88599Turkish" | "Iso885915Latin9" | "Iso88598HebrewLogical" | "Iso2022JpNoHalfwidthKatakana" | "Iso2022JpJisX02021984" | "Iso2022JpJisX02011989" | "Iso2022Kr" | "Iso2022CnTraditionalChinese" | "Iso2022CnSimplifiedChinese" | "MacRoman" | "MacJapanese" | "MacTraditionalChineseBig5" | "MacKorean" | "MacArabic" | "MacHebrew" | "MacGreek1" | "MacCyrillic" | "MacSimplifiedChineseGb2312" | "MacRomania" | "MacUkraine" | "MacLatin2" | "MacIcelandic" | "MacTurkish" | "MacCroatia" | "EbcdicUsCanada" | "EbcdicInternational" | "EbcdicMultilingualRoeceLatin2" | "EbcdicGreekModern" | "EbcdicTurkishLatin5" | "EbcdicGermany" | "EbcdicDenmarkNorway" | "EbcdicFinlandSweden" | "EbcdicItaly" | "EbcdicLatinAmericaSpain" | "EbcdicUnitedKingdom" | "EbcdicJapaneseKatakanaExtended" | "EbcdicFrance" | "EbcdicArabic" | "EbcdicGreek" | "EbcdicHebrew" | "EbcdicKoreanExtended" | "EbcdicThai" | "EbcdicIcelandic" | "EbcdicTurkish" | "EbcdicRussian" | "EbcdicSerbianBulgarian" | "EbcdicJapaneseKatakanaExtendedAndJapanese" | "EbcdicUsCanadaAndJapanese" | "EbcdicKoreanExtendedAndKorean" | "EbcdicSimplifiedChineseExtendedAndSimplifiedChinese" | "EbcdicUsCanadaAndTraditionalChinese" | "EbcdicJapaneseLatinExtendedAndJapanese" | "OemUnitedStates" | "OemGreek437G" | "OemBaltic" | "OemMultilingualLatinI" | "OemMultilingualLatinIi" | "OemCyrillic" | "OemTurkish" | "OemPortuguese" | "OemIcelandic" | "OemHebrew" | "OemCanadianFrench" | "OemArabic" | "OemNordic" | "OemCyrillicIi" | "OemModernGreek" | "EucJapanese" | "EucChineseSimplifiedChinese" | "EucKorean" | "EucTaiwaneseTraditionalChinese" | "IsciiDevanagari" | "IsciiBengali" | "IsciiTamil" | "IsciiTelugu" | "IsciiAssamese" | "IsciiOriya" | "IsciiKannada" | "IsciiMalayalam" | "IsciiGujarati" | "IsciiPunjabi" | "ArabicAsmo" | "ArabicTransparentAsmo" | "KoreanJohab" | "TaiwanCns" | "TaiwanTca" | "TaiwanEten" | "TaiwanIbm5550" | "TaiwanTeleText" | "TaiwanWang" | "Ia5Irv" | "Ia5German" | "Ia5Swedish" | "Ia5Norwegian" | "UsaAscii" | "T61" | "Iso6937NonSpacingAccent" | "Koi8R" | "ExtAlphaLowercase" | "Koi8U" | "Europa3" | "HzGbSimplifiedChinese" | "SimplifiedChineseGb18030" | "Utf7" | "Utf8";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the title of the original document after legal-blackline comparison.

readonly originalDocumentTitle: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a PageSetup object that's associated with the document.

readonly pageSetup: Word.PageSetup;

Property Value

Remarks

[ API set: WordApiDesktop 1.3 ]

Gets a ParagraphCollection object that represents all the paragraphs in the document.

readonly paragraphs: Word.ParagraphCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Sets a password that must be supplied to open the document.

password: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the algorithm used for password encryption.

readonly passwordEncryptionAlgorithm: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the key length used for password encryption.

readonly passwordEncryptionKeyLength: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the name of the password encryption provider.

readonly passwordEncryptionProvider: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the disk or the web path to the document (excludes the document name).

readonly path: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether revision marks are printed with the document.

printRevisions: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the properties of the document.

readonly properties: Word.DocumentProperties;

Property Value

Remarks

[ API set: WordApi 1.3 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/30-properties/get-built-in-properties.yaml

await Word.run(async (context) => {
    const builtInProperties: Word.DocumentProperties = context.document.properties;
    builtInProperties.load("*"); // Let's get all!

    await context.sync();
    console.log(JSON.stringify(builtInProperties, null, 4));
});

Gets the protection type for the document.

readonly protectionType: Word.ProtectionType | "NoProtection" | "AllowOnlyRevisions" | "AllowOnlyComments" | "AllowOnlyFormFields" | "AllowOnlyReading";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a ReadabilityStatisticCollection object that represents the readability statistics for the document.

readonly readabilityStatistics: Word.ReadabilityStatisticCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the width of pages in reading layout view when frozen.

readingLayoutSizeX: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the height of pages in reading layout view when frozen.

readingLayoutSizeY: number;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether pages in reading layout view are frozen for handwritten markup.

readingModeIsLayoutFrozen: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether Word removes user information upon saving.

removePersonalInformationOnSave: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the title of the revised document after legal-blackline comparison.

readonly revisedDocumentTitle: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the collection of revisions that represents the tracked changes in the document.

readonly revisions: Word.RevisionCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Indicates whether the changes in the document have been saved. A value of true indicates that the document hasn't changed since it was saved.

readonly saved: boolean;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Specifies the encoding used when saving the document.

saveEncoding: Word.DocumentEncoding | "Thai" | "JapaneseShiftJis" | "SimplifiedChineseGbk" | "Korean" | "TraditionalChineseBig5" | "UnicodeLittleEndian" | "UnicodeBigEndian" | "CentralEuropean" | "Cyrillic" | "Western" | "Greek" | "Turkish" | "Hebrew" | "Arabic" | "Baltic" | "Vietnamese" | "AutoDetect" | "JapaneseAutoDetect" | "SimplifiedChineseAutoDetect" | "KoreanAutoDetect" | "TraditionalChineseAutoDetect" | "CyrillicAutoDetect" | "GreekAutoDetect" | "ArabicAutoDetect" | "Iso88591Latin1" | "Iso88592CentralEurope" | "Iso88593Latin3" | "Iso88594Baltic" | "Iso88595Cyrillic" | "Iso88596Arabic" | "Iso88597Greek" | "Iso88598Hebrew" | "Iso88599Turkish" | "Iso885915Latin9" | "Iso88598HebrewLogical" | "Iso2022JpNoHalfwidthKatakana" | "Iso2022JpJisX02021984" | "Iso2022JpJisX02011989" | "Iso2022Kr" | "Iso2022CnTraditionalChinese" | "Iso2022CnSimplifiedChinese" | "MacRoman" | "MacJapanese" | "MacTraditionalChineseBig5" | "MacKorean" | "MacArabic" | "MacHebrew" | "MacGreek1" | "MacCyrillic" | "MacSimplifiedChineseGb2312" | "MacRomania" | "MacUkraine" | "MacLatin2" | "MacIcelandic" | "MacTurkish" | "MacCroatia" | "EbcdicUsCanada" | "EbcdicInternational" | "EbcdicMultilingualRoeceLatin2" | "EbcdicGreekModern" | "EbcdicTurkishLatin5" | "EbcdicGermany" | "EbcdicDenmarkNorway" | "EbcdicFinlandSweden" | "EbcdicItaly" | "EbcdicLatinAmericaSpain" | "EbcdicUnitedKingdom" | "EbcdicJapaneseKatakanaExtended" | "EbcdicFrance" | "EbcdicArabic" | "EbcdicGreek" | "EbcdicHebrew" | "EbcdicKoreanExtended" | "EbcdicThai" | "EbcdicIcelandic" | "EbcdicTurkish" | "EbcdicRussian" | "EbcdicSerbianBulgarian" | "EbcdicJapaneseKatakanaExtendedAndJapanese" | "EbcdicUsCanadaAndJapanese" | "EbcdicKoreanExtendedAndKorean" | "EbcdicSimplifiedChineseExtendedAndSimplifiedChinese" | "EbcdicUsCanadaAndTraditionalChinese" | "EbcdicJapaneseLatinExtendedAndJapanese" | "OemUnitedStates" | "OemGreek437G" | "OemBaltic" | "OemMultilingualLatinI" | "OemMultilingualLatinIi" | "OemCyrillic" | "OemTurkish" | "OemPortuguese" | "OemIcelandic" | "OemHebrew" | "OemCanadianFrench" | "OemArabic" | "OemNordic" | "OemCyrillicIi" | "OemModernGreek" | "EucJapanese" | "EucChineseSimplifiedChinese" | "EucKorean" | "EucTaiwaneseTraditionalChinese" | "IsciiDevanagari" | "IsciiBengali" | "IsciiTamil" | "IsciiTelugu" | "IsciiAssamese" | "IsciiOriya" | "IsciiKannada" | "IsciiMalayalam" | "IsciiGujarati" | "IsciiPunjabi" | "ArabicAsmo" | "ArabicTransparentAsmo" | "KoreanJohab" | "TaiwanCns" | "TaiwanTca" | "TaiwanEten" | "TaiwanIbm5550" | "TaiwanTeleText" | "TaiwanWang" | "Ia5Irv" | "Ia5German" | "Ia5Swedish" | "Ia5Norwegian" | "UsaAscii" | "T61" | "Iso6937NonSpacingAccent" | "Koi8R" | "ExtAlphaLowercase" | "Koi8U" | "Europa3" | "HzGbSimplifiedChinese" | "SimplifiedChineseGb18030" | "Utf7" | "Utf8";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the file format of the document.

readonly saveFormat: Word.FileSaveFormat | "Document" | "Template" | "Text" | "TextLineBreaks" | "DosText" | "DosTextLineBreaks" | "Rtf" | "UnicodeText" | "Html" | "WebArchive" | "FilteredHtml" | "Xml" | "XmlDocument" | "XmlDocumentMacroEnabled" | "XmlTemplate" | "XmlTemplateMacroEnabled" | "DocumentDefault" | "Pdf" | "Xps" | "FlatXml" | "FlatXmlMacroEnabled" | "FlatXmlTemplate" | "FlatXmlTemplateMacroEnabled" | "OpenDocumentText" | "StrictOpenXmlDocument";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the collection of Section objects in the document.

readonly sections: Word.SectionCollection;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Returns a Selection object that represents the current selection in the document.

readonly selection: Word.Selection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the RangeScopedCollection object that represents all the sentences in the document.

readonly sentences: Word.RangeScopedCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the add-in's settings in the document.

readonly settings: Word.SettingCollection;

Property Value

Remarks

[ API set: WordApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-settings.yaml

// Gets all custom settings this add-in set on this document.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  settings.load("items");
  await context.sync();

  if (settings.items.length == 0) {
    console.log("There are no settings.");
  } else {
    console.log("All settings:");
    for (let i = 0; i < settings.items.length; i++) {
      console.log(settings.items[i]);
    }
  }
});

Gets a RangeCollection object that represents the words identified as spelling errors in the document.

readonly spellingErrors: Word.RangeCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a RangeCollection object that represents all the stories in the document.

readonly storyRanges: Word.RangeCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a StyleCollection for the document.

readonly styles: Word.StyleCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a TableOfAuthoritiesCategoryCollection object that represents the available table of authorities categories in the document.

readonly tableOfAuthoritiesCategories: Word.TableOfAuthoritiesCategoryCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets a TableCollection object that represents all the tables in the document.

readonly tables: Word.TableCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a TableOfAuthoritiesCollection object that represents all the tables of authorities in the document.

readonly tablesOfAuthorities: Word.TableOfAuthoritiesCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a TableOfContentsCollection object that represents all the tables of contents in the document.

readonly tablesOfContents: Word.TableOfContentsCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a TableOfFiguresCollection object that represents all the tables of figures in the document.

readonly tablesOfFigures: Word.TableOfFiguresCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the encoding for saving as encoded text.

textEncoding: Word.DocumentEncoding | "Thai" | "JapaneseShiftJis" | "SimplifiedChineseGbk" | "Korean" | "TraditionalChineseBig5" | "UnicodeLittleEndian" | "UnicodeBigEndian" | "CentralEuropean" | "Cyrillic" | "Western" | "Greek" | "Turkish" | "Hebrew" | "Arabic" | "Baltic" | "Vietnamese" | "AutoDetect" | "JapaneseAutoDetect" | "SimplifiedChineseAutoDetect" | "KoreanAutoDetect" | "TraditionalChineseAutoDetect" | "CyrillicAutoDetect" | "GreekAutoDetect" | "ArabicAutoDetect" | "Iso88591Latin1" | "Iso88592CentralEurope" | "Iso88593Latin3" | "Iso88594Baltic" | "Iso88595Cyrillic" | "Iso88596Arabic" | "Iso88597Greek" | "Iso88598Hebrew" | "Iso88599Turkish" | "Iso885915Latin9" | "Iso88598HebrewLogical" | "Iso2022JpNoHalfwidthKatakana" | "Iso2022JpJisX02021984" | "Iso2022JpJisX02011989" | "Iso2022Kr" | "Iso2022CnTraditionalChinese" | "Iso2022CnSimplifiedChinese" | "MacRoman" | "MacJapanese" | "MacTraditionalChineseBig5" | "MacKorean" | "MacArabic" | "MacHebrew" | "MacGreek1" | "MacCyrillic" | "MacSimplifiedChineseGb2312" | "MacRomania" | "MacUkraine" | "MacLatin2" | "MacIcelandic" | "MacTurkish" | "MacCroatia" | "EbcdicUsCanada" | "EbcdicInternational" | "EbcdicMultilingualRoeceLatin2" | "EbcdicGreekModern" | "EbcdicTurkishLatin5" | "EbcdicGermany" | "EbcdicDenmarkNorway" | "EbcdicFinlandSweden" | "EbcdicItaly" | "EbcdicLatinAmericaSpain" | "EbcdicUnitedKingdom" | "EbcdicJapaneseKatakanaExtended" | "EbcdicFrance" | "EbcdicArabic" | "EbcdicGreek" | "EbcdicHebrew" | "EbcdicKoreanExtended" | "EbcdicThai" | "EbcdicIcelandic" | "EbcdicTurkish" | "EbcdicRussian" | "EbcdicSerbianBulgarian" | "EbcdicJapaneseKatakanaExtendedAndJapanese" | "EbcdicUsCanadaAndJapanese" | "EbcdicKoreanExtendedAndKorean" | "EbcdicSimplifiedChineseExtendedAndSimplifiedChinese" | "EbcdicUsCanadaAndTraditionalChinese" | "EbcdicJapaneseLatinExtendedAndJapanese" | "OemUnitedStates" | "OemGreek437G" | "OemBaltic" | "OemMultilingualLatinI" | "OemMultilingualLatinIi" | "OemCyrillic" | "OemTurkish" | "OemPortuguese" | "OemIcelandic" | "OemHebrew" | "OemCanadianFrench" | "OemArabic" | "OemNordic" | "OemCyrillicIi" | "OemModernGreek" | "EucJapanese" | "EucChineseSimplifiedChinese" | "EucKorean" | "EucTaiwaneseTraditionalChinese" | "IsciiDevanagari" | "IsciiBengali" | "IsciiTamil" | "IsciiTelugu" | "IsciiAssamese" | "IsciiOriya" | "IsciiKannada" | "IsciiMalayalam" | "IsciiGujarati" | "IsciiPunjabi" | "ArabicAsmo" | "ArabicTransparentAsmo" | "KoreanJohab" | "TaiwanCns" | "TaiwanTca" | "TaiwanEten" | "TaiwanIbm5550" | "TaiwanTeleText" | "TaiwanWang" | "Ia5Irv" | "Ia5German" | "Ia5Swedish" | "Ia5Norwegian" | "UsaAscii" | "T61" | "Iso6937NonSpacingAccent" | "Koi8R" | "ExtAlphaLowercase" | "Koi8U" | "Europa3" | "HzGbSimplifiedChinese" | "SimplifiedChineseGb18030" | "Utf7" | "Utf8";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies how Word marks line and paragraph breaks in text files.

textLineEnding: Word.LineEndingType | "Crlf" | "CrOnly" | "LfOnly" | "Lfcr" | "Lsps";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to remove or store date and time metadata for tracked changes.

trackedChangesAreDateAndTimeRemoved: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to track formatting changes when change tracking is on.

trackFormatting: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to mark moved text when Track Changes is on.

trackMoves: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether changes are tracked in the document.

trackRevisions: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the document type (template or document).

readonly type: Word.DocumentType | "Document" | "Template" | "Frameset";

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the WebSettings object for webpage-related attributes.

readonly webSettings: Word.WebSettings;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the collection of Word.Window objects for the document.

readonly windows: Word.WindowCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.2 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/35-ranges/get-pages.yaml

await Word.run(async (context) => {
  // Gets the document windows.
  const windows: Word.WindowCollection = context.document.windows;
  windows.load("windows/items/length");

  await context.sync();

  console.log(`Number of windows for this document: ${windows.items.length}`);
});

Gets the RangeScopedCollection object that represents each word in the document.

readonly words: Word.RangeScopedCollection;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Sets a password for saving changes to the document.

writePassword: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether error messages are generated from built-in Word messages or MSXML (Microsoft XML).

xmlAreAdvancedErrorsShown: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies whether to save a document through an Extensible Stylesheet Language Transformation (XSLT).

xmlIsXsltUsedWhenSaving: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Specifies the path and file name for the XSLT to apply when saving a document.

xmlSaveThroughXslt: string;

Property Value

Remarks

[ API set: WordApiDesktop 1.4 ]

Accepts all tracked changes in the document.

acceptAllRevisions(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Accepts all revisions in the document that are displayed on the screen.

acceptAllRevisionsShown(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Activates the document so that it becomes the active document.

activate(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Adds a style into the document by name and type.

addStyle(name: string, type: Word.StyleType): Word.Style;

Parameters

Returns

Remarks

[ API set: WordApi 1.5 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-styles.yaml

// Adds a new style.
await Word.run(async (context) => {
  const newStyleName = (document.getElementById("new-style-name") as HTMLInputElement).value;
  if (newStyleName == "") {
    console.warn("Enter a style name to add.");
    return;
  }

  const style: Word.Style = context.document.getStyles().getByNameOrNullObject(newStyleName);
  style.load();
  await context.sync();

  if (!style.isNullObject) {
    console.warn(
      `There's an existing style with the same name '${newStyleName}'! Please provide another style name.`
    );
    return;
  }

  const newStyleType = ((document.getElementById("new-style-type") as HTMLSelectElement).value as unknown) as Word.StyleType;
  context.document.addStyle(newStyleName, newStyleType);
  await context.sync();

  console.log(newStyleName + " has been added to the style list.");
});

Adds a style into the document by name and type.

addStyle(name: string, type: "Character" | "List" | "Paragraph" | "Table"): Word.Style;

Parameters

Returns

Remarks

[ API set: WordApi 1.5 ]

Creates a shortcut to the document or hyperlink and adds it to the Favorites folder.

addToFavorites(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Applies the specified Quick Style set to the document.

applyQuickStyleSet(style: Word.ApplyQuickStyleSet): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Applies the specified Quick Style set to the document.

applyQuickStyleSet(style: "SessionStart" | "Template"): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Applies the specified theme to this document.

applyTheme(name: string): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Automatically formats the document.

autoFormat(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns true if Microsoft Word can check in the document to a server.

canCheckin(): OfficeExtension.ClientResult<boolean>;

Returns

true if the document can be checked in; otherwise, false.

Remarks

[ API set: WordApiDesktop 1.4 ]

Searches all text in a Japanese language document and displays instances where character usage is inconsistent for the same words.

checkConsistencyJapanese(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Begins a spelling and grammar check for the document.

checkGrammar(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Checks in the document from the local computer to a server and sets the local document to read-only so that it cannot be edited locally.

checkIn(options?: Word.DocumentCheckInOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Saves the document to a server from a local computer, and sets the local document to read-only so that it cannot be edited locally.

checkInWithVersion(options?: Word.DocumentCheckInWithVersionOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Begins a spelling check for the document.

checkSpelling(options?: Word.DocumentCheckSpellingOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Closes the current document.

Note: This API isn't supported in Word on the web.

close(closeBehavior?: Word.CloseBehavior): void;

Parameters

Returns

Remarks

[ API set: WordApi 1.5 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/save-close.yaml

// Closes the document with default behavior
// for current state of the document.
await Word.run(async (context) => {
  context.document.close();
});

Closes the current document.

Note: This API isn't supported in Word on the web.

close(closeBehavior?: "Save" | "SkipSave"): void;

Parameters

Returns

Remarks

[ API set: WordApi 1.5 ]

Switches the document from print preview to the previous view.

closePrintPreview(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Displays revision marks that indicate where the specified document differs from another document.

compare(filePath: string, documentCompareOptions?: Word.DocumentCompareOptions): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.1 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/compare-documents.yaml

// Compares the current document with a specified external document.
await Word.run(async (context) => {
  // Absolute path of an online or local document.
  const filePath = (document.getElementById("filePath") as HTMLInputElement).value;
  // Options that configure the compare operation.
  const options: Word.DocumentCompareOptions = {
    compareTarget: Word.CompareTarget.compareTargetCurrent,
    detectFormatChanges: false
    // Other options you choose...
    };
  context.document.compare(filePath, options);

  await context.sync();

  console.log("Differences shown in the current document.");
});

Displays revision marks that indicate where the specified document differs from another document.

compareFromBase64(base64File: string, documentCompareOptions?: Word.DocumentCompareOptions): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.2 ]

Returns a statistic based on the contents of the document.

computeStatistics(statistic: Word.StatisticType, includeFootnotesAndEndnotes?: boolean): OfficeExtension.ClientResult<number>;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a statistic based on the contents of the document.

computeStatistics(statistic: "Words" | "Lines" | "Pages" | "Characters" | "Paragraphs" | "CharactersWithSpaces" | "FarEastCharacters", includeFootnotesAndEndnotes?: boolean): OfficeExtension.ClientResult<number>;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Converts the file to the newest format and enables all features.

convert(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Converts automatic hyphens to manual hyphens.

convertAutoHyphens(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Changes the list numbers and LISTNUM fields in the document to text.

convertNumbersToText(numberType?: Word.NumberType): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Changes the list numbers and LISTNUM fields in the document to text.

convertNumbersToText(numberType?: "Paragraph" | "ListNum" | "AllNumbers"): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Reconverts a Vietnamese document to Unicode using a code page other than the default.

convertVietnameseDocument(codePageOrigin: number): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Copies styles from the specified template to the document.

copyStylesFromTemplate(StyleTemplate: string): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns the number of bulleted or numbered items and LISTNUM fields in the document.

countNumberedItems(options?: Word.DocumentCountNumberedItemsOptions): OfficeExtension.ClientResult<number>;

Parameters

Returns

The count of numbered items.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Deletes all comments from the document.

deleteAllComments(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Deletes all revisions in the document that are displayed on the screen.

deleteAllCommentsShown(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Deletes all handwritten ink annotations in the document.

deleteAllInkAnnotations(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Deletes a bookmark, if it exists, from the document.

deleteBookmark(name: string): void;

Parameters

Returns

Remarks

[ API set: WordApi 1.4 ]

Analyzes the document text to determine the language.

detectLanguage(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.3 ]

Terminates a review of the file that has been sent for review.

endReview(options?: Word.DocumentEndReviewOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Saves the document in PDF or XPS format.

exportAsFixedFormat(outputFileName: string, exportFormat: Word.ExportFormat, options?: Word.DocumentExportAsFixedFormatOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Saves the document in PDF or XPS format.

exportAsFixedFormat(outputFileName: string, exportFormat: "Pdf" | "Xps", options?: Word.DocumentExportAsFixedFormatOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Saves the document in PDF or XPS format.

exportAsFixedFormat2(outputFileName: string, exportFormat: Word.ExportFormat, options?: Word.DocumentExportAsFixedFormat2Options): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Saves the document in PDF or XPS format.

exportAsFixedFormat2(outputFileName: string, exportFormat: "Pdf" | "Xps", options?: Word.DocumentExportAsFixedFormat2Options): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Saves the document in PDF or XPS format with improved tagging.

exportAsFixedFormat3(outputFileName: string, exportFormat: Word.ExportFormat, options?: Word.DocumentExportAsFixedFormat3Options): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Saves the document in PDF or XPS format with improved tagging.

exportAsFixedFormat3(outputFileName: string, exportFormat: "Pdf" | "Xps", options?: Word.DocumentExportAsFixedFormat3Options): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Decreases the font size of text just enough so that the document page count drops by one.

fitToPages(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Displays a cached document, if it has already been downloaded. Otherwise, this method resolves the hyperlink, downloads the target document, and displays the document in the appropriate application.

followHyperlink(options?: Word.DocumentFollowHyperlinkOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Fixes the layout of the document in Web view.

freezeLayout(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the annotation by ID. Throws an ItemNotFound error if annotation isn't found.

getAnnotationById(id: string): Word.Annotation;

Parameters

Returns

Remarks

[ API set: WordApi 1.7 ]

Gets a bookmark's range. Throws an ItemNotFound error if the bookmark doesn't exist.

getBookmarkRange(name: string): Word.Range;

Parameters

Returns

Remarks

[ API set: WordApi 1.4 ]

Gets a bookmark's range. If the bookmark doesn't exist, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getBookmarkRangeOrNullObject(name: string): Word.Range;

Parameters

Returns

Remarks

[ API set: WordApi 1.4 ]

Gets the currently supported content controls in the document.

getContentControls(options?: Word.ContentControlOptions): Word.ContentControlCollection;

Parameters

Returns

Remarks

[ API set: WordApi 1.5 ]

Important: If specific types are provided in the options parameter, only content controls of supported types are returned. Be aware that an exception will be thrown on using methods of a generic Word.ContentControl that aren't relevant for the specific type. With time, additional types of content controls may be supported. Therefore, your add-in should request and handle specific types of content controls.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/insert-and-change-checkbox-content-control.yaml

// Toggles the isChecked property on all checkbox content controls.
await Word.run(async (context) => {
  let contentControls = context.document.getContentControls({
    types: [Word.ContentControlType.checkBox]
  });
  contentControls.load("items");

  await context.sync();

  const length = contentControls.items.length;
  console.log(`Number of checkbox content controls: ${length}`);

  if (length <= 0) {
    return;
  }

  const checkboxContentControls = [];
  for (let i = 0; i < length; i++) {
    let contentControl = contentControls.items[i];
    contentControl.load("id,checkboxContentControl/isChecked");
    checkboxContentControls.push(contentControl);
  }

  await context.sync();

  console.log("isChecked state before:");
  const updatedCheckboxContentControls = [];
  for (let i = 0; i < checkboxContentControls.length; i++) {
    const currentCheckboxContentControl = checkboxContentControls[i];
    const isCheckedBefore = currentCheckboxContentControl.checkboxContentControl.isChecked;
    console.log(`id: ${currentCheckboxContentControl.id} ... isChecked: ${isCheckedBefore}`);

    currentCheckboxContentControl.checkboxContentControl.isChecked = !isCheckedBefore;
    currentCheckboxContentControl.load("id,checkboxContentControl/isChecked");
    updatedCheckboxContentControls.push(currentCheckboxContentControl);
  }

  await context.sync();

  console.log("isChecked state after:");
  for (let i = 0; i < updatedCheckboxContentControls.length; i++) {
    const currentCheckboxContentControl = updatedCheckboxContentControls[i];
    console.log(
      `id: ${currentCheckboxContentControl.id} ... isChecked: ${currentCheckboxContentControl.checkboxContentControl.isChecked}`
    );
  }
});

Returns an array of items that can be cross-referenced based on the specified cross-reference type.

getCrossReferenceItems(referenceType: Word.ReferenceType): OfficeExtension.ClientResult<string[]>;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns an array of items that can be cross-referenced based on the specified cross-reference type.

getCrossReferenceItems(referenceType: "NumberedItem" | "Heading" | "Bookmark" | "Footnote" | "Endnote"): OfficeExtension.ClientResult<string[]>;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Gets the document's endnotes in a single body.

getEndnoteBody(): Word.Body;

Returns

Remarks

[ API set: WordApi 1.5 ]

Gets the document's footnotes in a single body.

getFootnoteBody(): Word.Body;

Returns

Remarks

[ API set: WordApi 1.5 ]

Gets the paragraph by its unique local ID. Throws an ItemNotFound error if the collection is empty.

getParagraphByUniqueLocalId(id: string): Word.Paragraph;

Parameters

Returns

Remarks

[ API set: WordApi 1.6 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/onadded-event.yaml

await Word.run(async (context) => {
  const paragraphId = (document.getElementById("paragraph-id") as HTMLInputElement).value;
  const paragraph: Word.Paragraph = context.document.getParagraphByUniqueLocalId(paragraphId);
  paragraph.load();
  await paragraph.context.sync();

  console.log(paragraph);
});

Returns a Range object by using the specified starting and ending character positions.

getRange(options?: Word.DocumentRangeOptions): Word.Range;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Gets the current selection of the document. Multiple selections aren't supported.

getSelection(): Word.Range;

Returns

Remarks

[ API set: WordApi 1.1 ]

Examples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    const textSample = 'This is an example of the insert text method. This is a method ' + 
        'which allows users to insert text into a selection. It can insert text into a ' +
        'relative location or it can overwrite the current selection. Since the ' +
        'getSelection method returns a range object, look up the range object documentation ' +
        'for everything you can do with a selection.';
    
    // Create a range proxy object for the current selection.
    const range = context.document.getSelection();
    
    // Queue a command to insert text at the end of the selection.
    range.insertText(textSample, Word.InsertLocation.end);
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('Inserted the text at the end of the selection.');
});  

Gets a StyleCollection object that represents the whole style set of the document.

getStyles(): Word.StyleCollection;

Returns

Remarks

[ API set: WordApi 1.5 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-styles.yaml

// Gets the number of available styles stored with the document.
await Word.run(async (context) => {
  const styles: Word.StyleCollection = context.document.getStyles();
  const count = styles.getCount();
  await context.sync();

  console.log(`Number of styles: ${count.value}`);
});

Returns a Range object that represents the start position of the specified item, such as a page, bookmark, or field.

goTo(options?: Word.GoToOptions): Word.Range;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Import styles from a JSON-formatted string.

importStylesFromJson(stylesJson: string, importedStylesConflictBehavior?: Word.ImportedStylesConflictBehavior): OfficeExtension.ClientResult<string[]>;

Parameters

Returns

Remarks

[ API set: WordApi 1.6 ]

Note: The importedStylesConflictBehavior parameter was introduced in WordApiDesktop 1.1.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/40-tables/manage-custom-style.yaml

// Imports styles from JSON.
await Word.run(async (context) => {
  const str =
    '{"styles":[{"baseStyle":"Default Paragraph Font","builtIn":false,"inUse":true,"linked":false,"nameLocal":"NewCharStyle","priority":2,"quickStyle":true,"type":"Character","unhideWhenUsed":false,"visibility":false,"paragraphFormat":null,"font":{"name":"DengXian Light","size":16.0,"bold":true,"italic":false,"color":"#F1A983","underline":"None","subscript":false,"superscript":true,"strikeThrough":true,"doubleStrikeThrough":false,"highlightColor":null,"hidden":false},"shading":{"backgroundPatternColor":"#FF0000"}},{"baseStyle":"Normal","builtIn":false,"inUse":true,"linked":false,"nextParagraphStyle":"NewParaStyle","nameLocal":"NewParaStyle","priority":1,"quickStyle":true,"type":"Paragraph","unhideWhenUsed":false,"visibility":false,"paragraphFormat":{"alignment":"Centered","firstLineIndent":0.0,"keepTogether":false,"keepWithNext":false,"leftIndent":72.0,"lineSpacing":18.0,"lineUnitAfter":0.0,"lineUnitBefore":0.0,"mirrorIndents":false,"outlineLevel":"OutlineLevelBodyText","rightIndent":72.0,"spaceAfter":30.0,"spaceBefore":30.0,"widowControl":true},"font":{"name":"DengXian","size":14.0,"bold":true,"italic":true,"color":"#8DD873","underline":"Single","subscript":false,"superscript":false,"strikeThrough":false,"doubleStrikeThrough":true,"highlightColor":null,"hidden":false},"shading":{"backgroundPatternColor":"#00FF00"}},{"baseStyle":"Table Normal","builtIn":false,"inUse":true,"linked":false,"nextParagraphStyle":"NewTableStyle","nameLocal":"NewTableStyle","priority":100,"type":"Table","unhideWhenUsed":false,"visibility":false,"paragraphFormat":{"alignment":"Left","firstLineIndent":0.0,"keepTogether":false,"keepWithNext":false,"leftIndent":0.0,"lineSpacing":12.0,"lineUnitAfter":0.0,"lineUnitBefore":0.0,"mirrorIndents":false,"outlineLevel":"OutlineLevelBodyText","rightIndent":0.0,"spaceAfter":0.0,"spaceBefore":0.0,"widowControl":true},"font":{"name":"DengXian","size":20.0,"bold":false,"italic":true,"color":"#D86DCB","underline":"None","subscript":false,"superscript":false,"strikeThrough":false,"doubleStrikeThrough":false,"highlightColor":null,"hidden":false},"tableStyle":{"allowBreakAcrossPage":true,"alignment":"Left","bottomCellMargin":0.0,"leftCellMargin":0.08,"rightCellMargin":0.08,"topCellMargin":0.0,"cellSpacing":0.0},"shading":{"backgroundPatternColor":"#60CAF3"}}]}';
  const styles = context.document.importStylesFromJson(str);

  // If you'd like to set how conflicting styles are handled, use the importedStylesConflictBehavior parameter that was introduced in the Desktop 1.1 requirement set. "Ignore" is the default.
  ////const styles = context.document.importStylesFromJson(str, Word.ImportedStylesConflictBehavior.Ignore);

  await context.sync();
  console.log("Styles imported from JSON:", styles);
});

Import styles from a JSON-formatted string.

importStylesFromJson(stylesJson: string, importedStylesConflictBehavior?: "Ignore" | "Overwrite" | "CreateNew"): OfficeExtension.ClientResult<string[]>;

Parameters

Returns

Remarks

[ API set: WordApi 1.6 ]

Note: The importedStylesConflictBehavior parameter was introduced in WordApiDesktop 1.1.

Inserts a document into the target document at a specific location with additional properties. Headers, footers, watermarks, and other section properties are copied by default.

insertFileFromBase64(base64File: string, insertLocation: Word.InsertLocation.replace | Word.InsertLocation.start | Word.InsertLocation.end | "Replace" | "Start" | "End", insertFileOptions?: Word.InsertFileOptions): Word.SectionCollection;

Parameters

Returns

Remarks

[ API set: WordApi 1.5 ]

Insertion isn't supported if the document being inserted contains an ActiveX control (likely in a form field). Consider replacing such a form field with a content control or other option appropriate for your scenario.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/insert-external-document.yaml

// Inserts content (applying selected settings) from another document passed in as a Base64-encoded string.
await Word.run(async (context) => {
  // Use the Base64-encoded string representation of the selected .docx file.
  context.document.insertFileFromBase64(externalDocument, "Replace", {
    importTheme: true,
    importStyles: true,
    importParagraphSpacing: true,
    importPageColor: true,
    importChangeTrackingMode: true,
    importCustomProperties: true,
    importCustomXmlParts: true,
    importDifferentOddEvenPages: true
  });
  await context.sync();
});

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Word.Interfaces.DocumentLoadOptions): Word.Document;

Parameters

Returns

Examples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the document.
    const thisDocument = context.document;
    
    // Queue a command to load content control properties.
    thisDocument.load('contentControls/id, contentControls/text, contentControls/tag');
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    if (thisDocument.contentControls.items.length !== 0) {
        for (let i = 0; i < thisDocument.contentControls.items.length; i++) {
            console.log(thisDocument.contentControls.items[i].id);
            console.log(thisDocument.contentControls.items[i].text);
            console.log(thisDocument.contentControls.items[i].tag);
        }
    } else {
        console.log('No content controls in this document.');
    }
});

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Word.Document;

Parameters

Returns

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.Document;

Parameters

Returns

Locks the file on the server preventing anyone else from editing it.

lockServerFile(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Sets the compatibility options.

makeCompatibilityDefault(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Initiates manual hyphenation of a document, one line at a time.

manualHyphenation(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.3 ]

Merges the changes marked with revision marks from one document to another.

merge(fileName: string, options?: Word.DocumentMergeOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Posts the document to a public folder in Microsoft Exchange.

post(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Opens PowerPoint with the Word document loaded.

presentIt(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Prints all or part of the document.

printOut(options?: Word.DocumentPrintOutOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Switches the view to print preview.

printPreview(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Protects the document from unauthorized changes.

protect(type: Word.ProtectionType, options?: Word.DocumentProtectOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Protects the document from unauthorized changes.

protect(type: "NoProtection" | "AllowOnlyRevisions" | "AllowOnlyComments" | "AllowOnlyFormFields" | "AllowOnlyReading", options?: Word.DocumentProtectOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Redoes the last action that was undone (reverses the undo method).

redo(times?: number): OfficeExtension.ClientResult<boolean>;

Parameters

Returns

true if the actions were redone successfully; otherwise, false.

Remarks

[ API set: WordApiDesktop 1.4 ]

Rejects all tracked changes in the document.

rejectAllRevisions(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Rejects all revisions in the document that are displayed on the screen.

rejectAllRevisionsShown(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Reloads a cached document by resolving the hyperlink to the document and downloading it.

reload(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Reloads the document based on an HTML document, using the document encoding.

reloadAs(encoding: Word.DocumentEncoding): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Reloads the document based on an HTML document, using the document encoding.

reloadAs(encoding: "Thai" | "JapaneseShiftJis" | "SimplifiedChineseGbk" | "Korean" | "TraditionalChineseBig5" | "UnicodeLittleEndian" | "UnicodeBigEndian" | "CentralEuropean" | "Cyrillic" | "Western" | "Greek" | "Turkish" | "Hebrew" | "Arabic" | "Baltic" | "Vietnamese" | "AutoDetect" | "JapaneseAutoDetect" | "SimplifiedChineseAutoDetect" | "KoreanAutoDetect" | "TraditionalChineseAutoDetect" | "CyrillicAutoDetect" | "GreekAutoDetect" | "ArabicAutoDetect" | "Iso88591Latin1" | "Iso88592CentralEurope" | "Iso88593Latin3" | "Iso88594Baltic" | "Iso88595Cyrillic" | "Iso88596Arabic" | "Iso88597Greek" | "Iso88598Hebrew" | "Iso88599Turkish" | "Iso885915Latin9" | "Iso88598HebrewLogical" | "Iso2022JpNoHalfwidthKatakana" | "Iso2022JpJisX02021984" | "Iso2022JpJisX02011989" | "Iso2022Kr" | "Iso2022CnTraditionalChinese" | "Iso2022CnSimplifiedChinese" | "MacRoman" | "MacJapanese" | "MacTraditionalChineseBig5" | "MacKorean" | "MacArabic" | "MacHebrew" | "MacGreek1" | "MacCyrillic" | "MacSimplifiedChineseGb2312" | "MacRomania" | "MacUkraine" | "MacLatin2" | "MacIcelandic" | "MacTurkish" | "MacCroatia" | "EbcdicUsCanada" | "EbcdicInternational" | "EbcdicMultilingualRoeceLatin2" | "EbcdicGreekModern" | "EbcdicTurkishLatin5" | "EbcdicGermany" | "EbcdicDenmarkNorway" | "EbcdicFinlandSweden" | "EbcdicItaly" | "EbcdicLatinAmericaSpain" | "EbcdicUnitedKingdom" | "EbcdicJapaneseKatakanaExtended" | "EbcdicFrance" | "EbcdicArabic" | "EbcdicGreek" | "EbcdicHebrew" | "EbcdicKoreanExtended" | "EbcdicThai" | "EbcdicIcelandic" | "EbcdicTurkish" | "EbcdicRussian" | "EbcdicSerbianBulgarian" | "EbcdicJapaneseKatakanaExtendedAndJapanese" | "EbcdicUsCanadaAndJapanese" | "EbcdicKoreanExtendedAndKorean" | "EbcdicSimplifiedChineseExtendedAndSimplifiedChinese" | "EbcdicUsCanadaAndTraditionalChinese" | "EbcdicJapaneseLatinExtendedAndJapanese" | "OemUnitedStates" | "OemGreek437G" | "OemBaltic" | "OemMultilingualLatinI" | "OemMultilingualLatinIi" | "OemCyrillic" | "OemTurkish" | "OemPortuguese" | "OemIcelandic" | "OemHebrew" | "OemCanadianFrench" | "OemArabic" | "OemNordic" | "OemCyrillicIi" | "OemModernGreek" | "EucJapanese" | "EucChineseSimplifiedChinese" | "EucKorean" | "EucTaiwaneseTraditionalChinese" | "IsciiDevanagari" | "IsciiBengali" | "IsciiTamil" | "IsciiTelugu" | "IsciiAssamese" | "IsciiOriya" | "IsciiKannada" | "IsciiMalayalam" | "IsciiGujarati" | "IsciiPunjabi" | "ArabicAsmo" | "ArabicTransparentAsmo" | "KoreanJohab" | "TaiwanCns" | "TaiwanTca" | "TaiwanEten" | "TaiwanIbm5550" | "TaiwanTeleText" | "TaiwanWang" | "Ia5Irv" | "Ia5German" | "Ia5Swedish" | "Ia5Norwegian" | "UsaAscii" | "T61" | "Iso6937NonSpacingAccent" | "Koi8R" | "ExtAlphaLowercase" | "Koi8U" | "Europa3" | "HzGbSimplifiedChinese" | "SimplifiedChineseGb18030" | "Utf7" | "Utf8"): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Removes sensitive information, properties, comments, and other metadata from the document.

removeDocumentInformation(removeDocInfoType: Word.RemoveDocInfoType): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Removes sensitive information, properties, comments, and other metadata from the document.

removeDocumentInformation(removeDocInfoType: "Comments" | "Revisions" | "Versions" | "RemovePersonalInformation" | "EmailHeader" | "RoutingSlip" | "SendForReview" | "DocumentProperties" | "Template" | "DocumentWorkspace" | "InkAnnotations" | "DocumentServerProperties" | "DocumentManagementPolicy" | "ContentType" | "TaskpaneWebExtensions" | "AtMentions" | "DocumentTasks" | "DocumentIntelligence" | "CommentReactions" | "All"): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Purges the document of locked styles when formatting restrictions have been applied in the document.

removeLockedStyles(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Removes numbers or bullets from the document.

removeNumbers(numberType?: Word.NumberType): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Removes numbers or bullets from the document.

removeNumbers(numberType?: "Paragraph" | "ListNum" | "AllNumbers"): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Removes the active theme from the current document.

removeTheme(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Repaginates the entire document.

repaginate(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Sends an email message to the author of the document that has been sent out for review, notifying them that a reviewer has completed review of the document.

replyWithChanges(options?: Word.DocumentReplyWithChangesOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Clears all form fields in the document, preparing the form to be filled in again.

resetFormFields(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns the document to the last saved reading position.

returnToLastReadPosition(): OfficeExtension.ClientResult<number>;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Runs an auto macro that's stored in the document. If the specified auto macro doesn't exist, nothing happens.

runAutoMacro(autoMacro: Word.AutoMacro): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Runs an auto macro that's stored in the document. If the specified auto macro doesn't exist, nothing happens.

runAutoMacro(autoMacro: "StartWord" | "New" | "Open" | "Close" | "Exit" | "Sync"): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Saves the document.

save(saveBehavior?: Word.SaveBehavior, fileName?: string): void;

Parameters

Returns

Remarks

[ API set: WordApi 1.1 ]

Note: The saveBehavior and fileName parameters were introduced in WordApi 1.5.

Examples

// Run a batch operation against the Word object model.
await Word.run(async (context) => {
    
    // Create a proxy object for the document.
    const thisDocument = context.document;

    // Queue a command to load the document save state (on the saved property).
    thisDocument.load('saved');    
    
    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
        
    if (thisDocument.saved === false) {
        // Queue a command to save this document.
        thisDocument.save();
        
        // Synchronize the document state by executing the queued commands, 
        // and return a promise to indicate task completion.
        await context.sync();
        console.log('Saved the document');
    } else {
        console.log('The document has not changed since the last save.');
    }
});

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/save-close.yaml

// Saves the document with default behavior
// for current state of the document.
await Word.run(async (context) => {
  context.document.save();
  await context.sync();
});

Saves the document.

save(saveBehavior?: "Save" | "Prompt", fileName?: string): void;

Parameters

Returns

Remarks

[ API set: WordApi 1.1 ]

Note: The saveBehavior and fileName parameters were introduced in WordApi 1.5.

Saves the group of quick styles currently in use.

saveAsQuickStyleSet(fileName: string): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Performs a search with the specified search options on the scope of the whole document. The search results are a collection of Range objects.

search(searchText: string, searchOptions?: Word.SearchOptions | {
            ignorePunct?: boolean;
            ignoreSpace?: boolean;
            matchCase?: boolean;
            matchPrefix?: boolean;
            matchSuffix?: boolean;
            matchWholeWord?: boolean;
            matchWildcards?: boolean;
        }): Word.RangeCollection;

Parameters

Returns

Remarks

[ API set: WordApi 1.7 ]

Selects the contents of the document.

select(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns all content controls with the specified tag.

selectContentControlsByTag(tag: string): Word.ContentControlCollection;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a ContentControlCollection object that represents all the content controls in the document with the specified title.

selectContentControlsByTitle(title: string): Word.ContentControlCollection;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a ContentControlCollection object that represents all content controls in the document that are linked to the specific custom XML node.

selectLinkedControls(node: Word.CustomXmlNode): Word.ContentControlCollection;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns an XmlNodeCollection object that represents all the nodes that match the XPath parameter in the order in which they appear in the document.

selectNodes(xPath: string, options?: Word.SelectNodesOptions): Word.XmlNodeCollection;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns an XmlNode object that represents the first node that matches the XPath parameter in the document.

selectSingleNode(xPath: string, options?: Word.SelectSingleNodeOptions): Word.XmlNode;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Returns a ContentControlCollection object that represents all content controls in the document that are not linked to an XML node.

selectUnlinkedControls(stream?: Word.CustomXmlPart): Word.ContentControlCollection;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Sends the document as a fax, without any user interaction.

sendFax(address: string, subject?: string): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Sends the document to a fax service provider, who faxes the document to one or more specified recipients.

sendFaxOverInternet(options?: Word.DocumentSendFaxOverInternetOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sends the document in an email message for review by the specified recipients.

sendForReview(options?: Word.DocumentSendForReviewOptions): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Opens a message window for sending the document through Microsoft Exchange.

sendMail(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.DocumentUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

Returns

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Word.Document): void;

Parameters

Returns

Specifies the table style to use for newly created tables in the document.

setDefaultTableStyle(style: string, setInTemplate: boolean): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Sets the options Microsoft Word uses for encrypting documents with passwords.

setPasswordEncryptionOptions(passwordEncryptionProvider: string, passwordEncryptionAlgorithm: string, passwordEncryptionKeyLength: number, passwordEncryptFileProperties?: boolean): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Switches form design mode on or off.

toggleFormsDesign(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Word.Document object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.DocumentData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Word.Interfaces.DocumentData;

Returns

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.

track(): Word.Document;

Returns

Applies the specified Extensible Stylesheet Language Transformation (XSLT) file to this document and replaces the document with the results.

transformDocument(path: string, dataOnly?: boolean): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Undoes the last action or a sequence of actions, which are displayed in the Undo list.

undo(times?: number): OfficeExtension.ClientResult<boolean>;

Parameters

Returns

true if the actions were undone successfully; otherwise, false.

Remarks

[ API set: WordApiDesktop 1.4 ]

Clears the list of actions that can be undone in the document.

undoClear(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Removes protection from the document.

unprotect(password?: string): void;

Parameters

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.

untrack(): Word.Document;

Returns

Copies all styles from the attached template into the document, overwriting any existing styles in the document that have the same name.

updateStyles(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Displays the code window for the selected Microsoft ActiveX control in the document.

viewCode(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Displays the property window for the selected Microsoft ActiveX control in the document.

viewPropertyBrowser(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Displays a preview of the current document as it would look if saved as a webpage.

webPagePreview(): void;

Returns

Remarks

[ API set: WordApiDesktop 1.4 ]

Occurs when the user clicks an annotation (or selects it using Alt+Down).

readonly onAnnotationClicked: OfficeExtension.EventHandlers<Word.AnnotationClickedEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.7 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onClickedHandler(args: Word.AnnotationClickedEventArgs) {
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationClicked: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

Occurs when the user hovers the cursor over an annotation.

readonly onAnnotationHovered: OfficeExtension.EventHandlers<Word.AnnotationHoveredEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.7 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onHoveredHandler(args: Word.AnnotationHoveredEventArgs) {
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationHovered: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

Occurs when the user adds one or more annotations.

readonly onAnnotationInserted: OfficeExtension.EventHandlers<Word.AnnotationInsertedEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.7 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onInsertedHandler(args: Word.AnnotationInsertedEventArgs) {
  await Word.run(async (context) => {
    const annotations = [];
    for (let i = 0; i < args.ids.length; i++) {
      let annotation: Word.Annotation = context.document.getAnnotationById(args.ids[i]);
      annotation.load("id,critiqueAnnotation");

      annotations.push(annotation);
    }

    await context.sync();

    for (let annotation of annotations) {
      console.log(`AnnotationInserted: ID ${annotation.id}:`, annotation.critiqueAnnotation.critique);
    }
  });
}

Occurs when the user performs an action in an annotation pop-up menu.

readonly onAnnotationPopupAction: OfficeExtension.EventHandlers<Word.AnnotationPopupActionEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.8 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onPopupActionHandler(args: Word.AnnotationPopupActionEventArgs) {
  await Word.run(async (context) => {
    let message = `AnnotationPopupAction: ID ${args.id} = `;
    if (args.action === "Accept") {
      message += `Accepted: ${args.critiqueSuggestion}`;
    } else {
      message += "Rejected";
    }

    console.log(message);
  });
}

Occurs when the user deletes one or more annotations.

readonly onAnnotationRemoved: OfficeExtension.EventHandlers<Word.AnnotationRemovedEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.7 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Registers event handlers.
await Word.run(async (context) => {
  eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
  eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

  eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
  eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
  eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
  eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
  eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

  await context.sync();

  console.log("Event handlers registered.");
});

...

async function onRemovedHandler(args: Word.AnnotationRemovedEventArgs) {
  await Word.run(async (context) => {
    for (let id of args.ids) {
      console.log(`AnnotationRemoved: ID ${id}`);
    }
  });
}

Occurs when a content control is added. Run context.sync() in the handler to get the new content control's properties.

readonly onContentControlAdded: OfficeExtension.EventHandlers<Word.ContentControlAddedEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.5 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/content-control-onadded-event.yaml

// Registers the onAdded event handler on the document.
await Word.run(async (context) => {
  eventContext = context.document.onContentControlAdded.add(contentControlAdded);
  await context.sync();

  console.log("Added event handler for when content controls are added.");
});

...

async function contentControlAdded(event: Word.ContentControlAddedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. IDs of content controls that were added:`, event.ids);
  });
}

Occurs when the user adds new paragraphs.

readonly onParagraphAdded: OfficeExtension.EventHandlers<Word.ParagraphAddedEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.6 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/onadded-event.yaml

// Registers the onParagraphAdded event handler on the document.
await Word.run(async (context) => {
  eventContext = context.document.onParagraphAdded.add(paragraphAdded);
  await context.sync();

  console.log("Added event handler for when paragraphs are added.");
});

...

async function paragraphAdded(event: Word.ParagraphAddedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.type} event detected. IDs of paragraphs that were added:`, event.uniqueLocalIds);
  });
}

Occurs when the user changes paragraphs.

readonly onParagraphChanged: OfficeExtension.EventHandlers<Word.ParagraphChangedEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.6 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/onchanged-event.yaml

// Registers the onParagraphChanged event handler on the document.
await Word.run(async (context) => {
  eventContext = context.document.onParagraphChanged.add(paragraphChanged);
  await context.sync();

  console.log("Added event handler for when content is changed in paragraphs.");
});

...

async function paragraphChanged(event: Word.ParagraphChangedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.type} event detected. IDs of paragraphs where content was changed:`, event.uniqueLocalIds);
  });
}

Occurs when the user deletes paragraphs.

readonly onParagraphDeleted: OfficeExtension.EventHandlers<Word.ParagraphDeletedEventArgs>;

Event Type

Remarks

[ API set: WordApi 1.6 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/25-paragraph/ondeleted-event.yaml

// Registers the onParagraphDeleted event handler on the document.
await Word.run(async (context) => {
  eventContext = context.document.onParagraphDeleted.add(paragraphDeleted);
  await context.sync();

  console.log("Added event handlers for when paragraphs are deleted.");
});

...

async function paragraphDeleted(event: Word.ParagraphDeletedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.type} event detected. IDs of paragraphs that were deleted:`, event.uniqueLocalIds);
  });
}