DOMTokenList#
DOMTokenList.replace()#
Metoda replace() zastępuje przekazane słowo nowym słowem w uporządkowanym zestawie słów skojarzonym z danym zestawem słów DOM, jeśli się w nim znajduje.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
domTokenList.replace(token, newToken);gdzie poszczególne człony oznaczają:
- domTokenList - zestaw słów DOM będący obiektem kontekstu.
- token - łańcuchy znakowy reprezentujący przekazane słowo zastępowane nowym słowem w uporządkowanym zestawie słów, który nie może być pusty ani zawierać znaków spacji.
- newToken - łańcuchy znakowy reprezentujący nowe słowo zastępujące przekazane słowo w uporządkowanym zestawie słów, który nie może być pusty ani zawierać znaków spacji.
Algorytm wywołania metody replace(token, newToken) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Jeśli token lub newToken jest pustym łańcuchem znakowym, to zrzuć wyjątek
"SyntaxError". - Jeśli token lub newToken zawiera jakiekolwiek białe znaki ASCII, to zrzuć wyjątek
"InvalidCharacterError". - Jeśli token nie znajduje się w uporządkowanym zestawie słów skojarzonym z obiektem kontekstu, to pomiń kolejne kroki.
- Zastąp token przez newToken w uporządkowanym zestawie słów skojarzonym z obiektem kontekstu.
- Uruchom kroki aktualizacji.
Metoda replace() nie modyfikuje kolejność pozostałych słów w zestawie, co w niektórych przypadkach jest istotne, i z tego właśnie powodu, na prośbę niektórych programistów, została wprowadzona do bieżącej specyfikacji DOM4 (DOM - Bug 28).
Wywołanie metody replace() będzie automatycznie aktualizowało powiązany z zestawem atrybut, przez co jego oryginalna zawartość (łańcuch znakowy) może ulec zmianie. Przekazanie identycznych argumentów do metody również utworzy zapis zmian w obserwatorze zmian.
Kolejność argumentów w metodzie replace() bazuje na kolejności z javascriptowej metody String.prototype.replace(), a nie z metody Node.replaceChild().
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.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>");
html.classList.replace("Test2", "Test4"); // zastępujemy konkretne słowo
document.write(showTokens(html.classList)); // Test1 Test4 Test3
document.write("<br>");
document.write(html.classList.length); // 3
document.write("<br><br>");
html.classList.replace("Test5", "Test6"); // zastępujemy konkretne słowo
document.write(showTokens(html.classList)); // Test1 Test4 Test3
document.write("<br>");
document.write(html.classList.length); // 3
document.write("<br><br>");
try{ // Zastępujemy pusty łańcuch znakowy z uporządkowanego zestawu słów
html.classList.replace("", "Test6");
}
catch(e){
document.write("Przekazanie do metody replace() 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>Metoda replace() pojawia się dopiero w specyfikacji DOM4.
Składnia Web IDL#
interface DOMTokenList { void replace(DOMString token, DOMString newToken); }