Object 內建對象

對象XmlDocument

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

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

  1. 建立元素節點、文字節點、註解和處理指令等
  2. 存取和修改文件屬性和相關資訊(如DTD 註釋及文件聲明)
  3. 解析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。最後我們使用xmlDocdocumentElement屬性來取得文檔根節點,並取得其節點名稱,輸出到控制台上。

由於XmlDocument 是整個XML 文件的入口,因此我們可以透過它來取得和修改文件的相關資訊。例如,我們可以透過xmlDoc.xmlVersionxmlDoc.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)

1
readonly XmlDocumentType XmlDocument.doctype;

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


documentElement

XmlElement, 傳回文檔的根節點

1
readonly XmlElement XmlDocument.documentElement;

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

1
readonly XmlElement XmlDocument.head;

title

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

1
readonly String XmlDocument.title;

body

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

1
readonly XmlElement XmlDocument.body;

nodeType

Integer, 傳回節點的節點類型

1
readonly Integer XmlDocument.nodeType;

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


nodeName

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

1
readonly String XmlDocument.nodeName;

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


nodeValue

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

1
String XmlDocument.nodeValue;

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


ownerDocument

XmlDocument, 傳回節點的根元素(XmlDocument 物件)

1
readonly XmlDocument XmlDocument.ownerDocument;

parentNode

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

1
readonly XmlNode XmlDocument.parentNode;

childNodes

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

1
readonly XmlNodeList XmlDocument.childNodes;

children

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

1
readonly XmlNodeList XmlDocument.children;

firstChild

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

1
readonly XmlNode XmlDocument.firstChild;

lastChild

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

1
readonly XmlNode XmlDocument.lastChild;

previousSibling

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

1
readonly XmlNode XmlDocument.previousSibling;

nextSibling

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

1
readonly XmlNode XmlDocument.nextSibling;

firstElementChild

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

1
readonly XmlNode XmlDocument.firstElementChild;

lastElementChild

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

1
readonly XmlNode XmlDocument.lastElementChild;

previousElementSibling

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

1
readonly XmlNode XmlDocument.previousElementSibling;

nextElementSibling

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

1
readonly XmlNode XmlDocument.nextElementSibling;

textContent

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

1
String XmlDocument.textContent;

成員函數

load

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

1
XmlDocument.load(String source);

呼叫參數:

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

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

1
XmlDocument.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 屬性的文檔元素。 。


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, 指定元素節點規定名稱

回傳結果:


createElementNS

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

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

呼叫參數:

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

回傳結果:


createTextNode

建立文字節點

1
XmlText XmlDocument.createTextNode(String data);

呼叫參數:

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

回傳結果:


createComment

建立註解節點

1
XmlComment XmlDocument.createComment(String data);

呼叫參數:

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

回傳結果:


createCDATASection

創建XmlCDATASection節點

1
XmlCDATASection XmlDocument.createCDATASection(String data);

呼叫參數:

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

回傳結果:


createProcessingInstruction

創建XmlProcessingInstruction節點

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

呼叫參數:

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

回傳結果:


hasChildNodes

查詢是否存在子節點

1
Boolean XmlDocument.hasChildNodes();

回傳結果:

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

normalize

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

1
XmlDocument.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, 在此節點前插入新節點

回傳結果:

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


insertAfter

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

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

呼叫參數:

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

回傳結果:

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


appendChild

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

1
XmlNode XmlDocument.appendChild(XmlNode newChild);

呼叫參數:

  • newChild:XmlNode, 指定新增的節點

回傳結果:

  • XmlNode, 返回這個新的子節點

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


replaceChild

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

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

呼叫參數:

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

回傳結果:

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

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


removeChild

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

1
XmlNode 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 序列化的值