DOMTokenList#

DOMTokenList.toggle()#

Metoda toggle() przełącza przekazane słowo w uporządkowanym zestawie słów skojarzonym z danym zestawem słów DOM. Pojęcie "przełączania" oznacza usunięcie słowa z uporządkowanego zestawu słów (jeśli występuje), lub dodanie słowa do uporządkowanego zestawu słów (jeśli nie występuje). Metoda zwraca także boolowską wartość true jeśli po wykonaniu wszystkich czynności przekazane słowo znajduje się w uporządkowanym zestawie słów, w przeciwnym razie zwrócona zostanie wartość false.

Opis działania#

Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
var toggled = domTokenList.toggle(token [, force]);

gdzie poszczególne człony oznaczają:

Algorytm wywołania metody toggle(token, force) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

  1. Jeśli token jest pustym łańcuchem znakowym, to zrzuć wyjątek "SyntaxError".
  2. Jeśli token zawiera jakiekolwiek białe znaki ASCII, to zrzuć wyjątek "InvalidCharacterError".

  3. Jeśli token znajduje się w uporządkowanym zestawie słów skojarzonym z obiektem kontekstu, to wykonają poniższe podkroki:

    1. Jeśli force nie został przekazany lub ma boolowską wartość false, to usuń token z uporządkowanego zestawu słów skojarzonego z obiektem kontekstu, uruchom kroki aktualizacji i zwróć boolowską wartość false.
    2. W przeciwnym razie zwróć boolowską wartość true.

  4. W przeciwnym razie wykonaj poniższe podkroki:

    1. Jeśli force został przekazany i ma boolowską wartość false, to zwróć boolowską wartość false.
    2. W przeciwnym razie dołącz token do uporządkowanego zestawu słów skojarzonego z obiektem kontekstu, uruchom kroki aktualizacji i zwróć boolowską wartość true.

Wywołanie metody toggle() będzie automatycznie aktualizowało powiązany z zestawem atrybut, przez co jego oryginalna zawartość (łańcuch znakowy) może ulec zmianie.

Przełączanie stanu konkretnej klasy w elementach (X)HTML to bardzo często przeprowadzany zabieg. Zamiast kombinować na tekstowej wartości z właściwości Element.className, ewentualnie używać dwóch poniższych metod usuwających/dodających klasę, zdecydowanie wygodniej zastosować jedynie metodę toggle(). Pierwotnie czynność taka wprowadzona została w wielu popularnych bibliotekach dla DOM i JavaScriptu (np. jQuery).

Metoda toggle() jest wygodniejszą postacią połączonych metod DOMTokenList.add() i DOMTokenList.remove(), aczkolwiek, w zależności od drugiego argumentu, pozwala zasymulować te metody. Jedyna zasadnicza różnica jest taka, że do toggle() można przekazywać tylko jedno słowo.

Prosty przykład:

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
<script>

	function showTokens(set){
		return Array.prototype.slice.call(set).join(" ");
	}

	var html = document.documentElement; // referencja do elementu html
	var toogled;

	document.write(html.classList.constructor); // function DOMTokenList() { [native code] }
	document.write("<br>");
	document.write(html.classList.length); // 0

	document.write("<br><br>");

	html.className = "Test1 Test2 Test3"; // ustawiamy wartość atrybutu class

	document.write(showTokens(html.classList)); // Test1 Test2 Test3
	document.write("<br>");
	document.write(html.classList.length); // 3

	document.write("<br><br>");

	toogled = html.classList.toggle("Test2"); // przełączamy słowo Test2

	document.write(showTokens(html.classList)); // Test1 Test3
	document.write("<br>");
	document.write(html.classList.length); // 2
	document.write("<br>");
	document.write(toogled); // false

	document.write("<br><br>");

	toogled = html.classList.toggle("Test2"); // przełączamy słowo Test2

	document.write(showTokens(html.classList)); // Test1 Test3 Test2
	document.write("<br>");
	document.write(html.classList.length); // 3
	document.write("<br>");
	document.write(toogled); // true

	document.write("<br><br>");

	toogled = html.classList.toggle("Test4", false); // usuwamy słowo Test4

	document.write(showTokens(html.classList)); // Test1 Test3 Test2, w IE Test1 Test3 Test2 Test 4 - błąd
	document.write("<br>");
	document.write(html.classList.length); // 3, w IE 4 - błąd
	document.write("<br>");
	document.write(toogled); // false, w IE true - błąd

	document.write("<br><br>");

	try{ // Przełączamy pusty łańcuch znakowy w uporządkowanym zestawie słów
		html.classList.toggle("");
	}
	catch(e){
		document.write("Przekazanie do metody toggle() 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ę toggle() zgodnie z wymaganiami specyfikacji DOM4. Pozostałe programy nie zwracają uwagi na drugi opcjonalny argument i działają tak, jakby go wcale nie było. Szczerze mówiąc to w Chrome istnieje pewien subtelny problem z prawidłową obsługą opcjonalnej wartości undefined przekazywanej jako drugi argument, ale dotyczy on wszystkich podobnych przypadków i wynika z błędnej implementacji Web IDL (DOM - Bug 64).

Metoda toggle() pojawia się dopiero w specyfikacji DOM4.

Składnia Web IDL#

  1. —
  2. L
  3. K
  4. T'
  5. T
  6. A
  7. O
  8. Z'
  9. Z
  10. #
interface DOMTokenList {
	boolean toggle(DOMString token, optional boolean force);
}

Specyfikacje i inne materiały#

Pasek społecznościowy

SPIS TREŚCI AKTUALNEJ STRONY

DOMTokenList (H1) DOMTokenList.toggle() (H2) Opis działania (H3) Składnia Web IDL (H3) Specyfikacje i inne materiały (H3)