OpenXmlSdkTs - v1.0.7
    Preparing search index...

    Class XElement

    Represents an XML element -- the primary class in LtXmlTs.

    An XElement has a name, zero or more attributes, and zero or more child nodes. It supports functional construction (passing children and attributes to the constructor), parsing from strings or files, and serialisation to XML strings.

    const el = new XElement('item',
      new XAttribute('id', '1'),
      new XElement('name', 'Widget'),
    );
    const copy = new XElement(el); // clone

    Hierarchy

    • XContainer
      • XElement
    Index

    Constructors

    constructor

    Properties

    name nodeType parent

    Accessors

    firstNode lastNode value firstAttribute lastAttribute hasAttributes hasElements isEmpty previousNode nextNode document

    Methods

    nodes insertAfterChild add replaceNodes removeNodes elements element descendantNodes descendants addFirst insertBeforeChild replaceChild removeChild attributes attribute descendantNodesAndSelf descendantsAndSelf removeAttribute removeAttributes replaceAttributes setAttributeValue setElementValue removeAll replaceAll ancestorsAndSelf equals toString toStringWithIndentation parse load loadAsync addAfterSelf addBeforeSelf replaceWith ancestors elementsAfterSelf elementsBeforeSelf nodesBeforeSelf nodesAfterSelf remove deepEquals deepEquals addAnnotation annotation annotations removeAnnotations

    Constructors

    • Creates an empty XElement with the given name.

      Parameters

      • name: string | XName

        The element name (string or XName).

      Returns XElement

      • new XElement(name) creates an empty element.
      • new XElement(name, ...content) creates an element with child nodes and/or attributes via functional construction.
      • new XElement(other) deep-clones an existing element.
      const el = new XElement('item',
        new XAttribute('id', '1'),
        new XElement('name', 'Widget'),
      );
      const copy = new XElement(el); // clone

    • Creates an XElement with the given name and content.

      Parameters

      • name: string | XName

        The element name (string or XName).

      • ...content: unknown[]

        Child nodes, attributes, strings, or arrays thereof.

      Returns XElement

    • Deep-clones an existing XElement.

      Parameters

      Returns XElement

    Properties

    name: XName

    The qualified name of this element.

    nodeType: XmlNodeType

    The kind of XML node this object represents.

    const el = new XElement('root');
    console.log(el.nodeType); // 'Element'
    parent: XObject | null

    The parent of this object in the XML tree, or null if it is a root.

    const child = new XElement('child');
    const parent = new XElement('parent', child);
    console.log(child.parent === parent); // true

    Accessors

    • get firstNode(): XNode | null

      Gets the first child node, or null if the container is empty.

      Returns XNode | null

    • get lastNode(): XNode | null

      Gets the last child node, or null if the container is empty.

      Returns XNode | null

    • get value(): string

      Gets the concatenated text content of this element and all its descendants.

      Returns string

      The setter replaces all child nodes with a single XText node.

      const el = new XElement('title', 'Hello ', new XElement('em', 'World'));
      el.value; // 'Hello World'
      el.value = 'New text';
    • set value(value: string): void

      Parameters

      • value: string

      Returns void

    • get firstAttribute(): XAttribute | null

      Gets the first attribute of this element, or null if there are none.

      Returns XAttribute | null

    • get lastAttribute(): XAttribute | null

      Gets the last attribute of this element, or null if there are none.

      Returns XAttribute | null

    • get hasAttributes(): boolean

      Returns true if this element has at least one attribute.

      Returns boolean

    • get hasElements(): boolean

      Returns true if this element contains at least one child element.

      Returns boolean

    • get isEmpty(): boolean

      Returns true if this element has no child nodes.

      Returns boolean

    • get previousNode(): XNode | null

      Gets the previous sibling node, or null if this is the first node.

      Returns XNode | null

    • get nextNode(): XNode | null

      Gets the next sibling node, or null if this is the last node.

      Returns XNode | null

    • get document(): XDocument | null

      Gets the XDocument that contains this object, or null if the object is not part of a document tree.

      Returns XDocument | null

      const doc = new XDocument(new XElement('root', new XElement('child')));
      const child = doc.root!.elements()[0];
      console.log(child.document === doc); // true

    Methods

    • Returns a shallow copy of this container's child nodes.

      Returns XNode[]

      A new array containing all direct child XNode instances.

    • Inserts content immediately after an existing child node.

      Parameters

      • child: XNode

        The reference child node.

      • ...content: unknown[]

        Content to insert after the child.

      Returns void

    • Appends content as children of this container.

      Parameters

      • ...content: unknown[]

        Nodes, strings, or arrays to add.

      Returns void

      Content rules:

      • XElement and other XNode subclasses are added as child nodes.
      • Strings are wrapped in XText.
      • Arrays are recursively unpacked.
      • XAttribute objects passed here are silently ignored; pass attributes to the XElement constructor or use XElement.setAttributeValue instead.
      • If a node already has a parent, it is cloned before being added.

    • Replaces all child nodes with the specified content.

      Parameters

      • ...content: unknown[]

        New content to use as children.

      Returns void

    • Removes all child nodes from this container.

      Returns void

    • Returns the child elements of this container.

      Returns XElement[]

      An array of direct child XElement instances.

    • Returns the child elements of this container filtered by name.

      Parameters

      • name: string | XName

        Name to filter by.

      Returns XElement[]

    • Returns the first child element with the specified name, or null.

      Parameters

      • name: string | XName

        The element name to match.

      Returns XElement | null

      The first matching child XElement, or null.

    • Returns all descendant nodes of this container in document order.

      Returns XNode[]

      A flat array of all descendant XNode instances.

    • Returns all descendant elements of this container in document order.

      Returns XElement[]

      An array of descendant XElement instances.

    • Returns all descendant elements of this container in document order, filtered by name.

      Parameters

      • name: string | XName

        Name to filter by.

      Returns XElement[]

    • Inserts content as the first children of this container.

      Parameters

      • ...content: unknown[]

        Nodes, strings, or arrays to prepend.

      Returns void

    • Inserts content immediately before an existing child node.

      Parameters

      • child: XNode

        The reference child node.

      • ...content: unknown[]

        Content to insert before the child.

      Returns void

    • Replaces an existing child node with the specified content.

      Parameters

      • child: XNode

        The child node to replace.

      • ...content: unknown[]

        Content that replaces the child.

      Returns void

    • Removes a specific child node from this container.

      Parameters

      • child: XNode

        The child node to remove.

      Returns void

    • Returns the attributes of this element.

      Returns XAttribute[]

      An array of XAttribute instances.

    • Returns the attributes of this element filtered by name.

      Parameters

      • name: string | XName

        Name to filter by.

      Returns XAttribute[]

    • Returns the attribute with the specified name, or null.

      Parameters

      • name: string | XName

        The attribute name to look up.

      Returns XAttribute | null

      The matching XAttribute, or null.

    • Returns this element followed by all its descendant nodes in document order.

      Returns XNode[]

      An array starting with this element and including all descendant nodes.

    • Returns this element followed by all its descendant elements in document order.

      Returns XElement[]

      An array starting with this element (if it matches) and including all matching descendant elements.

    • Returns this element followed by all its descendant elements in document order, filtered by name.

      Parameters

      • name: string | XName

        Name to filter by.

      Returns XElement[]

    • Removes a specific attribute from this element.

      Parameters

      • attr: XAttribute

        The attribute instance to remove.

      Returns void

    • Removes all attributes from this element.

      Returns void

    • Replaces all attributes on this element with the specified content.

      Parameters

      • ...content: unknown[]

        New attributes (or arrays of attributes) to set.

      Returns void

    • Sets, updates, or removes an attribute by name.

      Parameters

      • name: string | XName

        The attribute name.

      • value: string | null

        The new value, or null to remove.

      Returns void

      If value is null, the attribute is removed (if it exists). Otherwise the attribute is created or updated with the new value.

      el.setAttributeValue('id', '42');   // add or update
      el.setAttributeValue('id', null);   // remove

    • Sets, updates, or removes a child element by name.

      Parameters

      • name: string | XName

        The child element name.

      • value: string | null

        The new text value, or null to remove.

      Returns void

      If value is null, the matching child element is removed. If the child exists, its content is replaced. Otherwise a new child element is created.

    • Removes all attributes and child nodes from this element.

      Returns void

    • Replaces all attributes and child nodes with the specified content.

      Parameters

      • ...content: unknown[]

        New content (nodes, attributes, strings, or arrays).

      Returns void

    • Returns this element followed by all its ancestor elements.

      Returns XElement[]

      An array starting with this element and continuing to the root.

    • Returns this element followed by all its ancestor elements, filtered by name.

      Parameters

      • name: string | XName

        Name to filter by.

      Returns XElement[]

    • Compares this element with another for structural equality, including name, attributes, and all child nodes.

      Parameters

      • other: XElement

        The element to compare against.

      Returns boolean

      true if the elements are structurally identical.

    • Serialises this element and its subtree to an XML string.

      Returns string

      The XML string representation.

    • Serialises this element to an indented (pretty-printed) XML string.

      Returns string

      The indented XML string.

      const root = new XElement('root', new XElement('child', new XElement('leaf')));
      root.toStringWithIndentation();
      // <root>
      //   <child>
      //     <leaf />
      //   </child>
      // </root>

    • Parses an XML string into an XElement.

      Parameters

      • xml: string

        The XML string to parse.

      Returns XElement

      The parsed element.

      const el = XElement.parse('<items><item id="1"/></items>');

    • Loads an XML file synchronously and parses it into an XElement.

      Parameters

      • filePath: string

        Path to the XML file.

      Returns XElement

      The parsed element.

      const el = XElement.load('/path/to/data.xml');

    • Loads an XML file asynchronously and parses it into an XElement.

      Parameters

      • filePath: string

        Path to the XML file.

      Returns Promise<XElement>

      A promise that resolves to the parsed element.

      const el = await XElement.loadAsync('/path/to/data.xml');

    • Inserts the specified content immediately after this node in its parent.

      Parameters

      • ...content: unknown[]

        One or more nodes or strings to insert.

      Returns void

      Error if this node has no parent.

      const parent = new XElement('p', new XElement('a'), new XElement('c'));
      const a = parent.elements()[0];
      a.addAfterSelf(new XElement('b'));
      // parent now contains <a/>, <b/>, <c/>

    • Inserts the specified content immediately before this node in its parent.

      Parameters

      • ...content: unknown[]

        One or more nodes or strings to insert.

      Returns void

      Error if this node has no parent.

    • Replaces this node with the specified content.

      Parameters

      • ...content: unknown[]

        One or more nodes or strings that replace this node.

      Returns void

      Error if this node has no parent.

    • Returns a collection of the ancestor elements of this node.

      Returns XElement[]

      An array of ancestor XElement instances.

      When called with no arguments, returns all ancestor elements from the immediate parent up to the root. When a name is supplied, only ancestors with that name are returned. The collection is ordered from nearest ancestor to farthest.

      const xml = XElement.parse('<root><a><b/></a></root>');
      const b = xml.descendants('b')[0];
      b.ancestors();        // [<a>, <root>]
      b.ancestors('root');  // [<root>]

    • Returns a collection of the ancestor elements of this node filtered by name.

      Parameters

      • name: string | XName

        Name to filter ancestors by.

      Returns XElement[]

    • Returns the sibling elements that follow this node.

      Returns XElement[]

      An array of sibling XElement instances after this node.

      const parent = new XElement('p', new XElement('a'), new XElement('b'), new XElement('c'));
      const a = parent.elements()[0];
      a.elementsAfterSelf(); // [<b>, <c>]

    • Returns the sibling elements that follow this node, filtered by name.

      Parameters

      • name: string | XName

        Name to filter by.

      Returns XElement[]

    • Returns the sibling elements that precede this node.

      Returns XElement[]

      An array of sibling XElement instances before this node.

    • Returns the sibling elements that precede this node, filtered by name.

      Parameters

      • name: string | XName

        Name to filter by.

      Returns XElement[]

    • Returns all sibling nodes that precede this node.

      Returns XNode[]

      An array of XNode instances before this node.

    • Returns all sibling nodes that follow this node.

      Returns XNode[]

      An array of XNode instances after this node.

    • Removes this node from its parent.

      Returns void

      Error if this node has no parent.

    • Performs a deep structural comparison of this node with another.

      Parameters

      • other: XNode

        The node to compare against.

      Returns boolean

      true if the two nodes are structurally identical.

      Two nodes are deeply equal when they have the same node type and their content (including all descendants and attributes for elements) is equal.

      const e1 = XElement.parse('<a x="1"><b/></a>');
      const e2 = XElement.parse('<a x="1"><b/></a>');
      e1.deepEquals(e2); // true

    • Static convenience method for deep structural comparison of two nodes.

      Parameters

      • a: XNode

        First node.

      • b: XNode

        Second node.

      Returns boolean

      true if the two nodes are structurally identical.

      const e1 = XElement.parse('<a x="1"><b/></a>');
      const e2 = XElement.parse('<a x="1"><b/></a>');
      XNode.deepEquals(e1, e2); // true

    • Attaches an arbitrary annotation object to this XML object.

      Parameters

      • obj: unknown

        The annotation object to attach.

      Returns void

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));

    • Returns the first annotation of the specified type, or null if none exists.

      Type Parameters

      • T

        The annotation class to look up.

      Parameters

      • ctor: new (...args: any[]) => T

        Constructor of the annotation type to retrieve.

      Returns T | null

      The first matching annotation, or null.

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));
      const m = el.annotation(MyMeta);
      console.log(m?.tag); // 'important'

    • Returns all annotations of the specified type.

      Type Parameters

      • T

        The annotation class to look up.

      Parameters

      • ctor: new (...args: any[]) => T

        Constructor of the annotation type to retrieve.

      Returns T[]

      An array of matching annotations (may be empty).

    • Removes annotations from this object.

      Returns void

      When called with no arguments, all annotations are removed. When called with a constructor, only annotations of that type are removed.

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));
      el.removeAnnotations(MyMeta);  // removes only MyMeta annotations
      el.removeAnnotations();        // removes everything

    • Removes annotations from this object.

      Type Parameters

      • T

      Parameters

      • ctor: new (...args: any[]) => T

      Returns void

      When called with no arguments, all annotations are removed. When called with a constructor, only annotations of that type are removed.

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));
      el.removeAnnotations(MyMeta);  // removes only MyMeta annotations
      el.removeAnnotations();        // removes everything

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods