Document#
Document.createNodeIterator()#
Metoda createNodeIterator() tworzy nowy obiekt typu NodeIterator (tzw. iterator węzłowy) z określonym korzeniem, maską bitową i filtrem dla danego dokumentu.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_iterator = document.createCreateNodeIterator(root [, whatToShow =4294967295[, filter =null]]);
gdzie poszczególne człony oznaczają:
- new_iterator - referencja do nowego iteratora węzłowego.
- document - dokument będący obiektem kontekstu.
- root - węzeł reprezentujący korzeń w nowym iteratorze węzłowym. Może nim zostać dowolny rodzaj węzła i w żaden sposób nie zależy on od przekazywanej maski bitowej czy filtra.
- whatToShow - liczba całkowita reprezentująca maskę bitową w nowym iteratorze węzłowym, od której uzależniona jest wstępna filtracja przy testowaniu jego węzłów. Parametr jest opcjonalny z domyślną wartością ustawianą na
4294967295(0xFFFFFFFF), co jest równoważne stałejNodeFilter.SHOW_ALLi oznacza branie pod uwagę wszystkich rodzajów węzłów. - filter - obiekt reprezentujący filtr w nowym iteratorze węzłowym, od którego uzależniona jest dodatkowa filtracja przy testowaniu jego węzłów lub wartość
null. Parametr jest opcjonalny z domyślną wartością ustawianą nanull, co jest równoważne z brakiem dodatkowej filtracji.
Algorytm wywołania metody createNodeIterator(root, whatToShow, filter) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Niech iterator będzie nowym obiektem typu
NodeIterator. - Ustaw korzeń oraz zainicjuj atrybut
referenceNodew iterator na wartość argumentu root. - Zainicjuj atrybut
pointerBeforeReferenceNodew iterator na boolowską wartośćtrue. - Ustaw maskę bitów w iterator na wartość argumentu whatToShow.
- Ustaw filtr w iterator na wartość argumentu filter.
- Zwróć iterator.
Korzeń, maska bitowa oraz filtr w iteratorach węzłowych są ustawiane jednorazowo za pośrednictwem metody createNodeIterator() i nigdy nie ulegają zmianie. W razie potrzeby zawsze istnieje możliwość utworzenia nowego iteratora węzłowego o określonych cechach.
Obiekt zwracany przez metodę createNodeIterator() implementuje interfejs NodeIterator, dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia).
Więcej szczegółów związanych z iteratorami węzłowymi umieściłem w zbiorczym dziale "Podstawy - Przejścia".
Prosty przykład:
<script>
// Tworzymy nowego iteratora węzłowego (maska bitowa oraz filtr są domyślne)
var iterator1 = document.createNodeIterator(document);
document.write(iterator1); // [object NodeIterator]
document.write("<br>");
document.write(iterator1.root); // [object HTMLDocument]
document.write("<br>");
document.write(iterator1.whatToShow); // 4294967295
document.write("<br>");
document.write(iterator1.filter); // null
document.write("<br><br>");
// Tworzymy nowego iteratora węzłowego z własną maską bitową i filtrem
var iterator2 = document.createNodeIterator(document.documentElement, 1, function(node){
if (node.nodeName.toLowerCase() == "p"){
return 1;
}
});
document.write(iterator2); // [object NodeIterator]
document.write("<br>");
document.write(iterator2.root); // [object HTMLHtmlElement]
document.write("<br>");
document.write(iterator2.whatToShow); // 1
document.write("<br>");
document.write(iterator2.filter); // function (node){ if (node.nodeName.toLowerCase() == "p"){ return 1; } },
// [object NodeFilter] w Chrome (błędnie)
</script>Na chwilę obecną jedynie przeglądarka Firefox obsługuje metodę createNodeIterator() zgodnie z najnowszymi wymaganiami specyfikacji DOM4. Chrome błędnie zwraca funkcję filtrującą poprzez właściwość NodeIterator.filter. Opera (Presto) i IE11 spełniają wymagania poprzedniej specyfikacji, gdzie wywołanie metody createNodeIterator() wymagało przekazania czterech argumentów (żaden nie był opcjonalny).
W poprzedniej specyfikacji metoda createNodeIterator() definiowana była w specjalnym interfejsie DocumentTraversal, ale z dopiskiem, że może być implementowana bezpośrednio w interfejsie Document.
Składnia Web IDL#
interface Document : Node { [NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null); };