XML DOM - objek Range

objek Range mewakili kawasan rentang berurutan di dalam dokumen.

objek Range

objek Range mewakili kawasan rentang berurutan dokumen, seperti kawasan yang dipilih pengguna dengan menggesek tetikus di dalam tingkap pelayar.

Jika implementasi mendukung modul Range, maka objek Documentyang telah metod createRange()dengan panggilannya, objek Range baru akan dibuat.

Perhatian:IE telah mendefinikan metod Document.createRange() yang tak kompatibel, objek yang dihasilkan seakan-akan dengan Interface Range tetapi tak kompatibel.

Interface Range menyediakan banyak metod untuk menentukan kawasan 'terpilih' dokumen, selain daripada beberapa metod yang boleh digunakan untuk operasi pemotongan dan menempel di kawasan terpilih.

Properti Interface Range menyediakan cara untuk mendapatkan titik batas dan offset rentang. Metodnya menyediakan cara untuk menetapkan batas rentang. Perhatikan, batas rentang boleh ditetapkan Document atau objek DocumentFragmentpada node. Sekali titik batas rentang telah ditentukan, operasi pemotongan, menyalin dan menempel boleh dilakukan dengan menggunakan metod deleteContents(), extractContents(), cloneContents() dan insertNode().

Ketika dokumen diubah melalui operasi penambahan atau penghapusan, semua objek Range yang mewakili sebahagian dokumen akan berubah (jika perlu), untuk memastikan titik batas mereka tetap berlaku, dan untuk memastikan mereka (sebagai yang hampir mungkin) mewakili kandungan dokumen yang sama.

Kata istilah: rentang, titik batas dan offset

Sebuah rentang mempunyai dua titik batas, iaitu titik awal dan titik akhir. Setiap titik batas ditentukan oleh sebuah node dan offset yang ada di dalam node itu. Biasanya node itu adalah Node Element、Node Documentatau Node TextUntuk node Element dan node Document, offset merujuk kepada anak node yang ada di dalam node itu. Offset 0 menunjukkan titik batas berada sebelum pertama anak node. Offset 1 menunjukkan titik batas berada setelah pertama anak node, sebelum kedua anak node. Tetapi jika titik batas adalah node Text, offset merujuk kepada posisi antara dua karakter di dalam teks.

Konstanta objek Range

Konstanta ini menentukan cara membandingkan titik batas objek Range.

Mereka adalah compareBoundaryPoints() method how Nilai yang sah parameter:

Konstanta Deskripsi
START_TO_START Bandingkan titik awal range yang ditentukan dengan titik awal range saat ini.
START_TO_END Bandingkan titik awal range yang ditentukan dengan titik akhir range saat ini.
END_TO_END Bandingkan titik akhir range yang ditentukan dengan titik akhir range saat ini.
END_TO_START Bandingkan titik akhir range yang ditentukan dengan titik awal range saat ini.

Atribut objek Range

Perhatian:Semua atribut adalah hanya baca, tidak dapat diubah melalui pengaturan atribut ini untuk mengubah titik awal dan titik akhir range, harus dipanggil method setEnd() dan setStart() untuk mencapai hal ini.

Perhatian:Operasi baca apapun terhadap atribut ini setelah pemanggilan method detach() akan melempar code INVALID_STATE_ERR DOMException gangguan.

Atribut Deskripsi
collapsed Jika titik awal dan titik akhir range berada di lokasi yang sama di dokumen, maka nilai ini adalah true, yaitu range kosong, atau tergabung.
commonAncestorContainer Node Dokumen yang paling dalam dan adalah ancestor dari titik awal dan titik akhir range (yaitu mereka sendiri),
endContainer Node Dokumen yang mengandung titik akhir range
endOffset Posisi titik akhir di endContainer
startContainer Node Dokumen yang mengandung titik awal range
startOffset Posisi titik awal di startContainer

Metode objek Range

Perhatian:Jika method detach() range telah dipanggil, maka pemanggilan method mana pun atas objek Range akan melempar code INVALID_STATE_ERR DOMException gangguan.

Metode Deskripsi
cloneContents() Kembalikan objek DocumentFragment baru yang mengandung salinan area dokumen yang diwakili oleh range ini.
cloneRange() Buat objek Range baru yang menyatakan area dokumen yang sama seperti objek Range saat ini.
collapse() Gelincirkan rentang ini, sehingga titik batasnya bersama-sama.
compareBoundaryPoints() Bandingkan batas rentang yang ditentukan dan batas rentang saat ini, kembalikan -1, 0, atau 1 berdasarkan urutan mereka. Bandingkan batas poin mana yang ditentukan oleh parameter pertama, nilai itu harus salah satu konstanta yang didefinisi sebelumnya.
deleteContents() Hapus kawasan dokumen yang diwakili oleh objek Range saat ini.
detach() Beritahu implementasi bahwa rentang saat ini tidak lagi digunakan, dapat berhenti melacak. Jika metode ini di panggil, maka metode apapun yang di panggil berikutnya untuk rentang ini akan melempar gangguan dengan kode INVALID_STATE_ERR. DOMException gangguan.
extractContents() Hapus kawasan dokumen yang diwakili oleh rentang saat ini, dan kembalikan konten kawasan itu dalam bentuk objek DocumentFragment. Metode ini dan kombinasi metode cloneContents() dan deleteContents() sangat mirip.
insertNode() Sisihkan node yang ditentukan ke titik awal rentang dokumen.
selectNode() Atur batas rentang ini untuk termasuk node yang ditentukan dan semua keturunannya.
selectNodeContents() Atur batas rentang ini untuk termasuk keturunan node yang ditentukan, tetapi tidak termasuk node yang ditentukan sendiri.
setEnd() Atur titik akhir rentang ini untuk berdekatan dengan node dan offset yang ditentukan.
setEndAfter() Atur titik akhir rentang ini untuk berdekatan dengan node yang ditentukan setelahnya.
setEndBefore() Atur titik akhir rentang ini untuk berdekatan dengan node yang ditentukan sebelumnya.
setStart() Atur titik awal rentang ini untuk berdekatan dengan offset yang ditentukan dalam node yang ditentukan.
setStartAfter() Atur titik awal rentang ini untuk berdekatan dengan node yang ditentukan setelahnya.
setStartBefore() Atur titik awal rentang ini untuk berdekatan dengan node yang ditentukan sebelumnya.
surroundContents() Sisihkan node yang ditentukan ke titik awal rentang dokumen, kemudian atur pengecualian semua node dalam rentang, jadikan mereka menjadi keturunan node yang disisihkan.
toString() Kembalikan teks asli kawasan dokumen yang diwakili oleh rentang ini.