XML DOM - كائن Range

كائن Range يمثل نطاقًا متسلسلًا في المستند.

كائن Range

كائن Range يمثل منطقة نطاق مستند متسلسل، مثل منطقة النص التي يتم اختيارها بواسطة المستخدم باستخدام الماوس في نافذة المتصفح.

إذا كان لديك تنفيذ يدعم وحدة Range، فإن كائن Documentتعريف طريقة createRange()، يمكن استدعاؤه لإنشاء كائن جديد من Range.

注意：تعريف Microsoft IE لـ Document.createRange() غير متوافق، حيث يعود الكائن الذي يقدمه مشابه لواجهة Range، لكنه غير متوافق.

تقدم واجهة Range العديد من الطرق لتعريف منطقة المستند المحددة 'المختارة'، بالإضافة إلى بعض الطرق التي يمكن استخدامها لتنفيذ عمليات القطع واللصق في المنطقة المختارة.

تقدم واجهة Range خصائص لاستخراج نقاط الحد والمقياس الإزاحة للمجال. توفر الطرق إمكانية تعيين حدود المجال. ملاحظة، يمكن تعيين حدود المجال إلى Document أو كائن DocumentFragmentمن نقاط المستند. بمجرد تعريف نقاط الحد للمجال، يمكن استخدام طرق deleteContents()، extractContents()، cloneContents()، و insertNode() لتنفيذ عمليات القطع، النسخ، واللصق.

عندما يتم تغيير المستند من خلال عملية إدراج أو حذف، فإن جميع كائنات Range التي تمثل جزءًا من المستند ستتغير (إذا لزم الأمر) لضمان بقاء نقاط الحد نافذة، وكذلك تمثيل نفس محتوى المستند (بقدر الإمكان).

مصطلحات: مجال، نقطة الحد، ومقياس الإزاحة

مجال يمتلك نقطتين حدودية، وهي نقطة البداية ونقطة النهاية. نقطة الحد محددة بنقطة و مقياس الإزاحة لتلك النقطة. عادةً تكون النقطة نقطة Elementونقطة Documentأو نقطة Textللنقاط Element و Document، مقياس الإزاحة يشير إلى فرع النقطة. إذا كان المقياس الإزاحة 0، فإن نقطة الحد هي قبل أول فرع من النقطة. إذا كان المقياس الإزاحة 1، فإن نقطة الحد هي بعد أول فرع من النقطة، قبل ثاني فرع. ولكن إذا كانت النقطة الحد نصية، فإن المقياس الإزاحة يشير إلى موقع بين حرفين في النص.

Range 对象的常量

这些常量指定了如何比较 Range 对象的边界点。

它们是 compareBoundaryPoints() 方法的 how 参数的合法值：

常量 描述
START_TO_START 用指定范围的开始点与当前范围的开始点进行比较。
START_TO_END 用指定范围的开始点与当前范围的结束点进行比较。
END_TO_END 用指定范围的结束点与当前范围的结束点进行比较。
END_TO_START 用指定范围的结束点与当前范围的开始点进行比较。

Range 对象的属性

注意：所有属性都是只读的，不能通过设置这些属性改变范围的开始点和结束点，必须调用 setEnd() 方法和 setStart() 方法实现这一点。

注意：调用 detach() 方法后，对这些属性的任何读操作都会抛出代码为 INVALID_STATE_ERR 的 استثناء DOMException.

属性 描述
collapsed 如果范围的开始点和结束点在文档的同一位置，则为 true，即范围是空的，或折叠的。
commonAncestorContainer 范围的开始点和结束点的（即它们的祖先节点）、嵌套最深的 Document 节点。
endContainer 包含范围的结束点的 Document 节点。
endOffset endContainer 中的结束点位置。
startContainer 包含范围的开始点的 Document 节点。
startOffset startContainer 中的开始点位置。

Range 对象的方法

注意：如果调用了范围的 detach() 方法，那么接下来调用 Range 对象的任何方法都会抛出代码为 INVALID_STATE_ERR 的 استثناء DOMException.

方法 描述
cloneContents() 返回新的 DocumentFragment 对象，它包含该范围表示的文档区域的副本。
cloneRange() 创建一个新的 Range 对象，表示与当前的 Range 对象相同的文档区域。
collapse() طي النطاق بحيث تتطابق نقاط الحدود.
compareBoundaryPoints() مقارنة حدود النطاق المحدد وحدود النطاق الحالي، وإرجاع -1، 0، أو 1 بناءً على ترتيبها. يتم تحديد ما إذا كانت المقارنة تشمل الحد الأعلى أو السفلي من النطاق بناءً على أول معامل، ويجب أن يكون قيمته إحدى القيم المحددة مسبقًا.
deleteContents() حذف المنطقة الوثائقية التي يمثلها النطاق الحالي.
detach() إعلام بإنهاء استخدام النطاق الحالي، يمكن التوقف عن المتابعة. إذا تم استدعاء هذه الطريقة للنطاق، فإن أي طريقة أخرى تتبعها للنطاق ستقوم بإلقاء استثناء INVALID_STATE_ERR. استثناء DOMException.
extractContents() حذف المنطقة الوثائقية التي يمثلها النطاق الحالي، وإرجاع محتواها كعنصر DocumentFragment. يشبه هذا الطريقة مجموعة من طريقة deleteContents() و cloneContents().
insertNode() أدخل العنصر المحدد في بداية نطاق الوثائق.
selectNode() ضبط حدود النطاق بحيث يحتوي على العنصر المحدد وأبناءه.
selectNodeContents() ضبط حدود النطاق بحيث يحتوي على أبناء العنصر المحدد دون العنصر نفسه.
setEnd() ضبط نهاية النطاق إلى العنصر المحدد والفاصل.
setEndAfter() ضبط نهاية النطاق إلى ما بعد العنصر المحدد.
setEndBefore() ضبط نهاية النطاق إلى ما قبل العنصر المحدد.
setStart() ضبط بداية النطاق إلى الفاصل المحدد في العنصر المحدد.
setStartAfter() ضبط بداية النطاق إلى ما بعد العنصر المحدد.
setStartBefore() ضبط بداية النطاق إلى ما قبل العنصر المحدد.
surroundContents() أدخل العنصر المحدد في بداية نطاق الوثائق، ثم أعد تحديد جميع عناصر الأب لجميع العناصر في النطاق لتكون أبناء العنصر المدمج الجديد.
toString() استرداد محتوى النص النقي للمنطقة الوثائقية التي يمثلها النطاق.