Специфікація Обходу Елемента

Анотація

Ця специфікація визначає інтерфейс ElementTraversal, який дозволяє здійснювати навігацію сценарію елементів дерева DOM, виключаючи всі інші вузли в DOM, такі як текстові вузли. Він також надає атрибут, щоб виявити число дочірніх елементів цього елемента. Він призначений для того, щоб забезпечити більш зручну альтернативу існуючим інтерфейсам навігації DOM, з невеликим обсягом реалізації.

Статус цього документа

Цей розділ описує статус даного документа на час його публікації. Інші документи можуть заміняти цей документ. Зі списком поточних публікацій W3C та останньою ревізією цього технічного докладу можна ознайомитися в індексі технічних докладів W3C на http://www.w3.org/TR/.

Специфікація обходу елемента є Рекомендацією від 22 грудня 2008 року.

Цей документ був розглянутий членами W3C, розробниками програмного забезпечення, а також іншими групами W3C і зацікавленими сторонами, і схвалений Директором в якості Рекомендації W3C. Це стабільний документ і може бути використаний в якості довідкового матеріалу або цитат в іншому документі. Роль W3C у розробці Рекомендації, полягає в залученні уваги до специфікації, і сприяти її широкому поширенню. Це підвищує функціональність і сумісність у Веб(Web).

Робоча група Веб-додатків (WebApps) підготовила набір тестів та звіт про реалізацію, щоб вказати на поточний рівень підтримуваної реалізації даної специфікації, з передачею результатів для всіх тестів. Не було ніяких змін, починаючи з Запропонованою Рекомендації.

Будь ласка, надсилайте Ваші питання та коментарі щодо цієї специфікації за адресою [email protected], публічний список електронних листів для питань, що стосуються результатів WebApps WG. Цей список знаходиться у публічному архіві, і прийняття цієї політики запису до архіву запитується автоматично після першого повідомлення. Щоб підписатися на цей список надішліть листа за адресою [email protected] зі словом "subscribe" у темі листа.

Цей документ був підготовлений Робочою групою Веб-додатків (WebApps), в рамках W3C Rich Web Clients Activity, у відповідності з викладеними процедурами для W3C Process.

Інтерфейс ElementTraversal був спочатку опублікований як частина специфікації SVG Tiny 1.2 у просторі імен SVG. На вимогу SVG, CDF, JCP, та інших груп, він був переданий у WebAPI WG, і перенесений у DOM і простір імен DOM, у якості загального об'єкта. Він був переданий ще раз, коли WebApps WG взяв на себе відповідальність за компоненти що поставляються WebAPI WG.

Цей документ був підготовлений групою, діючи в рамках Патентної Політики W3C від 5 лютого 2004 року. W3C підтримує публічний список відкритих патентів зроблений у зв'язку з результатами діяльності групи; ця сторінка також включає в себе інструкції з розкриття патенту. Особи, які мають актуальною інформацією про патент, який задовольняє Основним вимогам, повинні розкрити цю інформацію згідно з пунктом 6 патентної політики W3C.

Зміст

• 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 Level 1 Core
  • 4.2. DOM Level 2 Traversal & Range
  • 4.3. DOM Level 3 Core
• 5. Обговорення безпеки

• A. Визначення IDL
• B. Прив'язка до мови ECMAScript
• C. Прив'язка до мови Java
• D. Історія змін
• E. Посилання
• F. Подяки

1. Вступ

Цей розділ є інформативним.

Інтерфейс Node у DOM Рівень 1, визначає 11 типів вузла, але зазвичай автори хочуть працювати виключно на nodeType 1, вузол Element. Інші типи вузла включають у себе елемент Document та вузол Text, що містить у собі пробіли та розриви рядка. Вузол обходу DOM 1 включає у себе всі ці типи вузлів, які часто є джерелом безладу для авторів і які вимагають додатковий крок для авторів, щоб підтвердити, що очікувані інтерфейси вузла Element доступні. Це вносить додаткові обмеження в продуктивності.

ElementTraversal - це інтерфейс, який дозволяє авторам обмежувати навігацію по вузлах Element. Це дозволяє здійснювати переміщення від елемента до його першого дочірнього елемента, його останнього дочірнього елемента і до його наступного чи попереднього елемента який знаходиться на одному рівні з ним. Оскільки реалізація представляє собою тільки вузли елементу, пам'ять і обчислювальне місце подання DOM можуть бути оптимізовані для обмежених пристроїв.

Інтерфейс Node у DOM Рівень 1, також визначає атрибут childNodes, який є живим списком всіх дочірніх вузлів одного вузла; список childNodes має атрибут length який служить для того, щоб виявити загальну кількість дочірніх вузлів у всіх nodeTypes, це корисно для попередньої обробки операцій та обчислень перед, або замість, циклічного виконання через дочірні вузли. У інтерфейсу ElementTraversal є подібний атрибут, childElementCount, який повідомляє тільки число вузлів Element, який часто є тим, що потрібно для таких операцій.

2. Інтерфейс ElementTraversal

Цей розділ є нормативним.

Інтерфейс ElementTraversal являє собою набір атрибутів тільки для читання, які дозволяють автору легко переміщатися між елементами в документі. У відповідних реалізаціях обходу елементів, всі об'єкти які реалізують Element повинні також реалізовувати інтерфейс ElementTraversal. Кожен з наступних чотирьох атрибутів з набору, firstElementChild, lastElementChild, previousElementSibling, та nextElementSibling, забезпечує живе посилання на інший елемент з певним ставленням до поточного елемента, якщо зв'язаний елемент існує. П'ятий атрибут, childElementCount, надає число дочірніх елементів елемента, для того, щоб попередньо обробити перед навігацією. Відповідна клієнтська програма повинна реалізувати всі п'ять атрибутів. Клієнтська програма може реалізувати подібні інтерфейси в інших специфікаціях, але така реалізація не потрібна для відповідності до цієї специфікації, якщо клієнтська програма розроблена для мінімального обсягу коду.

Цей інтерфейс повинен бути реалізований на всіх Element, незалежно від їх простору імен. Вузли EntityReference невидимі механізму обходу елементів; якщо обхідник дерева (tree-walker) випадково зустрічає вузол EntityReference, він спускається до нього, не повідомляючи про це програмі яка його викликає, і обробляє будь-які дочірні елементи так, як якщо б вони були присутні в тому місці де вузол об'єкту був знайдений. Навігація зобов'язана бути незалежна від простору імен, наприклад, якщо елемент у просторі імен HTML буде супроводжуватися елементом у просторі імен SVG, тоді атрибут nextElementSibling елемента HTML поверне елемент 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. Наступний сценарій показує різні методи ітерації через дерево DOM, враховуючи наступний фрагмент SVG:

<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 є елементом 'g' який має 'id' "shapeGroup", nodeCount буде мати значення 11. firstNode буде вузлом Text (nodeType 3), і не еквівалентний першому присвоєному значенню childEl, який є вузлом Element (nodeType 1) має 'id' "rect1". Цикл while циклічно повториться ще 4 рази, виконуючи ітерації через однорівневі вузли Element, відповідно "rect2", "ellipse1", "path1", та "text1". Та останнє значення childEl буде null, оскільки "text1" не має наступного однорівневого елемента, хоча у нього є наступний однорівневий вузол.

Відзначте, що елемент 'text' у SVG не те ж саме, що вузол Text. Відзначте також, що дочірній елемент 'textPath' у SVG елементу 'text' не включений до ітерації, оскільки він не однорівневий з childEl.

4. Відношення до інших специфікацій DOM

Цей розділ є інформативним.

5. Обговорення безпеки

Цей розділ є інформативним.

Немає ніяких відомих питань безпеки, які включені у реалізацію або використання інтерфейсу ElementTraversal. Цей розділ повинен бути переглянутий, якщо в майбутньому, питання безпеки будуть виявлені.

A. Визначення IDL

B. Прив'язка до мови ECMAScript

C. Прив'язка до мови Java

package org.w3c.dom;

public interface ElementTraversal 
{
    Element getFirstElementChild();

    Element getLastElementChild();

    Element getPreviousElementSibling();

    Element getNextElementSibling();

    int getChildElementCount();
}

D. Історія змін

Різні редакційні зміни, виправлення та модифікації до прикладів були зроблені від проекту до проекту.

Атрибут childElementCount був додатковим до первісної пропозиції, з причин, вказаних в цій специфікації.

E. Посилання

Нормативні посилання

[RFC2119]

Ключові слова для використання в документах RFC для Вказівки Рівнів Вимог, С. Браднер (S. Bradner), березень 1997 року. Специфікація для того, щоб вказати як використовувати англійську мову так, як ніби це була технічна мова із зазначенням нормативних вимог.

[DOM1Core]

Об'єктна модель документа (Document Object Model) - Рівень 1, Основний, В. Еппарао (V. Apparao), С. Берн (S. Byrne), М. Чемпіон (M. Champion), С. Ісаакс (S. Isaacs), І. Джейкобс (I. Jacobs), А. Ле Хорс (A. Le Hors), Г. Ніколь (G. Nicol), Дж. Робі (J. Robie), Р. Сьютор (R. Sutor), С. Уілсон (C. Wilson), Л. Вуд (L. Wood), Редактори. World Wide Web Consortium, 1 жовтня 1998 року. Стандартний набір об'єктів для того, щоб представити документи HTML та XML, стандартну модель того, як ці об'єкти можуть бути об'єднані, і стандартний інтерфейс для доступу та управління ними.

[ECMA262]

Стандарт ECMA-262, 3-^е видання. ECMA International, грудень 1999 року. Специфікація для мови ECMAScript, діалектом якого є JavaScript.

Інформативні посилання

[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, Редактори. World Wide Web Consortium, 10 серпня 2006 року. Пропонується інтерфейс ElementTraversal у SVG.

[DOM2TR]

Об'єктна модель документа (DOM) Рівень 2, Специфікації обходу та діапазону, Дж. Кессельман (J. Kesselman), Дж. Робі (J. Robie), М. Чемпіон (M. Champion), П. Шерпе (P. Sharpe),В. Аппарео (V. Apparao), Л. Вуд (L. Wood), Редактори. World Wide Web Consortium, 13 листопада 2000 року. Множина платформно- та мовно- нейтральних інтерфейсів які дозволяють програмам і скриптам динамічно обходити та ідентифікувати діапазон вмісту у документі.

[DOM3Core]

Об'єктна модель документа (DOM) Рівень 3, Основна Специфікація, А. Ле Хорс (A. Le Hors), P. Le Hégaret, Л. Вуд (L. Wood), Г. Ніколь (G. Nicol), Дж. Робі (J. Robie), М. Чемпіон (M. Champion), С. Берн (S. Byrne), Редактори. World Wide Web Consortium, 07 квітня 2004 року. Множина платформно- та мовно- нейтральних інтерфейсів які дозволяють програмам і скриптам динамічно отримувати доступ і оновлювати вміст, структуру і стиль документів.

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 WG за те, що він зробив проект [SVGD] на якому спочатку була заснована дана специфікація.