Edit

Share via

Word.XmlNode class

Package:
word

Represents a single XML node applied to the document.

Extends
OfficeExtension.ClientObject

Remarks

[ API set: WordApiDesktop 1.4 ]

Properties

attributes

Gets the attributes for this XML node. Returns null if the node type is attribute.
baseName

Gets the name of the element without any prefix.
childNodes

Gets the child elements of this XML node. Returns an empty collection if the node type is attribute.
context

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

Gets the first child node if this is a parent node. Returns null if the node type is attribute.
hasChildNodes

Gets whether this XML node has child nodes. Always returns false for attribute nodes since they cannot have children.
lastChild

Gets the last child node if this is a parent node. Returns null if the node type is attribute.
level

Gets whether this XML element is part of a paragraph, is a paragraph, or is contained within a table cell or contains a table row. Returns null if the node type is attribute.
namespaceUri

Gets the Uniform Resource Identifier (URI) of the schema namespace for this XML node.
nextSibling

Gets the next element in the document that's at the same level as this XML node. Returns null if the node type is attribute.
ownerDocument

Gets the parent document of this XML node.
parentNode

Gets the parent element of this XML node.
placeholderText

Specifies the text displayed for this element if it contains no text. Only applies to element nodes, not attribute nodes.
previousSibling

Gets the previous element in the document that's at the same level as this XML node. Returns null if the node type is attribute.
range

Gets the portion of a document that is contained in this XML node. Returns null if the node type is attribute.
text

Specifies the text contained within the XML element. Returns an empty string if the node type is attribute.
type

Gets the type of node.
validationErrorText

Gets the description for a validation error on this XmlNode object. May not be meaningful for attribute nodes.
validationStatus

Gets whether this element is valid according to the attached schema. May not be meaningful for attribute nodes.
value

Specifies the value of this XML node. For element nodes, represents the text content; for attribute nodes, represents the attribute value.

Methods

copy()

Copies this XML node, excluding XML markup, to the Clipboard. For attribute nodes, copies only the attribute value as text.
cut()

Removes this XML node from the document and places it on the Clipboard. For attribute nodes, removes the attribute from its parent element and copies only the attribute value as text to the clipboard.
delete()

Deletes the XML node from the XML document. For element nodes, removes the entire element and its content; for attribute nodes, removes the attribute from its parent element.
load(options)

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

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

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

Removes a child element from this XML node. This method has no effect if the node type is attribute (since attribute nodes have no child elements).
selectNodes(xPath, options)

Returns all the child elements that match the XPath parameter, in the order in which they appear within this XML node. Returns null if the node type is attribute (since attribute nodes have no child elements to search).
selectSingleNode(xPath, options)

Returns the first child element that matches the XPath parameter within this XML node. Returns null if the node type is attribute (since attribute nodes have no child elements to search).
setValidationError(status, options)

Changes the validation error text displayed to a user for this XML node and whether to force Word to report the node as invalid. May not be meaningful for attribute nodes.
setValidationError(status, options)

Changes the validation error text displayed to a user for this XML node and whether to force Word to report the node as invalid. May not be meaningful for attribute nodes.
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.XmlNode object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.XmlNodeData) that contains shallow copies of any loaded child properties from the original object.
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.
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.
validate()

Validates this XML node against the XML schemas that are attached to the document. May not be meaningful for attribute nodes.

Property Details

attributes

Gets the attributes for this XML node. Returns null if the node type is attribute.

readonly attributes: Word.XmlNodeCollection;

Property Value

Word.XmlNodeCollection

Remarks

[ API set: WordApiDesktop 1.4 ]

baseName

Gets the name of the element without any prefix.

readonly baseName: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.4 ]

childNodes

Gets the child elements of this XML node. Returns an empty collection if the node type is attribute.

readonly childNodes: Word.XmlNodeCollection;

Property Value

Word.XmlNodeCollection

Remarks

[ API set: WordApiDesktop 1.4 ]

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

Word.RequestContext

firstChild

Gets the first child node if this is a parent node. Returns null if the node type is attribute.

readonly firstChild: Word.XmlNode;

Property Value

Word.XmlNode

Remarks

[ API set: WordApiDesktop 1.4 ]

hasChildNodes

Gets whether this XML node has child nodes. Always returns false for attribute nodes since they cannot have children.

readonly hasChildNodes: boolean;

Property Value

boolean

Remarks

[ API set: WordApiDesktop 1.4 ]

lastChild

Gets the last child node if this is a parent node. Returns null if the node type is attribute.

readonly lastChild: Word.XmlNode;

Property Value

Word.XmlNode

Remarks

[ API set: WordApiDesktop 1.4 ]

level

Gets whether this XML element is part of a paragraph, is a paragraph, or is contained within a table cell or contains a table row. Returns null if the node type is attribute.

readonly level: Word.XmlNodeLevel | "Inline" | "Paragraph" | "Row" | "Cell";

Property Value

Word.XmlNodeLevel | "Inline" | "Paragraph" | "Row" | "Cell"

Remarks

[ API set: WordApiDesktop 1.4 ]

namespaceUri

Gets the Uniform Resource Identifier (URI) of the schema namespace for this XML node.

readonly namespaceUri: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.4 ]

nextSibling

Gets the next element in the document that's at the same level as this XML node. Returns null if the node type is attribute.

readonly nextSibling: Word.XmlNode;

Property Value

Word.XmlNode

Remarks

[ API set: WordApiDesktop 1.4 ]

ownerDocument

Gets the parent document of this XML node.

readonly ownerDocument: Word.Document;

Property Value

Word.Document

Remarks

[ API set: WordApiDesktop 1.4 ]

parentNode

Gets the parent element of this XML node.

readonly parentNode: Word.XmlNode;

Property Value

Word.XmlNode

Remarks

[ API set: WordApiDesktop 1.4 ]

placeholderText

Specifies the text displayed for this element if it contains no text. Only applies to element nodes, not attribute nodes.

placeholderText: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.4 ]

previousSibling

Gets the previous element in the document that's at the same level as this XML node. Returns null if the node type is attribute.

readonly previousSibling: Word.XmlNode;

Property Value

Word.XmlNode

Remarks

[ API set: WordApiDesktop 1.4 ]

range

Gets the portion of a document that is contained in this XML node. Returns null if the node type is attribute.

readonly range: Word.Range;

Property Value

Word.Range

Remarks

[ API set: WordApiDesktop 1.4 ]

text

Specifies the text contained within the XML element. Returns an empty string if the node type is attribute.

text: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.4 ]

type

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.

Gets the type of node.

readonly type: Word.XmlNodeType | "Element" | "Attribute";

Property Value

Word.XmlNodeType | "Element" | "Attribute"

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

validationErrorText

Gets the description for a validation error on this XmlNode object. May not be meaningful for attribute nodes.

readonly validationErrorText: string;

Property Value

string

Remarks

[ API set: WordApiDesktop 1.4 ]

validationStatus

Gets whether this element is valid according to the attached schema. May not be meaningful for attribute nodes.

readonly validationStatus: Word.XmlValidationStatus | "Ok" | "Custom";

Property Value

Word.XmlValidationStatus | "Ok" | "Custom"

Remarks

[ API set: WordApiDesktop 1.4 ]

value

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 value of this XML node. For element nodes, represents the text content; for attribute nodes, represents the attribute value.

value: string;

Property Value

string

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Method Details

copy()

Copies this XML node, excluding XML markup, to the Clipboard. For attribute nodes, copies only the attribute value as text.

copy(): void;

Returns

void

Remarks

[ API set: WordApiDesktop 1.4 ]

cut()

Removes this XML node from the document and places it on the Clipboard. For attribute nodes, removes the attribute from its parent element and copies only the attribute value as text to the clipboard.

cut(): void;

Returns

void

Remarks

[ API set: WordApiDesktop 1.4 ]

delete()

Deletes the XML node from the XML document. For element nodes, removes the entire element and its content; for attribute nodes, removes the attribute from its parent element.

delete(): void;

Returns

void

Remarks

[ API set: WordApiDesktop 1.4 ]

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.XmlNodeLoadOptions): Word.XmlNode;

Parameters

options
Word.Interfaces.XmlNodeLoadOptions

Provides options for which properties of the object to load.

Returns

Word.XmlNode

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.XmlNode;

Parameters

propertyNames

string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Word.XmlNode

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.XmlNode;

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

Word.XmlNode

removeChild(childElement)

Removes a child element from this XML node. This method has no effect if the node type is attribute (since attribute nodes have no child elements).

removeChild(childElement: Word.XmlNode): void;

Parameters

childElement
Word.XmlNode

The child element to remove.

Returns

void

Remarks

[ API set: WordApiDesktop 1.4 ]

selectNodes(xPath, options)

Returns all the child elements that match the XPath parameter, in the order in which they appear within this XML node. Returns null if the node type is attribute (since attribute nodes have no child elements to search).

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

Parameters

xPath

string

The XPath expression to evaluate.

options
Word.SelectNodesOptions

Optional. Configuration options for the XPath search.

Returns

Word.XmlNodeCollection

A collection of XML nodes that match the XPath expression.

Remarks

[ API set: WordApiDesktop 1.4 ]

selectSingleNode(xPath, options)

Returns the first child element that matches the XPath parameter within this XML node. Returns null if the node type is attribute (since attribute nodes have no child elements to search).

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

Parameters

xPath

string

The XPath expression to evaluate.

options
Word.SelectSingleNodeOptions

Optional. Configuration options for the XPath search.

Returns

Word.XmlNode

The first XML node that matches the XPath expression, or null if no match is found.

Remarks

[ API set: WordApiDesktop 1.4 ]

setValidationError(status, options)

Changes the validation error text displayed to a user for this XML node and whether to force Word to report the node as invalid. May not be meaningful for attribute nodes.

setValidationError(status: Word.XmlValidationStatus, options?: Word.XmlNodeSetValidationErrorOptions): void;

Parameters

status
Word.XmlValidationStatus

The validation status to set.

options
Word.XmlNodeSetValidationErrorOptions

Optional. Configuration options for setting the validation error.

Returns

void

Remarks

[ API set: WordApiDesktop 1.4 ]

setValidationError(status, options)

Changes the validation error text displayed to a user for this XML node and whether to force Word to report the node as invalid. May not be meaningful for attribute nodes.

setValidationError(status: "Ok" | "Custom", options?: Word.XmlNodeSetValidationErrorOptions): void;

Parameters

status

"Ok" | "Custom"

The validation status to set.

options
Word.XmlNodeSetValidationErrorOptions

Optional. Configuration options for setting the validation error.

Returns

void

Remarks

[ API set: WordApiDesktop 1.4 ]

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.XmlNode object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.XmlNodeData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Word.Interfaces.XmlNodeData;

Returns

Word.Interfaces.XmlNodeData

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.XmlNode;

Returns

Word.XmlNode

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.XmlNode;

Returns

Word.XmlNode

validate()

Validates this XML node against the XML schemas that are attached to the document. May not be meaningful for attribute nodes.

validate(): void;

Returns

void

Remarks

[ API set: WordApiDesktop 1.4 ]