元素遍歷規範說明

摘要

本規範定義了 ElementTraversal 接口，這允許DOM樹元素腳本導航，但不包括DOM其他節點, 如文本節點。它還提供陳述某一元素的子元素的數目的屬性, 它旨在為現有的DOM導航接口提供更方便、低執行足跡的選擇。

本文檔狀態

本節描述本文檔發布時狀態, 其他文檔可能取代本文檔。最新W3C的出版物清單，以及本技術報告最新修訂本可參見W3C技術報告索引 , 網址 http://www.w3.org/TR/.

元素遍歷規範說明推薦標準制訂於2008年12月22日

本文件已由W3C成員、軟體開發商，以及其他的W3C組織和有關各方審閱，並由W3C理事批准為推薦標準。此為穩定的文檔，可以用作參考文獻或從另一個文件中引用。W3C 制定推薦標準的任務是使之受到關注，並促使其被廣泛使用。這將增強Web的功能性與互操作性。

web應用程式（ WebApps ）工作組編寫了測試套件和執行情況報告表明本規範執行支持的現有水準，所有測試全部通過。自成為推薦標準以來，未有變化。 .

.如對本規範有問題和意見請致函 public-webapps@w3.org, 該公共電子郵件列表處理和 WebApps WG 交付有關問題, 該列表公開存檔, 第一次發文即自動要求接受歸檔條款。如欲訂閱此列表, 請發送電子郵件至 public-webapps-request@w3.org 在主題行中註明“訂閱”。

本文由 web應用程式（ WebApps ）工作組根據W3C 工作程式所定的程式制訂, 該組織屬 W3C 富網客戶端活動。

ElementTraversal 接口最初是應 SVG, CDF, JCP, 和其他組織要求, 作為SVG 名字空間中可縮放向量圖形 (SVG) 微型 1.2 規格的一部分發表的。它被轉移到 WebAPI WG, 並作為一般設施遷移到DOM 和 DOM 名字空間, 而當WebApps WG負責WebAPI WG可交付使用時，再度轉移。

本文檔是由根據 2004年2月5日發布的W3C專利政策.運作的團隊制定的, W3C 維護著一個與工作組交付產品有關的已公開的專利列表 ; 頁面還包括如何公開一項專利的說明。對某專利擁有實際知識並相信該專利包含了基本要求的個人必須根據 W3C專利政策第6節的要求公開這個資訊。

1. 導言

本節為知識篇

一級DOM Node 接口定義了11種節點類型, 但通常作者希望只用 nodeType 1, 即 Element 節點, 其他節點類型包括Document 元素和 Text 節點, 其中包括空格和換行符。DOM 1 節點遍歷包括所有這些節點類型, 而這往往使作者搞亂，這就需要作者用一額外的步驟確認預計 Element 節點接口可用。這便引入額外的性能制約因素。

ElementTraversal 是一個讓作者限制 Element 節點導航接口,它使導航可從一元素導航至其第一子級元素、最後子級元素以及其下一同級元素，或前一同級元素。因為執行過程只顯示元素節點，內存和DOM表述之計算足跡可以就約束裝置進行優化。

一級DOMNode 接口還定義了 childNodes 屬性, 這是一個該節點所有子節點實況列表; childNodes 列表中有一 length 屬性，顯示所有 nodeTypes子節點總數, 利於預處理操作和預先計算或用來代替子節點循環。 ElementTraversal 接口有一類似屬性 -- childElementCount, childElementCount報告Element 節點數目, 通常此類操作就求這個。

1.1. 本規範不包括的內容

本規範不包括屬性，方法和 Element 對象其他可用接口完整列表, 其他規範，特別是DOM核心規範包括了另外的接口。

1.2. 一致性

本節為規範篇

本文檔關鍵詞 "必須 " (原文：MUST), "不能 "(原文：MUST NOT), "需要 " (原文：REQUIRED), "應" (原文：SHALL) "不得"(原文：SHALL NOT), "應該"(原文：SHOULD), "不應該 ",(原文：SHOULD NOT) "建議 "(原文：RECOMMEND), "可以 "(原文：MAY), and "可選" (原文：OPTIONAL) 按 RFC 2119 [RFC2119]所述來理解。為了便於閱讀，這些詞條在本文中不一定區分大小寫。

有時，為了便於閱讀，一致性要求可表述為對元素、屬性、方法、接口、性能或功能方面的要求。在所有情況下，這些是要執行的一致性要求。本規範一致性之實現符合所有在其語言綁定範圍內使用這些條款的要求。

2. `ElementTraversal` 接口

本節為規範篇

ElementTraversal 接口是一套祇讀屬性，它使作者能夠方便地瀏覽文檔內容。在符合元素遍歷一致性執行時，所有執行 Element對象也必須執行 ElementTraversal 接口。 firstElementChild, lastElementChild, previousElementSibling, 和 nextElementSibling 這四個屬性, 每個均提供對定義了與當前元素關係的另一元素的活引用，如果有關的元素存在的話。第五屬性, childElementCount,顯示一元素的子級元素數目作導航前預處理。合適的用戶代理必須執行全部五個屬性。用戶代理可以在其他規範執行類似的接口，但如果用戶代理是專為最低代碼足跡而設計的話，則這種執行就不需要符合本規範。

不論Element 名字空間為何，接口必須在全部Element 執行。對元素遍歷機制而言, 實體引用節點是不可見的; 如果轉換器遇到實體引用節點，它則下行至它處而不通知原調用者，接著處理子級元素就象是它們本來就在實體節點那裡一樣。導航必須與名字空間無關，例如，如果在HTML名字空間元素後面跟著SVG名字空間，那麼該 nextElementSiblingHTML元素屬性將返回SVG元素。

2.1. `firstElementChild`

訪問一元素的這個屬性必須將該nodeType 1 元素第一子節點引用返回為 Element 對象。如果該被訪問元素屬性沒有任何子節點，或者如果所有這些子節點都不是元素節點，那麼該屬性必須返回 null。

2.2. `lastElementChild`

訪問一元素的這個屬性必須將該nodeType 1 元素最後子節點引用返回為 Element 對象。如果該被訪問元素屬性沒有任何子節點，或者如果所有這些子節點都不是元素節點，那麼該屬性必須返回 null。

2.3. `previousElementSibling`

訪問一元素的這個屬性必須將按文件順序排在該元素之前屬於nodeType 1 元素同級節點引用返回為 Element 對象。如果該被訪問元素屬性沒有任何處於它之前的同級節點，或者如果所有這些同級節點都不是元素節點，那麼該屬性必須返回 null。

2.4. `nextElementSibling`

訪問一元素的這個屬性必須將按文件順序緊跟著這個屬於nodeType 1 元素同級節點引用返回為 Element 對象。如果該被訪問元素屬性沒有任何跟在它之後的同級節點，或者如果所有這些同級節點都不是元素節點，那麼該屬性必須返回 null。

2.5. `childElementCount`

訪問一元素的這個屬性必須返回這個屬於nodeType 1.元素子節點當前數目, 訪問此屬性時，執行可能存貯該數目，或可能計算該數目，但該數目必須始終代表訪問該屬性時子元素節點的數目。只有直接子節點才應該計算在內，如被訪問屬性元素子節點之一又有元素子節點那麼這下一級的就不算。如果屬性被訪問的這個元素沒有子節點，或者所有這些子節點都不是元素節點，那麼這個屬性必須返回0 。

3. 使用實例

本節為知識篇

本節用元素遍歷說明一些ECMAScript [ECMA262] 例子。

3.1. `previousElementSibling`例子

這個例子表明 previousElementSibling 屬性的實用性。以下程式取一元素作為參數，並返回該元素按文件順序在同一父級下的位置:


function findPosition( el ) {
   var pos = 0;

   // 逆序循環各子元素
   while ( null != el ) {
      // 導航到上一同級元素
      el = el.previousElementSibling;
      pos++;
   }
   
   return pos;
}

3.2. 預計值與元素循環例子

這個例子表明childElementCount 屬性的實用性。以下程式取一元素作為參數，並根據可用空間把每個子級元素等距放好

function spaceChildren( el ) {
   // 求元素節點數目 
   var elCount = el.childElementCount;
   
   var eachWidth = window.innerWidth / (elCount + 1);

   // 求第一子元素  
   var childEl = el.firstElementChild;

   // 設置初始位置 
   var nextPos = eachWidth/2;
   
   // 逐一循環子元素 
   while ( childEl ) {
      // 放好子元素
      childEl.style.setProperty( 'position', 'absolute', '' );
      childEl.style.setProperty( 'left', nextPos + 'px', '' );
      childEl.style.setProperty( 'width', eachWidth + 'px', '' );
      
      // 按寬度增距
      nextPos += eachWidth;
      
      // 然後導航到下一個子元素
      childEl = childEl.nextElementSibling;
   }
}

3.3.與其他的DOM接口比較例子

這個例子將 ElementTraversal 與其他的DOM接口對比, 下面的腳本顯示就以下SVG的片段，以不同的方法遍歷一個DOM樹:

<g id='shapeGroup'>

   <rect id='rect1' x='5' y='5' width='310' height='220' rx='15' ry='15' fill='skyblue'/>
   <rect id='rect2' x='15' y='15' width='210' height='180' rx='15' ry='15' fill='cornflowerblue'/>

   <ellipse id='ellipse1' cx='90' cy='70' rx='50' ry='30' fill='yellow' stroke='orange'/>

   <path id='path1' stroke-width='15' stroke='orange' fill='none' stroke-linecap='round' 
      d='M25,150 C180,180 290,0 400,140 S420,100 460,90'/>  
   <text id='text1' x='0' y='0' font-size='35' fill='yellow' stroke='orange'
      stroke-width='2' stroke-linejoin='round' font-weight='bold'>

      <textPath id='textPath1' xlink:href="#path1">when life gives you lemons...</textPath></text>

</g>

function walkTest( el ) {
   // 求所有節點總數 
   var nodeCount = el.childNodes.length;

   // 求第一個子節點 
   var firstNode = el.firstChild;

   // 求第一個子元素
   var childEl = el.firstElementChild;

   // 逐一循環各子元素
   while ( childEl ) {
      // 這裡做一些有用的事......

      // 然後導航到下一個子元素
      childEl = childEl.nextElementSibling;
   }
}

el 相當於 'id' 為 "shapeGroup"的'g' 元素, nodeCount 的值為 11. firstNode 為text 節點 (nodeType 3), 它不等於childEl的賦值, 那是 element 節點 (nodeType 1) 其 'id' 為"rect1" 。 while 循環將再循環4次, 遍歷同級element 節點, 分別是 "rect2", "ellipse1", "path1", 和 "text1", childEl最後值將為 null, 因為 "text1" 沒有下一個元素同級, 雖然它有下一個節點同級。

注意 SVG 'text'元素與 Text 節點不同。迭代不包括 'text' 元素的 SVG 'textPath' 子元素, 因為它與 childEl不同級。

4. 與其他的DOM 規範的關係

本節為知識篇

4.1. 一級DOM核心

本規範提供了一個接口, 它與DOM 1核心的DOM導航屬性與功能相似, 但只對元素節點操作, 對其他節點類型不操作。最具可比性的DOM 1核心屬性為firstChild, lastChild, previousSibling, nextSibling, 和 nodeList.length.

4.2. 二級DOM遍歷及範圍

二級文檔對象模型Traversal & Range是非常全面的文檔導航規範, 但可能比元素遍歷需要更多設備和設備資源。由於元素遍歷是一個二級DOM Traversal 功能的優化子集，一個實現兩種遍歷的用戶代理可以這麼做以利用遍歷的功能。

4.3.三級 DOM 核心

這是 DOM 3 Core補充規範。

5. 安全需要考慮事項

本節為知識篇

涉及實施或使用 ElementTraversal 接口方面, 未有安全需要考慮事項。今後如發現安全需要考慮事項, 本節將進行修訂。

A. IDL定義

IDL 定義

interface ElementTraversal
{
   readonly attribute Element        firstElementChild;
   readonly attribute Element        lastElementChild;
   readonly attribute Element        previousElementSibling;
   readonly attribute Element        nextElementSibling;
   readonly attribute unsigned long  childElementCount;
};

無定義常量

屬性

firstElementChild: 返回該元素第一個子元素節點，如該元素無子元素, 返回null。

lastElementChild: 返回該元素最後子元素節點，如該元素無子元素, 返回null。

previousElementSibling: 返回該元素上個同級元素節點，如該元素在文檔樹中無元素同級節點在它之前, 返回null。

nextElementSibling: 返回該元素下個同級元素節點，如該元素在文檔樹中無元素同級節點在它之後, 返回null。

childElementCount: 返回該元素所有子元素節點當前數目, 如該元素無屬於 nodeType 1子節點, 返回0。

無定義方法

B. ECMAScript 語言綁定

Object Element

就實現ElementTraversal 接口的用戶代理而言， Element 擁有在其他的DOM規範中所定義 Node 與 Element所有的屬性與方法, 此外，還擁有以下屬性:

firstElementChild: .這個祇讀屬性屬 Element類型.
lastElementChild: 這個祇讀屬性屬 Element類型.
previousElementSibling: 這個祇讀屬性屬 Element類型.
nextElementSibling: 這個祇讀屬性屬 Element類型.
childElementCount: 這個祇讀屬性屬Number類型.

C. Java 語言綁定

org/w3c/dom/ElementTraversal.java:

package org.w3c.dom;

public interface ElementTraversal 
{
    Element getFirstElementChild();

    Element getLastElementChild();

    Element getPreviousElementSibling();

    Element getNextElementSibling();

    int getChildElementCount();
}

D. 更改記載

各草案均對實例進行了不同的編輯性修改、更正和更改。

childElementCount 屬性是對原提案的補充, 原因已在本規範中陳明。

E. 參考文獻

規範性文獻

[RFC2119]: Key words for use in RFCs to indicate Requirement Levels, S. Bradner, March 1997. The specification for how to use English as if it were a technical language to indicate normative requirements.
[DOM1Core]: Document Object Model - Level 1 Core, V. Apparao, S. Byrne, M. Champion, S. Isaacs, I. Jacobs, A. Le Hors, G. Nicol, J. Robie, R. Sutor, C. Wilson, L. Wood, Editors. World Wide Web Consortium, 1 October 1998. A standard set of objects for representing HTML and XML documents, a standard model of how these objects can be combined, and a standard interface for accessing and manipulating them.
[ECMA262]: Standard ECMA-262, 3^rd edition. ECMA International, December 1999. The specification for the ECMAScript language, of which JavaScript is a dialect.

參考性文獻

[SVGD]: The SVG Micro DOM (uDOM), O. Andersson, R. Berjon, E. Dahlstr?m, A. Emmons, J. Ferraiolo, V. Hardy, S. Hayman, D. Jackson, C. Lilley, A. Neumann, C. Northway, A. Quint, N. Ramani, D. Schepers, A. Shellshear, Editors. World Wide Web Consortium, 10 August 2006. The proposed ElementTraversal interface in SVG.
[DOM2TR]: Document Object Model (DOM) Level 2 Traversal and Range Specification, J. Kesselman, J. Robie, M. Champion, P. Sharpe, V. Apparao, L. Wood, Editors. World Wide Web Consortium, 13 November 2000. A set of platform- and language-neutral interfacess that allow programs and scripts to dynamically traverse and identify a range of content in a document.
[DOM3Core]: Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le H garet, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, Editors. World Wide Web Consortium, 07 April 2004. A platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents.

F. 鳴謝

以下人員為本規範做出了貢獻，編輯在此特別鳴謝：

David Andersson, Robin Berjon, Jean-Yves Bitterlich, Sergiu Dumitriu, Daniel Glazman, Bjoern Hoehrmann, Kurosawa Takeshi, Chris Lilley, Charles McCathieNevile, Cameron McCormack, Simon Pieters, Nandini Ramani, Jonas Sicking, Andrew Sledd, Josh Soref, Anne van Kesteren, Boris Zbarsky, Mohamed Zergaoui

此外，編輯還要向SVG工作組致謝，是他們制訂了SVG草案 [SVGD] 而本規範原本基於該草案。

譯文:元素遍歷規範說明 W3C推薦標準2008年12月22日

英文:Element Traversal Specification W3C Recommendation 22 December 2008

聲明:

翻譯:

元素遍歷規範說明

W3C推薦標準2008年12月22日

摘要

本文檔狀態

目錄

1. 導言

1.1. 本規範不包括的內容

1.2. 一致性

2. `ElementTraversal` 接口

2.1. `firstElementChild`

2.2. `lastElementChild`

2.3. `previousElementSibling`

2.4. `nextElementSibling`

2.5. `childElementCount`

3. 使用實例

3.1. `previousElementSibling`例子

3.2. 預計值與元素循環例子

3.3.與其他的DOM接口比較例子

4. 與其他的DOM 規範的關係

4.1. 一級DOM核心

4.2. 二級DOM遍歷及範圍

4.3.三級 DOM 核心

5. 安全需要考慮事項

A. IDL定義

B. ECMAScript 語言綁定

C. Java 語言綁定

D. 更改記載

E. 參考文獻

規範性文獻

參考性文獻

F. 鳴謝

譯文:元素遍歷規範說明 W3C推薦標準2008年12月22日

英文:Element Traversal Specification W3C Recommendation 22 December 2008

聲明:

翻譯:

元素遍歷規範說明

W3C推薦標準2008年12月22日

摘要

本文檔狀態

目錄

1. 導言

1.1. 本規範不包括的內容

1.2. 一致性

2. ElementTraversal 接口

2.1. firstElementChild

2.2. lastElementChild

2.3. previousElementSibling

2.4. nextElementSibling

2.5. childElementCount

3. 使用實例

3.1. previousElementSibling例子

3.2. 預計值與元素循環例子

3.3.與其他的DOM接口比較例子

4. 與其他的DOM 規範的關係

4.1. 一級DOM核心

4.2. 二級DOM遍歷及範圍

4.3.三級 DOM 核心

5. 安全需要考慮事項

A. IDL定義

B. ECMAScript 語言綁定

C. Java 語言綁定

D. 更改記載

E. 參考文獻

規範性文獻

參考性文獻

F. 鳴謝

2. `ElementTraversal` 接口

2.1. `firstElementChild`

2.2. `lastElementChild`

2.3. `previousElementSibling`

2.4. `nextElementSibling`

2.5. `childElementCount`

3.1. `previousElementSibling`例子