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

Аннотация

Эта спецификация определяет интерфейс 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] на котором первоначально была основана данная спецификация.