Word.Body

Word.Body is an object type of the Word module (Office.word(iframe)). 24 methods.

Generated from the SDK type definitions

Word · 14 object types · 259 methods · namespace Word. This reference is generated from the API document artifact (sdk-api-doc.html) produced with the SDK build. Descriptions are the editor's API comments as published. Pin the SDK and Office versions together and regenerate when either changes.

Remarks

• Module: Word · Office.word(iframe) · namespace Word
• Obtained from: Document.getBody(), Section.getBody(), Section.getFooter(type), Section.getHeader(type), Paragraph.getParentBody(), Shape.getBody(), Image.getBody()
• Every method returns a Promise; signatures use TypeScript notation.

Methods

Method	Description
acceptChangeTrackings()	Accepts all change tracking items in this area.
clear()	Clears the content of this area, leaving one empty paragraph.
exists()	Checks whether this content area actually exists.
getChangeTrackings()	Returns the list of change tracking items in this area in document order.
getComments()	Returns the list of comments in this area.
getContentHtml()	Returns the entire content of this area as HTML with formatting.
getEndnotes()	Returns the list of endnotes in the body.
getFootnotes()	Returns the list of footnotes in the body.
getNotes()	Returns the list of footnotes/endnotes in the body.
getParagraph(index)	Returns the paragraph at the given index in this area.
getParagraphs()	Returns the list of paragraphs in this area.
getRange(range)	Returns the range for the given position or coordinates within this area.
getStoryId()	Returns the identifier of this area.
getStructure(options)	Returns the paragraph/table structure of this area.
getText()	Returns the entire content of this area as plain text.
insertHtml(html, options)	Inserts HTML and returns the range of the inserted content.
insertParagraph(text, options)	Inserts a new paragraph; if the position is omitted, appends it at the end of the area.
insertTable(rows, columns, options)	Inserts a table; if the position is omitted, appends it at the end of the area.
insertText(text, options)	Puts text into this area, either at the very beginning or in place of the whole content.
rejectChangeTrackings()	Rejects all change tracking items in this area.
replaceAll(findText, replaceText, options)	Finds and replaces all matching text within this area.
replaceParagraphs(items)	Replaces multiple paragraphs in place at once.
search(query, options)	Searches this area for text or a special character and returns a list of editable ranges.
select(mode)	Sets this whole area as the on-screen selection (does not change document content).

Method details

acceptChangeTrackings()

Accepts all change tracking items in this area.

acceptChangeTrackings(): Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }>;

Returns

Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }> - processing result

clear()

Clears the content of this area, leaving one empty paragraph. - The content area itself is kept.

clear(): Promise<boolean>;

Returns

Promise<boolean> - true if the area exists (including an already empty area), false if the area does not exist

exists()

Checks whether this content area actually exists. - A header or footer that has not been created yet is created on the first content insertion.

exists(): Promise<boolean>;

Returns

Promise<boolean> - true if the area exists, false if it has not been created yet

getChangeTrackings()

Returns the list of change tracking items in this area in document order.

getChangeTrackings(): Promise<WordChangeTracking[]>;

Returns

Promise<WordChangeTracking[]> - array of change tracking proxies

getComments()

Returns the list of comments in this area. Works only for the body area; other areas return an empty array.

getComments(): Promise<WordComment[]>;

Returns

Promise<WordComment[]> - array of comment proxies

getContentHtml()

Returns the entire content of this area as HTML with formatting. - Paragraphs are represented as <p> elements.

getContentHtml(): Promise<{ html: string; paragraphCount: number }>;

Returns

Promise<{ html: string; paragraphCount: number }> - HTML and paragraph count. Empty string and 0 if the area does not exist

getEndnotes()

Returns the list of endnotes in the body. (body area only)

getEndnotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - array of endnote proxies

getFootnotes()

Returns the list of footnotes in the body. (body area only)

getFootnotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - array of footnote proxies

getNotes()

Returns the list of footnotes/endnotes in the body. (body area only)

getNotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - array of note proxies

getParagraph(index)

Returns the paragraph at the given index in this area.

getParagraph(index?: number): Promise<Paragraph>;

Parameters

Name	Type	Description
index (optional)	number	zero-based paragraph index (default: 0)

Returns

Promise<Paragraph> - paragraph that can be inspected and edited. null if the area or that paragraph does not exist

getParagraphs()

Returns the list of paragraphs in this area.

getParagraphs(): Promise<Paragraph[]>;

Returns

Promise<Paragraph[]> - list of paragraphs that can be inspected and edited. Empty array if the area does not exist

getRange(range)

Returns the range for the given position or coordinates within this area.

getRange(range?: (RangeData | RangePosition)): Promise<Range>;

Parameters

Name	Type	Description
range (optional)	(RangeData | RangePosition)	coordinate RangeData object, or an area position RangePosition ("whole"/"start"/"end"/"content"); omitted means the whole area (default: RangePosition.WHOLE)

Returns

Promise<Range> - range that can be inspected and edited within this area

getStoryId()

Returns the identifier of this area.

getStoryId(): Promise<string>;

Returns

Promise<string> - ID of the content area

getStructure(options)

Returns the paragraph/table structure of this area. Empty list if the area does not exist. - The text of a paragraph entry includes the trailing boundary newline - the final "\n" is always the paragraph boundary, so the character count within that paragraph is text.length - 1, and a "\n" in the middle is one line-break object (manual line break, page break, or column break).

getStructure(options?: { type?: StructureFilter }): Promise<{ paragraphs: { index: number; type: string; id: string; storyId: string; text?: string; rows?: number; columns?: number }[] }>;

Parameters

Name	Type	Description
options (optional)	{ type?: StructureFilter }	lookup options. The target area is fixed to this body.
options.type (optional)	StructureFilter	get only a specific type (table=tables only / list=list paragraphs only) (default: all)

Returns

Promise<{ paragraphs: { index: number; type: string; id: string; storyId: string; text?: string; rows?: number; columns?: number }[] }> - list of paragraph/table entries (document order). id is a common identifier (type tells the kind); type="p" includes text, tables include rows/columns

getText()

Returns the entire content of this area as plain text. - For footnotes/endnotes, the automatic number marker and separator space are excluded.

getText(): Promise<string>;

Returns

Promise<string> - full text for reading. Empty string if the area does not exist

insertHtml(html, options)

Inserts HTML and returns the range of the inserted content.
If the position is omitted, creates a new paragraph at the end of the area and inserts there.
If <img> is included, the images are uploaded first and their src replaced. Images that fail to upload are excluded and the rest is inserted.
Plain text without tags ("hello") and non-block tags ("\<div\>abc\</div\>") are also normalized as text within a paragraph, and multi-paragraph HTML ("\<p\>a\</p\>\<p\>b\</p\>") returns a range covering all of those paragraphs.
Since it goes through the same path as paste, anything paste does not support is not inserted:
List styles are not applied - \<ul\>/\<ol\>/\<li\> become plain paragraphs without numbers or bullets (set lists separately with WordParagraph.setList).
Heading styles are not applied either - \<h1\>~\<h6\> become plain paragraphs without a style (set styles separately with WordRange.setStyle).
Tags that are not document content (\<script\>/\<style\>/\<iframe\>, etc.) are discarded along with their inner text.
If change tracking (track changes) is on, the inserted content remains as a revision, as with normal paste (except inside comments).
Because block HTML (\<p\>, \<h1\>, etc.) inserts a paragraph break with each block, one empty paragraph remains after the last block (plain text and inline do not leave one).

insertHtml(
  html: string,
  options?: { paragraphId?: string; position?: InsertAt }
): Promise<Range>;

Parameters

Name	Type	Description
html	string	HTML to insert. If an empty string (whitespace-only counts too), returns only an empty range at the insertion point without changing the document
options (optional)	{ paragraphId?: string; position?: InsertAt }	insert position options
options.paragraphId (optional)	string	reference paragraph ID
options.position (optional)	InsertAt	without a reference paragraph, creates a new paragraph at "start" (very beginning of the area) / "end" (very end of the area) and inserts into it. With a reference paragraph, this is the insertion point, not a sibling position - "after" is the end point of that paragraph, "before" is its start point. "after" appends at the end of the anchor paragraph, so the first content merges into that paragraph (\<p\>A\</p\>\<p\>B\</p\> = A merged into the anchor + B as a new paragraph), while "before" becomes a new paragraph before the anchor for block HTML, or merges at the very start of the anchor for inline HTML (default: after if a reference paragraph is given, otherwise end)

Returns

Promise<Range> - range of the inserted content. If there is nothing to insert (empty HTML or HTML without content), an empty (collapsed) range at the insertion point. Insertion failures are reported as exceptions.

insertParagraph(text, options)

Inserts a new paragraph; if the position is omitted, appends it at the end of the area.
Creates the area automatically if it does not exist. The new paragraph inherits the direct paragraph formatting of the reference paragraph, such as alignment, spacing, and indentation.
If paragraphId is omitted, the first or last paragraph of the area is used as the reference depending on the insert position.
To reset the inherited direct formatting, call clearFormat() on the returned paragraph.

insertParagraph(
  text: string,
  options?: { paragraphId?: string; position?: InsertAt }
): Promise<Paragraph>;

Parameters

Name	Type	Description
text	string	text of the new paragraph
options (optional)	{ paragraphId?: string; position?: InsertAt }	insert options
options.paragraphId (optional)	string	reference paragraph ID
options.position (optional)	InsertAt	with a reference paragraph, "before" (above) / "after" (below) relative to that paragraph; without one, the area position "start" (very beginning) / "end" (very end) (default: after if a reference paragraph is given, otherwise end)

Returns

Promise<Paragraph> - new paragraph that can be inspected and edited after insertion

insertTable(rows, columns, options)

Inserts a table; if the position is omitted, appends it at the end of the area. - Cannot insert inside a table cell. An error is thrown if the insertion point is inside a cell.

insertTable(
  rows: number,
  columns: number,
  options?: { paragraphId?: string; position?: InsertAt; values?: string[][] }
): Promise<Table>;

Parameters

Name	Type	Description
rows	number	number of rows
columns	number	number of columns
options (optional)	{ paragraphId?: string; position?: InsertAt; values?: string[][] }	insert options
options.paragraphId (optional)	string	reference paragraph ID
options.position (optional)	InsertAt	with a reference paragraph, "before" (above) / "after" (below) relative to that paragraph; without one, the area position "start" (very beginning) / "end" (very end) (default: after if a reference paragraph is given, otherwise end)
options.values (optional)	string[][]	cell values to fill right after creation (2D array; throws before issuing if it exceeds the table size)

Returns

Promise<Table> - proxy of the inserted table

insertText(text, options)

Puts text into this area, either at the very beginning or in place of the whole content.
Without replace, the text goes in at the very start of the area and the existing content stays.
With replace, the whole content is replaced and a single paragraph is left, so several paragraphs become one.
If the area does not exist yet, it is created and this text becomes its first content.
In a footnote or endnote area, replace keeps the automatic number marker and the space after it and replaces only the text that follows.
Only the text changes - the formatting of the area stays as it is. Apply formatting to the returned range when you need it.

insertText(text: string, options?: { replace?: boolean }): Promise<Range>;

Parameters

Name	Type	Description
text	string	text to put in. An empty string with replace empties the area
options (optional)	{ replace?: boolean }	insert options
options.replace (optional)	boolean	true replaces the whole content of the area; omitted adds at the very beginning (default: false)

Returns

Promise<Range> - range of the text that was put in. For a footnote/endnote replace it covers the first paragraph including the number marker. null when a footnote/endnote has no content to replace

rejectChangeTrackings()

Rejects all change tracking items in this area.

rejectChangeTrackings(): Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }>;

Returns

Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }> - processing result

replaceAll(findText, replaceText, options)

Finds and replaces all matching text within this area. - When called on the body, the scope is the whole body; when called on a header, footer, etc., it is limited to that area.

replaceAll(
  findText: string,
  replaceText: string,
  options?: { caseSensitive?: boolean }
): Promise<{ replacedCount: number }>;

Parameters

Name	Type	Description
findText	string	text to find
replaceText	string	replacement text
options (optional)	{ caseSensitive?: boolean }	replace options
options.caseSensitive (optional)	boolean	case-sensitive matching (default: false)

Returns

Promise<{ replacedCount: number }> - number of actual replacements (0 if no match)

replaceParagraphs(items)

Replaces multiple paragraphs in place at once. Changes text only; unless keepFormat is set, resets the formatting of the replaced range.

replaceParagraphs(items: { paragraphId: string; text: string; keepFormat?: boolean }[]): Promise<number>;

Parameters

Name	Type	Description
items	{ paragraphId: string; text: string; keepFormat?: boolean }[]	list of paragraphs to replace, looked up within this area. keepFormat defaults to false (reset formatting)

Returns

Promise<number> - number of successful replacements

search(query, options)

Searches this area for text or a special character and returns a list of editable ranges.

search(
  query: string | { character: SpecialCharacter },
  options?: { caseSensitive?: boolean; wholeWord?: boolean }
): Promise<Range[]>;

Parameters

Name	Type	Description
query	string | { character: SpecialCharacter }	a string searches for text; a \{ character \} object searches for a special character
options (optional)	{ caseSensitive?: boolean; wholeWord?: boolean }	text search options (ignored for special character search)
options.caseSensitive (optional)	boolean	case-sensitive matching (default: false)
options.wholeWord (optional)	boolean	whole-word matching (default: false)

Returns

Promise<Range[]> - list of matched range proxies (empty array if none)

select(mode)

Sets this whole area as the on-screen selection (does not change document content).

select(mode?: SelectionMode): Promise<void>;

Parameters

Name	Type	Description
mode (optional)	SelectionMode	"select" (whole area) / "start" (cursor at the start of the area) / "end" (cursor at the end of the area) (default: SelectionMode.SELECT)

Returns

Promise<void>