DOMTokenList#
DOMTokenList.add()#
Metoda add() dodaje przekazane słowa do uporządkowanego zestawu słów skojarzonego z danym zestawem słów DOM, z pominięciem tych, które już się w nim znajdują.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
domTokenList.add(tokens...);gdzie poszczególne człony oznaczają:
- domTokenList - zestaw słów DOM będący obiektem kontekstu.
- tokens - łańcuchy znakowe reprezentujące nowe słowa, które będą dodawane do uporządkowanego zestawu słów. Żaden z nich nie może być pusty ani zawierać znaków spacji. Separatorem między łańcuchami jest przecinek. Wielkość znaków ma znaczenie.
Algorytm wywołania metody add(tokens) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
Dla każdego (for each) słowa token w tokens wykonaj poniższe podkroki:
- Jeśli token jest pustym łańcuchem znakowym, to zrzuć wyjątek
"SyntaxError". - Jeśli token zawiera jakiekolwiek białe znaki ASCII, to zrzuć wyjątek
"InvalidCharacterError".
- Jeśli token jest pustym łańcuchem znakowym, to zrzuć wyjątek
- Dla każdego (for each) słowa token w tokens, w podanej kolejności, który nie jest w uporządkowanym zestawie słów skojarzonym z obiektem kontekstu, dołącz token do uporządkowanego zestawu słów skojarzonego z obiektem kontekstu.
- Uruchom kroki aktualizacji.
Wywołanie metody add() będzie automatycznie aktualizowało powiązany z zestawem słów DOM atrybut, przez co jego oryginalna zawartość (łańcuch znakowy) może ulec zmianie, nawet w sytuacji całkowitego pominięcia argumentu. Przekazanie wielu argumentów do metody utworzy jeden zapis zmian w obserwatorze zmian.
Przy dodawaniu pojedynczego słowa do uporządkowanego zestawu słów alternatywnie można skorzystać z podobnie działającej metody DOMTokenList.toggle().
Prosty przykład:
<script>
function showTokens(set){
return Array.prototype.slice.call(set).join(" ");
}
var html = document.documentElement; // referencja do elementu html
document.write(html.classList.constructor); // function DOMTokenList() { [native code] }
document.write("<br>");
document.write(html.classList.length); // 0
document.write("<br><br>");
html.classList.add("Test1", "Test2"); // dodajemy nowe wartości
document.write(showTokens(html.classList)); // Test1 Test2
document.write("<br>");
document.write(html.classList.length); // 2
document.write("<br><br>");
html.classList.add("Test2", "Test3"); // dodajemy nowe wartości
document.write(showTokens(html.classList)); // Test1 Test2 Test3
document.write("<br>");
document.write(html.classList.length); // 3
document.write("<br><br>");
try{ // Dodajemy pusty łańcuch znakowy do uporządkowanego zestawu słów
html.classList.add("");
}
catch(e){
document.write("Przekazanie do metody add() pustego łańcuch znakowego zrzuca błąd:" + "<br>");
document.write(e); // opis zależny od przeglądarki
document.write("<br>");
document.write(e.constructor); // function DOMException() { [native code] }
}
</script>Na chwilę obecną jedynie przeglądarki Firefox i Chrome obsługują metodę add() zgodnie z wymaganiami specyfikacji DOM4. W pozostałych programach nie można przekazywać wielu argumentów do metody, gdyż brany pod uwagę jest tylko pierwszy z nich, a także całkowicie ich pomijać, bo zaowocuje to zrzuceniem błędu.
Metoda add() pojawia się dopiero w specyfikacji DOM4.
Składnia Web IDL#
interface DOMTokenList { void add(DOMString... tokens); }