對象XmlDocument

XmlDocument 是 xml模組的一個對象，它代表整個XML 文檔，提供了對整個文檔的存取入口

XmlDocument 是一棵文檔樹的根，包含了整個XML 文件中的所有節點。 XmlDocument 物件同樣提供了以下功能：

建立元素節點、文字節點、註解和處理指令等
存取和修改文件屬性和相關資訊（如DTD 註釋及文件聲明）
解析XML 文件

下面是使用XmlDocument 物件解析一個XML 文件的範例程式碼：

1
2
3
4
5
6
7
8
9
var xml = require('xml');
var fs = require('fs');

var xmlStr = fs.readFile('test.xml');
var xmlDoc = xml.parse(xmlStr);

// get document root node name
var rootName = xmlDoc.documentElement.nodeName;
console.log(`文档根节点名称是 ${rootName}`);

在上述程式碼中，我們首先使用fs模組的readFile()方法讀取了一個XML 文件，並將文件流賦值給變數xmlStr。然後我們使用[xml](../../module/ifs/xml.md)模組的parse()方法解析該XML 文件，並將解析後的XmlDocument物件賦值給變數xmlDoc。最後我們使用xmlDoc的documentElement屬性來取得文檔根節點，並取得其節點名稱，輸出到控制台上。

由於XmlDocument 是整個XML 文件的入口，因此我們可以透過它來取得和修改文件的相關資訊。例如，我們可以透過xmlDoc.xmlVersion和xmlDoc.xmlStandalone分別取得和修改文件的XML 版本和standalone 屬性。我們也可以透過xmlDoc.createProcessingInstruction()方法來建立新的處理指令節點。

XmlDocument 物件是一個非常強大的類型，為我們處理解析XML 檔案提供了很大的便利。

繼承關係

建構函數

XmlDocument

建構一個XmlDocument 對象

1
new XmlDocument(String type = "text/xml");

呼叫參數:

type: String, 指定文件物件的類型，預設為"text/xml"，若需要處理html 則需要指定"text/html"

成員屬性

inputEncoding

String, 傳回用於文件的編碼（在解析時）

1
readonly String XmlDocument.inputEncoding;

xmlStandalone

Boolean, 設定或傳回文件是否為standalone

1
Boolean XmlDocument.xmlStandalone;

xmlVersion

String, 設定或傳回文件的XML 版本

1
String XmlDocument.xmlVersion;

doctype

XmlDocumentType, 傳回與文件相關的文檔類型聲明（Document Type Declaration）

1readonly XmlDocumentType XmlDocument.doctype;

對於沒有DTD 的XML 文檔，則傳回null。此屬性可提供對XmlDocumentType物件（ XmlDocument 的一個子節點）的直接存取。

documentElement

XmlElement, 傳回文檔的根節點

1readonly XmlElement XmlDocument.documentElement;

head

XmlElement, 傳回HTML 文件的head 節點，僅在html 模式有效

1readonly XmlElement XmlDocument.head;

title

String, 傳回HTML 文件的title 節點的內容，僅在html 模式有效

1
readonly String XmlDocument.title;

body

XmlElement, 傳回HTML 文件的body 節點，僅在html 模式有效

1readonly XmlElement XmlDocument.body;

nodeType

Integer, 傳回節點的節點類型

1readonly Integer XmlDocument.nodeType;

不同物件的nodeType 會傳回不同的值：

XmlElement: ELEMENT_NODE(1)
XmlAttr: ATTRIBUTE_NODE(2)
XmlText: TEXT_NODE(3)
XmlCDATASection: CDATA_SECTION_NODE(4)
XmlProcessingInstruction: PROCESSING_INSTRUCTION_NODE(7)
XmlComment: COMMENT_NODE(8)
XmlDocument: DOCUMENT_NODE(9)
XmlDocumentType: DOCUMENT_TYPE_NODE(10)

nodeName

String, 傳回節點的名稱，依其類型

1
readonly String XmlDocument.nodeName;

不同物件的nodeName 會傳回不同的值：

XmlElement: element name
XmlAttr: 屬性名稱
XmlText: #text
XmlCDATASection: #cdata-section
XmlProcessingInstruction: 傳回指定目標target
XmlComment: #comment
XmlDocument: #document
XmlDocumentType: doctype 名稱

nodeValue

String, 傳回節點的名稱，依其類型

1
String XmlDocument.nodeValue;

不同物件的nodeName 會傳回不同的值：

XmlElement: null
XmlAttr: 屬性的值
XmlText: 節點的內容
XmlCDATASection: 節點的內容
XmlProcessingInstruction: 傳回指定內容data
XmlComment: 註釋文本
XmlDocument: null
XmlDocumentType: null

ownerDocument

XmlDocument, 傳回節點的根元素（XmlDocument 物件）

1readonly XmlDocument XmlDocument.ownerDocument;

parentNode

XmlNode, 可返回某節點的父節點

1readonly XmlNode XmlDocument.parentNode;

childNodes

XmlNodeList, 傳回指定節點的子節點的節點列表

1readonly XmlNodeList XmlDocument.childNodes;

children

XmlNodeList, 傳回指定節點的子元素節點的節點列表

1readonly XmlNodeList XmlDocument.children;

firstChild

XmlNode, 返回節點的首個子節點

1readonly XmlNode XmlDocument.firstChild;

lastChild

XmlNode, 返回節點的最後一個子節點

1readonly XmlNode XmlDocument.lastChild;

previousSibling

XmlNode, 傳回某節點之前緊接的節點（處於同一樹層級），如果沒有此節點，那麼該屬性傳回null

1readonly XmlNode XmlDocument.previousSibling;

nextSibling

XmlNode, 傳回某個元素之後緊接的節點（處於同一樹層級中），如果無此節點，則屬性傳回null

1readonly XmlNode XmlDocument.nextSibling;

firstElementChild

XmlNode, 返回節點的首個子元素節點

1readonly XmlNode XmlDocument.firstElementChild;

lastElementChild

XmlNode, 返回節點的最後一個子元素節點

1readonly XmlNode XmlDocument.lastElementChild;

previousElementSibling

XmlNode, 傳回某節點之前緊接的元素節點（處於同一樹層級），如果沒有此節點，那麼該屬性傳回null

1readonly XmlNode XmlDocument.previousElementSibling;

nextElementSibling

XmlNode, 傳回某個元素之後緊接的元素節點（處於同一樹層級中），如果無此節點，則屬性傳回null

1readonly XmlNode XmlDocument.nextElementSibling;

textContent

String, 查詢並設定選定元素的文字。查詢時，返回元素節點內所有文字節點的值；設定時，刪除所有子節點，並用單一文字節點替換它們。

1
String XmlDocument.textContent;

成員函數

load

透過解析一個XML/HTML 字串來組成該文檔，不支援多語種

1
XmlDocument.load(String source);

呼叫參數:

source: String, 要解析的XML/HTML 文本，取決於文件建立時的類型

透過解析一個二進位XML/HTML 字串來組成該文檔，並根據語種自動轉換

1XmlDocument.load(Buffer source);

呼叫參數:

source:Buffer, 要解析的XML/HTML 文本，取決於文件建立時的類型

getElementsByTagName

傳回帶有指定名稱的所有元素的一個節點列表

1
XmlNodeList XmlDocument.getElementsByTagName(String tagName);

呼叫參數:

tagName: String, 需檢索的標籤名稱。值"*" 符合所有的標籤

回傳結果:

XmlNodeList, 文檔樹中具有指定標記的XmlElement節點的XmlNodeList集合。傳回的元素節點的順序就是它們在來源文件中出現的順序。

該方法將返回一個XmlNodeList物件（可作為只讀數組處理），該物件存放文件中具有指定標籤名的所有XmlElement節點，它們存放的順序就是在來源文檔中出現的順序。XmlNodeList物件是「活」的，也就是如果在文件中新增或刪除了指定標籤名的元素，它的內容會自動進行必要的更新。

getElementsByTagNameNS

傳回具有指定命名空間和名稱的所有元素的一個節點列表

1
2
XmlNodeList XmlDocument.getElementsByTagNameNS(String namespaceURI,
    String localName);

呼叫參數:

namespaceURI: String, 指定檢索的命名空間URI。值"*" 可符合所有的標籤
localName: String, 需檢索的標籤名稱。值"*" 符合所有的標籤

回傳結果:

XmlNodeList, 文檔樹中具有指定標記的XmlElement節點的XmlNodeList集合。傳回的元素節點的順序就是它們在來源文件中出現的順序。

此方法與getElementsByTagName() 方法相似，但它根據命名空間和名稱來檢索元素。

getElementById

傳回擁有指定id 屬性的元素

1
XmlElement XmlDocument.getElementById(String id);

呼叫參數:

id: String, 需檢索的id

回傳結果:

XmlElement, 節點樹中具有指定id 屬性的XmlElement節點

此方法將遍歷文檔的子孫節點，傳回一個XmlElement節點對象，表示第一個具有指定id 屬性的文檔元素。。

getElementsByClassName

傳回帶有指定class 名稱的所有元素的一個節點列表

1
XmlNodeList XmlDocument.getElementsByClassName(String className);

呼叫參數:

className: String, 需檢索的class 名稱

回傳結果:

XmlNodeList, 文檔樹中具有指定class 名稱的XmlElement節點的XmlNodeList集合。傳回的元素節點的順序就是它們在來源文件中出現的順序。

該方法將返回一個XmlNodeList物件（可作為只讀數組處理），該物件存放文件中具有指定class 名的所有XmlElement節點，它們存放的順序就是在來源文檔中出現的順序。XmlNodeList物件是「活」的，也就是如果在文件中新增或刪除了指定標籤名的元素，它的內容會自動進行必要的更新。

createElement

建立元素節點

1
XmlElement XmlDocument.createElement(String tagName);

呼叫參數:

tagName: String, 指定元素節點規定名稱

回傳結果:

XmlElement, 返回新建的XmlElement節點，具有指定的標籤名

createElementNS

建立具有指定命名空間的元素節點

1
2
XmlElement XmlDocument.createElementNS(String namespaceURI,
    String qualifiedName);

呼叫參數:

namespaceURI: String, 指定元素節點命名空間URI
qualifiedName: String, 指定元素節點規定名稱

回傳結果:

XmlElement, 返回新建的XmlElement節點，具有指定的標籤名

createTextNode

建立文字節點

1
XmlText XmlDocument.createTextNode(String data);

呼叫參數:

data: String, 指定此節點的文本

回傳結果:

XmlText, 返回新建的XmlText節點，表示指定的data 字串

createComment

建立註解節點

1
XmlComment XmlDocument.createComment(String data);

呼叫參數:

data: String, 指定此節點的註解文本

回傳結果:

XmlComment, 返回新建的XmlComment節點，註釋文字為指定的data

createCDATASection

創建XmlCDATASection節點

1
XmlCDATASection XmlDocument.createCDATASection(String data);

呼叫參數:

data: String, 指定此節點規定CDATA 數據

回傳結果:

XmlCDATASection, 返回新建的XmlCDATASection節點，內容為指定的data

createProcessingInstruction

創建XmlProcessingInstruction節點

1
2
XmlProcessingInstruction XmlDocument.createProcessingInstruction(String target,
    String data);

呼叫參數:

target: String, 指定處理指令的目標
data: String, 指定處理指令的內容文本

回傳結果:

XmlProcessingInstruction, 新建的ProcessingInstruction 節點

hasChildNodes

查詢是否存在子節點

1
Boolean XmlDocument.hasChildNodes();

回傳結果:

Boolean, 存在任何子節點時回傳true，否則回傳false

normalize

合併相鄰的Text 節點並刪除空的Text 節點

1XmlDocument.normalize();

這個方法將遍歷目前節點的所有子孫節點，透過刪除空的Text 節點，已經合併所有相鄰的Text 節點來規範化文件。此方法在進行節點的插入或刪除操作後，對於簡化文件樹的結構很有用。

cloneNode

建立指定的節點的精確拷貝

1
XmlNode XmlDocument.cloneNode(Boolean deep = true);

呼叫參數:

deep: Boolean, 是否深度拷貝，為true 時，被複製的節點會複製原節點的所有子節點

回傳結果:

XmlNode, 返回所複製的節點

該方法將複製並傳回呼叫它的節點的副本。如果傳遞給它的參數是true，它還將遞歸複製目前節點的所有子孫節點。否則，它只複製當前節點。傳回的節點不屬於文件樹，它的parentNode 屬性為null。當複製的是Element 節點時，它的所有屬性都會被複製。

lookupPrefix

傳回在目前節點上符合指定的命名空間URI 的前綴

1
String XmlDocument.lookupPrefix(String namespaceURI);

呼叫參數:

namespaceURI: String, 指定符合的命名空間URI

回傳結果:

String, 傳回符合的前綴，未符合到返回null

lookupNamespaceURI

傳回在目前節點上符合指定的前綴的命名空間URI

1
String XmlDocument.lookupNamespaceURI(String prefix);

呼叫參數:

prefix: String, 指定符合的前綴

回傳結果:

String, 傳回符合的命名空間URI，未符合到傳回null

insertBefore

在已有的子節點前插入一個新的子節點

1
2
XmlNode XmlDocument.insertBefore(XmlNode newChild,
    XmlNode refChild);

呼叫參數:

newChild:XmlNode, 插入新的節點
refChild:XmlNode, 在此節點前插入新節點

回傳結果:

XmlNode, 返回新的子節點

如果文檔樹中已經存在了newChild，它將從文檔樹中刪除，然後重新插入它的新位置。來自一個文檔的節點（或由一個文檔建立的節點）不能插入另一個文檔。也就是說，newChild 的ownerDocument 屬性必須與目前節點的ownerDocument 屬性相同。

insertAfter

在已有的子節點後插入一個新的子節點

1
2
XmlNode XmlDocument.insertAfter(XmlNode newChild,
    XmlNode refChild);

呼叫參數:

newChild:XmlNode, 插入新的節點
refChild:XmlNode, 在此節點後插入新節點

回傳結果:

XmlNode, 返回新的子節點

appendChild

在節點的子節點清單的末尾新增新的子節點

1XmlNode XmlDocument.appendChild(XmlNode newChild);

呼叫參數:

newChild:XmlNode, 指定新增的節點

回傳結果:

XmlNode, 返回這個新的子節點

replaceChild

將某個子節點替換為另一個

1
2
XmlNode XmlDocument.replaceChild(XmlNode newChild,
    XmlNode oldChild);

呼叫參數:

newChild:XmlNode, 指定新的節點
oldChild:XmlNode, 指定被替換的節點

回傳結果:

XmlNode, 如替換成功，此方法可傳回被替換的節點，如替換失敗，則傳回null

removeChild

從子節點清單中刪除某個節點

1XmlNode XmlDocument.removeChild(XmlNode oldChild);

呼叫參數:

oldChild:XmlNode, 指定被刪除的節點

回傳結果:

XmlNode, 如刪除成功，此方法可傳回刪除的節點，如失敗，則傳回null

toString

傳回物件的字串表示，一般回傳"[Native Object]"，物件可以根據自己的特性重新實現

1
String XmlDocument.toString();

回傳結果:

String, 傳回物件的字串表示

toJSON

傳回物件的JSON 格式表示，一般傳回物件定義的可讀屬性集合

1
Value XmlDocument.toJSON(String key = "");

呼叫參數:

key: String, 未使用

回傳結果:

Value, 傳回包含可JSON 序列化的值

開發指南

基礎模組

內建對象

社群模組

對象XmlDocument

繼承關係

建構函數

XmlDocument

成員屬性

inputEncoding

xmlStandalone

xmlVersion

doctype

documentElement

head

title

body

nodeType

nodeName

nodeValue

ownerDocument

parentNode

childNodes

children

firstChild

lastChild

previousSibling

nextSibling

firstElementChild

lastElementChild

previousElementSibling

nextElementSibling

textContent

成員函數

load

getElementsByTagName

getElementsByTagNameNS

getElementById

getElementsByClassName

createElement

createElementNS

createTextNode

createComment

createCDATASection

createProcessingInstruction

hasChildNodes

normalize

cloneNode

lookupPrefix

lookupNamespaceURI

insertBefore

insertAfter

appendChild

replaceChild

removeChild

toString

toJSON