Word.Window class
Represents the window that displays the document. A window can be split to contain multiple reading panes.
- Extends
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);
}
});
Properties
| active |
Gets the active pane in the window. |
| are |
Specifies whether rulers are displayed for the window or pane. |
| are |
Specifies whether comments, footnotes, endnotes, and hyperlinks are displayed as tips. |
| are |
Specifies whether thumbnail images of the pages in a document are displayed along the left side of the Microsoft Word document window. |
| caption | Specifies the caption text for the window that is displayed in the title bar of the document or application window. |
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| height | Specifies the height of the window (in points). |
| horizontal |
Specifies the horizontal scroll position as a percentage of the document width. |
| ime |
Specifies the default start-up mode for the Japanese Input Method Editor (IME). |
| index | Gets the position of an item in a collection. |
| is |
Specifies whether the window is active. |
| is |
Specifies whether the document map is visible. |
| is |
Specifies whether the email message header is visible in the document window. The default value is |
| is |
Specifies whether a horizontal scroll bar is displayed for the window. |
| is |
Specifies whether the vertical scroll bar appears on the left side of the document window. |
| is |
Specifies whether the vertical ruler appears on the right side of the document window in print layout view. |
| is |
Specifies whether the window is split into multiple panes. |
| is |
Specifies whether a vertical ruler is displayed for the window or pane. |
| is |
Specifies whether a vertical scroll bar is displayed for the window. |
| is |
Specifies whether the window is visible. |
| left | Specifies the horizontal position of the window, measured in points. |
| next | Gets the next document window in the collection of open document windows. |
| panes | Gets the collection of panes in the window. |
| previous | Gets the previous document window in the collection open document windows. |
| show |
Specifies how Microsoft Word displays source documents after a compare and merge process. |
| split |
Specifies the vertical split percentage for the window. |
| state | Specifies the state of the document window or task window. |
| style |
Specifies the width of the style area in points. |
| top | Specifies the vertical position of the document window, in points. |
| type | Gets the window type. |
| usable |
Gets the height (in points) of the active working area in the document window. |
| usable |
Gets the width (in points) of the active working area in the document window. |
| vertical |
Specifies the vertical scroll position as a percentage of the document length. |
| view | Gets the |
| width | Specifies the width of the document window, in points. |
| window |
Gets an integer that represents the position of the window. |
Methods
| activate() | Activates the window. |
| close(options) | Closes the window. |
| large |
Scrolls the window by the specified number of screens. |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| page |
Scrolls through the window page by page. |
| set(properties, options) | 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) | Sets multiple properties on the object at the same time, based on an existing loaded object. |
| set |
Sets the focus of the document window to the body of an email message. |
| small |
Scrolls the window by the specified number of lines. A "line" corresponds to the distance scrolled by clicking the scroll arrow on the scroll bar once. |
| toggle |
Shows or hides the ribbon. |
| toJSON() | Overrides the JavaScript |
| track() | 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 |
| untrack() | 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 |
Property Details
activePane
Gets the active pane in the window.
readonly activePane: Word.Pane;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 pages enclosing the viewport.
// 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 pages enclosing the viewport.
const pages: Word.PageCollection = activePane.pagesEnclosingViewport;
pages.load();
await context.sync();
// Log the number of pages.
const pageCount = pages.items.length;
console.log(`Number of pages enclosing the viewport: ${pageCount}`);
// Log index info of these pages.
const pagesIndexes = [];
for (let i = 0; i < pageCount; i++) {
const page = pages.items[i];
page.load("index");
pagesIndexes.push(page);
}
await context.sync();
for (let i = 0; i < pagesIndexes.length; i++) {
console.log(`Page index: ${pagesIndexes[i].index}`);
}
});
areRulersDisplayed
Specifies whether rulers are displayed for the window or pane.
areRulersDisplayed: boolean;Property Value
boolean
Remarks
areScreenTipsDisplayed
Specifies whether comments, footnotes, endnotes, and hyperlinks are displayed as tips.
readonly areScreenTipsDisplayed: boolean;Property Value
boolean
Remarks
areThumbnailsDisplayed
Specifies whether thumbnail images of the pages in a document are displayed along the left side of the Microsoft Word document window.
areThumbnailsDisplayed: boolean;Property Value
boolean
Remarks
caption
Specifies the caption text for the window that is displayed in the title bar of the document or application window.
caption: string;Property Value
string
Remarks
context
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
height
Specifies the height of the window (in points).
readonly height: number;Property Value
number
Remarks
horizontalPercentScrolled
Specifies the horizontal scroll position as a percentage of the document width.
horizontalPercentScrolled: number;Property Value
number
Remarks
imeMode
Specifies the default start-up mode for the Japanese Input Method Editor (IME).
imeMode: Word.ImeMode | "NoControl" | "On" | "Off" | "Hiragana" | "Katakana" | "KatakanaHalf" | "AlphaFull" | "Alpha" | "HangulFull" | "Hangul";Property Value
Word.ImeMode | "NoControl" | "On" | "Off" | "Hiragana" | "Katakana" | "KatakanaHalf" | "AlphaFull" | "Alpha" | "HangulFull" | "Hangul"
Remarks
index
Gets the position of an item in a collection.
readonly index: number;Property Value
number
Remarks
isActive
Specifies whether the window is active.
readonly isActive: boolean;Property Value
boolean
Remarks
isDocumentMapVisible
Specifies whether the document map is visible.
isDocumentMapVisible: boolean;Property Value
boolean
Remarks
isEnvelopeVisible
Specifies whether the email message header is visible in the document window. The default value is false.
isEnvelopeVisible: boolean;Property Value
boolean
Remarks
isHorizontalScrollBarDisplayed
Specifies whether a horizontal scroll bar is displayed for the window.
isHorizontalScrollBarDisplayed: boolean;Property Value
boolean
Remarks
isLeftScrollBarDisplayed
Specifies whether the vertical scroll bar appears on the left side of the document window.
isLeftScrollBarDisplayed: boolean;Property Value
boolean
Remarks
isRightRulerDisplayed
Specifies whether the vertical ruler appears on the right side of the document window in print layout view.
isRightRulerDisplayed: boolean;Property Value
boolean
Remarks
isSplit
Specifies whether the window is split into multiple panes.
isSplit: boolean;Property Value
boolean
Remarks
isVerticalRulerDisplayed
Specifies whether a vertical ruler is displayed for the window or pane.
isVerticalRulerDisplayed: boolean;Property Value
boolean
Remarks
isVerticalScrollBarDisplayed
Specifies whether a vertical scroll bar is displayed for the window.
isVerticalScrollBarDisplayed: boolean;Property Value
boolean
Remarks
isVisible
Specifies whether the window is visible.
isVisible: boolean;Property Value
boolean
Remarks
left
Specifies the horizontal position of the window, measured in points.
readonly left: number;Property Value
number
Remarks
next
Gets the next document window in the collection of open document windows.
readonly next: Word.Window;Property Value
Remarks
panes
Gets the collection of panes in the window.
readonly panes: Word.PaneCollection;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 all the panes in the active document window.
// Get the active window.
const activeWindow: Word.Window = context.document.activeWindow;
activeWindow.load("panes/items/length");
await context.sync();
const panes: Word.PaneCollection = activeWindow.panes;
console.log(`Number of panes in the current document window: ${panes.items.length}`);
});
previous
Gets the previous document window in the collection open document windows.
readonly previous: Word.Window;Property Value
Remarks
showSourceDocuments
Specifies how Microsoft Word displays source documents after a compare and merge process.
showSourceDocuments: Word.ShowSourceDocuments | "None" | "Original" | "Revised" | "Both";Property Value
Word.ShowSourceDocuments | "None" | "Original" | "Revised" | "Both"
Remarks
splitVertical
Specifies the vertical split percentage for the window.
splitVertical: number;Property Value
number
Remarks
state
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Specifies the state of the document window or task window.
state: Word.WindowState | "Normal" | "Maximize" | "Minimize";Property Value
Word.WindowState | "Normal" | "Maximize" | "Minimize"
Remarks
styleAreaWidth
Specifies the width of the style area in points.
styleAreaWidth: number;Property Value
number
Remarks
top
Specifies the vertical position of the document window, in points.
readonly top: number;Property Value
number
Remarks
type
Gets the window type.
readonly type: Word.WindowType | "Document" | "Template";Property Value
Word.WindowType | "Document" | "Template"
Remarks
usableHeight
Gets the height (in points) of the active working area in the document window.
readonly usableHeight: number;Property Value
number
Remarks
usableWidth
Gets the width (in points) of the active working area in the document window.
readonly usableWidth: number;Property Value
number
Remarks
verticalPercentScrolled
Specifies the vertical scroll position as a percentage of the document length.
verticalPercentScrolled: number;Property Value
number
Remarks
view
Gets the View object that represents the view for the window.
readonly view: Word.View;Property Value
Remarks
width
Specifies the width of the document window, in points.
readonly width: number;Property Value
number
Remarks
windowNumber
Gets an integer that represents the position of the window.
readonly windowNumber: number;Property Value
number
Remarks
Method Details
activate()
close(options)
Closes the window.
close(options?: Word.WindowCloseOptions): void;Parameters
- options
- Word.WindowCloseOptions
Optional. The options that define whether to save changes before closing and whether to route the document.
Returns
void
Remarks
[ API set: WordApiDesktop 1.4 ]
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/99-preview-apis/close-document-window.yaml
await Word.run(async (context) => {
// Closes the document window, prompting to save if this is a new document.
const window: Word.Window = context.document.activeWindow;
const closeOptions: Word.WindowCloseOptions = { saveChanges: Word.SaveConfiguration.promptToSaveChanges };
console.log("About to close the document window...");
window.close(closeOptions);
});
largeScroll(options)
Scrolls the window by the specified number of screens.
largeScroll(options?: Word.WindowScrollOptions): void;Parameters
- options
- Word.WindowScrollOptions
Optional. The options for scrolling the window by the specified number of screens. If no options are specified, the window is scrolled down one screen.
Returns
void
Remarks
load(options)
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.WindowLoadOptions): Word.Window;Parameters
Provides options for which properties of the object to load.
Returns
load(propertyNames)
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.Window;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
load(propertyNamesAndPaths)
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.Window;Parameters
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
pageScroll(options)
Scrolls through the window page by page.
pageScroll(options?: Word.WindowPageScrollOptions): void;Parameters
- options
- Word.WindowPageScrollOptions
Optional. The options for scrolling through the window page by page.
Returns
void
Remarks
set(properties, options)
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.WindowUpdateData, options?: OfficeExtension.UpdateOptions): void;Parameters
- properties
- Word.Interfaces.WindowUpdateData
A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.
- options
- OfficeExtension.UpdateOptions
Provides an option to suppress errors if the properties object tries to set any read-only properties.
Returns
void
set(properties)
Sets multiple properties on the object at the same time, based on an existing loaded object.
set(properties: Word.Window): void;Parameters
- properties
- Word.Window
Returns
void
setFocus()
Sets the focus of the document window to the body of an email message.
setFocus(): void;Returns
void
Remarks
smallScroll(options)
Scrolls the window by the specified number of lines. A "line" corresponds to the distance scrolled by clicking the scroll arrow on the scroll bar once.
smallScroll(options?: Word.WindowScrollOptions): void;Parameters
- options
- Word.WindowScrollOptions
Optional. The options for scrolling the window by the specified number of lines. If no options are specified, the window is scrolled down by one line.
Returns
void
Remarks
toggleRibbon()
Shows or hides the ribbon.
toggleRibbon(): void;Returns
void
Remarks
toJSON()
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.Window object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.WindowData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): Word.Interfaces.WindowData;Returns
track()
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.Window;Returns
untrack()
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.Window;