A lightweight library for parsing xml to DOM tree, and vice versa.
npm install xml-js-domParsing and serializing operations rely on the project xml-js.
The DOM implementation is try the best to be compatible with the W3C Recommendation.
However, for the sake of convenient usage, subtle changes and differences may be introduced.
_The whole project is written by typescript. We strongly recommend you use typescript to reduce silly bugs.
Anyway, if typescript isn't your cup of tea, just take this as a regular javascript project._
``typescript
import {parse, toXml, Node} from "xml-js-dom";
// Parse xml to the DOM tree
const node: Node = parse('
// node is the toppest item of the XML, usually it's an object of Document.
// Serialize DOM tree to XML
const xml: string = toXml(node); // Now the xml is exactly the content we just parsed.
`
A DOM tree consists of different kinds of items, like Document, Element, Text, Attribute, etc. All these itemsindex
are exported by the module. So you could import any kinds of items like
`typescript`
import {Document, Element, Text, Attribute} from "xml-js-dom";
or in CommonJS mode:
`javascript`
const {Document, Element, Text, Attribute} = requre('xml-js-dom');
_Currently only partial of the types and functions of the XML items have been implemented. We're trying our best to work for this. And of course any contributions to this project are great welcome._
#### Classes & Modules
Node
NodeGroup
Document
Element
CharacterData
Text
CDATASection
Attr
ProcessingInstruction
Declaration
Comment
#### index
[Methods]
parse(xml: string, opts: ParsingOptions = {}): Node | null
Parse the giving into the DOM tree, and return the root node(usually is a Document) of the tree.ParsingOptions
The is similar to XML2JS, with the extra field nodeFactory indicated which factory for producing nodes should be used. (In most case the default factory is good enough)
toXml(node: Node | BackingData, opts: Options.JS2XML = {}): string
Serialize the DOM tree into the XML string. Please refer the JS2XML for more infomation.
#### Node
[Attributes]
readonly nodeName: string
The name of the node. See doc.
nodeValue: string | null
The value of the node.
readonly nodeType: number
The type of the node. See doc.
parentNode: Node | null
The parent of this node.
childNodes: NodeList
All the children belong to this node.
readonly firstChild: Node | null
The first node in the child node list.
readonly lastChild: Node | null
The last node in the child node list.
readonly previousSibling: Node | null
The previous node in the node list which shares the same parent with this node.
readonly nextSibling: Node | null
The next node in the node list which shares the same parent with this node.
readonly localName: string | null
The local name of this node. That is, the name without the namespace prefix.
prefix: string | null
The namespace prefix of this node. The prefix will be automatically inserted to the front of the tag name.
readonly attributes: NamedNodeMap
All the attributes belong to this node.
readonly ownerDocument: Document | null
The root document of this node. Null if this node doesn't belong to any DOM tree.
readonly origin: BackingData
The data object representing the sub DOM tree. Could be generated by the xml-js and serialized vice versa.
[Methods]
insertBefore(newChild: Node, refChild?: Node | null): Node
Insert the new node right before the specific one. If no ref node specified, append the new node to the tail of the child node list. Return the node inserted.
replaceChild(newChild: Node, oldChild: Node): Node
Replace the old node with the new node. Error will be thrown if the old node is null or doesn't belong to this node. Return the replaced node.
removeChild(oldChild: Node): Node
Remove the specific node. Error will be thrown if the old node doesn't belong to this node. Return the removed node.
removeAllChildren(): void
Clear the child node list.
appendChild(newChild: Node): Node
Append the new node to the tail of the child node list. Return the appended node.
hasAttributes(): boolean
Whether contains attribute nodes.
hasChildNodes(): boolean
Whether contains child nodes.
getTextValue(): string
Collect and return all the text(including Text and CDATASection) values belong to this node and all the decedents. Using DFS(depth-first-search).
detach(): Node
Remove self from the parent node. Return self.
cloneNode(deep?: boolean): Node
Duplicate the node (and all the decedents if is true). Modify the cloned node is guaranteed NOT infect the original one, and vice versa.
protected _cloneObject(obj: BackingData | BackingData[]): BackingData | BackingData[]
The implementation of deep copy of the objects and arrays using by the .
#### NodeGroup => Node
#### Document => NodeGroup
[Attributes]
readonly documentElement: Element | null
The direct child element of this document. If multiple child elements exists(which is actually illegal), the first one obtained.
readonly root: Element | null
The alias of
declaration: Declaration | null
The declaration of this XML.
[Methods]
importNode(importedNode: Node, deep: boolean): Node
Clone the and return it.
#### Element => NodeGroup
[Attributes]
tagName: string
The full name of this element. Consists of the namespace prefix and local name.
readonly localName: string
The name of this element without the namespace prefix.
prefix: string | null
The prefix of the namespace. Change this value will infect the .
text: string
This essentially represents the concatenation of all and CDATASection nodes in this.childNodes, without the recurse call into child elements. Modify this value will result for clearing ALL the child nodes of this node and appending the Text node.
readonly textTrim: string
Similar to but trim the value returned.
[Methods]
setAttribute(name: string, value: string): void setAttributeNode(newAttr: Attr): void
Add an attribute to this element.
getAttribute(name: string): string getAttributeNode(name: string): Attr | undefined
Retrieve the attribute node or value with the specific name.
removeAttribute(name: string): Attr | null removeAttributeNode(oldAttr: Attr): Attr | null
Remove the specific attribute node and return it.
setNamespace(namespace?: Namespace | null): void undefined
Set the namespace of this element. If the namespace is or null, the namespace of this node will be cleared.xmlns
The namespace of a child element could be inherited from its ascendants. So if the namespace of the same prefix could be found from the ascendants, (that is, the same url corresponds to the prefix could be found), only the previous attribute (if any) will be removed and the tagName will be changed.xmlns
Otherwise, besides the previous attribute and tagName, a new attribute of xmlns:{prefix}="{url}" will also be added to the element. For example, `xml`
If we calltypescript`
subElement.setNamespace({prefix: '', url: 'http://app.org'}); // subElement represents element
Then we will getxml`
Instead, if we calltypescript`
subElement.setNamespace({prefix: '', url: 'http://program.org'}); // Again, subElement represents
We will getxml`
getNamespace(): Namespace | null
Get the namespace of this element. Note that child node could inherit the namespace from its ascendants. So this method may call the ascendants recursively. will be returned if both prefix and url are empty.
getNamespaceUrl(prefix: string | null): string
Get the url of the namespace by the giving prefix. Notice that the prefix doesn't have to be the same as the element's prefix. It will look for the url from ascendants recursively.
protected _constructNsAttrName(prefix: string | null): string
Construct the attribute name represents for the namespace. By default, the name is (colon will be omitted if prefix is empty).
#### CharacterData => Node
[Attributes]
data: string
The text content of this node.
readonly length: number
The length of the content.
[Methods]
appendData(data: string): void
Concat the to the current content.
deleteData(offset: number, count: number): void
Remove the substring from to offset + count.
insertData(offset: number, data: string): void
Insert the to the position of offset.
replaceData(offset: number, count: number, data: string): void
Replace the substring from to offset + count with data.
substringData(offset: number, count: number): string
Fetch the substring from to offset + count.
#### Text => CharacterData
[Methods]
splitText(offset: number): Text
Split the content from the giving position. The former part will be left to this node, while the latter part will be wrapped into a new Text and insert after this node. Return the Text node represents the latter part.
#### CDATASection => CharacterData
This is similar to Text, except all the character here will be reserved without escaped.
#### Attr => Node
[Attributes]
readonly name: string
The name of the attribute.
ownerElement: Element | null
The element this attribute node belongs to, or if it doesn't belong to any element.
value: string
The value of the attribute.
valueChangedListener: (attr: Attr) => void | undefined
The function be called when the value of this attribute changed. Usually this is using for updating the origin data of the owner element.
[Methods]
detach(): Attr
Remove self from the and return self.
#### ProcessingInstruction => Node
[Attributes]
target: string
The target of this processing instruction.
instruction: string
The content of this processing instruction.
data: string
Alias of .
#### Declaration => Node
[Attributes]
ownerDocument: Document | null
The document this declaration belongs to.
version: string
The version of this XML standard used.
encoding: string
The encoding used in this XML. Default is utf-8.
standalone: 'yes' | 'no' | ''
It informs the parser whether the document relies on the information from an external source, such as external document type definition (DTD), for its content. The default value is set to _no_.
Setting it to yes tells the processor there are no external declarations required for parsing the document.
#### Comment => CharacterData
[Attributes]
data: string
The text content of node, which is always an empty string. Being empty ensure that Node.prototype.getTextValue() andElement.prototype.text could return the correct value (without the comment).
length: number
The length of the , which is always 0.
nodeValue: string
The actual content of comment.
#### NodeList\
[Methods]
item(index: number): N | null
Fetch the item at the position of .
#### NamedNodeMap\
[Attributes]
length: number
The size of this map.
[Symbol.iterator]: IterableIterator
Fetch the iterator of the values of this map.
[Methods]
setNamedItem(node: N): void
Add the giving to this map with the key of the nodeName of the node.
getNamedItem(name: string): N | undefined
Fetch the item set before by name.
removeNamedItem(name: string): N | null
Remove the item set before by name.
item(index: number): N | null
Fetch the item by the giving . Notice that although this method will return the node according to the order they've been inserted,
this behavior has NOT been strictly defined. So use this method only if you exactly know what you're doing.
#### Namespace
[Attributes]
prefix: string | null
The prefix represents the namespace.
url: string
The url identify the namespace.
#### BackingData
All the BackingData` and its decedents could be referred to xml-js API. Non-compact mode is used here.