CharacterData#
CharacterData.replaceData()#
Metoda replaceData() zastępuje konkretną część danych tekstowych skojarzonych z danym węzłem znakowym nową treścią.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
node.replaceData(offset, count, data);gdzie poszczególne człony oznaczają:
- node - węzeł znakowy będący obiektem kontekstu.
- offset - liczba całkowita określająca przesunięcie, od którego część danych tekstowych (kolejne znaki) będzie zastępowana nowymi danymi tekstowymi.
- count - liczbowa całkowita określająca ilość znaków w danych tekstowych, które zostaną zastąpione nowymi danymi tekstowymi. Wartość
0oznacza dodanie nowych danych tekstowych w określonej pozycji (bez zastępowania poprzednich). - data - łańcuch znakowy reprezentujący nowe dane tekstowe, które będą zastępowały określoną część w aktualnych danych tekstowych.
Algorytm wywołania metody replaceData(offset, count, data) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Zwróć wynik zastępowania danych tekstowych z węzłem będącym obiektem kontekstu, przesunięciem wskazywanym przez offset, licznikiem wskazywanym przez count oraz danymi tekstowymi wskazywanymi przez data.
Warto nadmienić, że argument offset przekazywany do metody nie może być większy od wartości z właściwości CharacterData.length danego węzła znakowego, bo zrzucony zostanie błąd.
Z praktycznego punktu widzenia metoda replaceData() jest najbardziej uniwersalna ze wszystkich metod dostępnych w interfejsie CharacterData, które odpowiadają za manipulowanie danymi tekstowymi. Dobierając odpowiednio poszczególne wartości argumentów możemy za jej pomocą uzyskać pozostałe metody (oraz właściwość CharacterData.data przy ustawianiu), z wykluczeniem jedynie CharacterData.substringData(), która w zasadzie niczego nie modyfikuje.
Dzięki takiej uniwersalności metoda replaceData() pozwala ograniczyć liczbę wywołań koniecznych przy pozostałych metodach. Przykładowo, jeśli suma offset i count jest większa od wartości z właściwości CharacterData.length danego węzła znakowego, wówczas wszystkie znaki za przesunięciem wskazywanym przez offset zostaną zastąpione, czyli efekt działania metody replaceData() będzie taki sam, jakby wywołać metodę CharacterData.deleteDeata() z tymi samymi argumentami offset i count, a następnie metodę CharacterData.appendData() z tym samym argumentem data.
Prosty przykład:
<!DOCTYPE html>
<html>
<head>
<script>
function changeData(offset, count, data){
var result = document.getElementById("info");
try{
var cloneText = document.getElementById("tekst").firstChild.cloneNode();
cloneText.replaceData(offset, count, data);
document.getElementById("info").textContent = cloneText.data;
}
catch(e){
result.innerHTML = "Przekazanie przesunięcia większego od liczby jednostek kodowych zrzuca błąd:"
result.innerHTML += "<br>" + e; // opis zależny od przeglądarki
result.innerHTML += "<br>" + e.constructor; // function DOMException() { [native code] }
}
}
</script>
</head>
<body>
<p>Kliknij konkretny przycisk by zastąpić stare dane tekstowe w testowym akapicie nowymi danymi tekstowymi.</p>
<input type="button" value="replaceData('0', '0', 'TEST')" onclick="changeData('0', '0', 'TEST')">
<input type="button" value="replaceData('0', '5', 'TEST')" onclick="changeData('0', '5', 'TEST')">
<input type="button" value="replaceData('5', '10', 'TEST')" onclick="changeData('5', '10', 'TEST')">
<input type="button" value="replaceData('0, '50', null)" onclick="changeData('0', '50', null)">
<input type="button" value="replaceData('50', '0', '')" onclick="changeData('50', '0', '')">
<p id="tekst" >Węzeł tekstowy umieszczony w testowym akapicie.</p>
<p style="color: blue;">Wynik działania przycisków:</p>
<p id="info"></p>
</body>
</html>Składnia Web IDL#
interface CharacterData : Node { void replaceData(unsigned long offset, unsigned long count, DOMString data); }