Document#
Document.createTreeWalker()#
Metoda createTreeWalker() tworzy nowy obiekt typu TreeWalker (tzw. przemierzacz drzewa) 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_walker = document.createCreateTreeWalker(root [, whatToShow =4294967295[, filter =null]]);
gdzie poszczególne człony oznaczają:
- new_walker - referencja do nowego przemierzacza drzewa.
- document - dokument będący obiektem kontekstu.
- root - węzeł reprezentujący korzeń w nowym przemierzaczu drzewa. 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 przemierzaczu drzewa, 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 przemierzaczu drzewa, 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 createTreeWalker(root, whatToShow, filter) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Niech walker będzie nowym obiektem typu
TreeWalker. - Ustaw korzeń oraz zainicjuj atrybut
currentNodew walker na wartość argumentu root. - Ustaw maskę bitów w walker na wartość argumentu whatToShow.
- Ustaw filtr w walker na wartość argumentu filter.
- Zwróć walker.
Korzeń, maska bitowa oraz filtr w przemierzaczach drzewa są ustawiane jednorazowo za pośrednictwem metody createCreateTreeWalker() i nigdy nie ulegają zmianie. W razie potrzeby zawsze istnieje możliwość utworzenia nowego przemierzacza drzewa o określonych cechach.
Obiekt zwracany przez metodę createTreeWalker() implementuje interfejs TreeWalker, 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 przemierzaczami drzewa umieściłem w zbiorczym dziale "Podstawy - Przejścia".
Prosty przykład:
<script>
// Tworzymy nowego przemierzacza drzewa (maska bitowa oraz filtr są domyślne)
var walker1 = document.createTreeWalker(document);
document.write(walker1); // [object TreeWalker]
document.write("<br>");
document.write(walker1.root); // [object HTMLDocument]
document.write("<br>");
document.write(walker1.whatToShow); // 4294967295
document.write("<br>");
document.write(walker1.filter); // null
document.write("<br><br>");
// Tworzymy nowego przemierzacza drzewa z własną maską bitową i filtrem
var walker2 = document.createTreeWalker(document.documentElement, 1, function(node){
if (node.nodeName.toLowerCase() == "p"){
return 1;
}
});
document.write(walker2); // [object TreeWalker]
document.write("<br>");
document.write(walker2.root); // [object HTMLHtmlElement]
document.write("<br>");
document.write(walker2.whatToShow); // 1
document.write("<br>");
document.write(walker2.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ę createTreeWalker() zgodnie z najnowszymi wymaganiami specyfikacji DOM4. Chrome błędnie zwraca funkcję filtrującą poprzez właściwość TreeWalker.filter. Opera (Presto) i IE11 spełniają wymagania poprzedniej specyfikacji, gdzie wywołanie metody createTreeWalker() wymagało przekazania czterech argumentów (żaden nie był opcjonalny).
W poprzedniej specyfikacji metoda createTreeWalker() 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] TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null); };