XML DOM - نود Range

نود Range برای نمایش محدوده پیوسته در مستند است.

نود Range

نود Range برای نمایش محدوده‌ای از مستند پیوسته است، مانند محدوده‌ای که کاربر با استفاده از ماوس در پنجره مرورگر انتخاب می‌کند.

اگر یک پیاده‌سازی از ماژول Range پشتیبانی کند، مستند Documentتعریف شده است روش createRange()، با فراخوانی آن می‌توان Range جدیدی ایجاد کرد.

توجه:IE روش Document.createRange() غیرقابل تطبیق را تعریف کرده است، که شیء بازگشتی آن مشابه رابط Range است، اما غیرقابل تطبیق.

رابط Range برای تعریف تعداد زیادی روش برای محدوده‌ای که در مستند “انتخاب” شده است، تعریف شده است، علاوه بر این چندین روش برای عملیات برش و چسباندن در محدوده انتخاب شده نیز وجود دارد.

ویژگی‌های رابط Range برای دریافت نودهای مرزی و انحراف محدوده ارائه می‌دهد. روش‌های آن برای تنظیم مرزهای محدوده ارائه می‌دهد. توجه داشته باشید که مرزهای محدوده می‌تواند تنظیم شود به Document یا مستند DocumentFragmentنود‌های درون آن. وقتی که نقطه‌های مرزی محدوده تعریف شد، می‌توان از روش‌های deleteContents()، extractContents()، cloneContents() و insertNode() برای عملیات برش، کپی و چسباندن استفاده کرد.

وقتی که با عملیات اضافه کردن یا حذف تغییراتی در مستند ایجاد می‌شود، تمامی Range‌های متعلق به بخشی از مستند تغییر می‌کنند (اگر نیاز باشد)، تا نقطه‌های مرزی آنها معتبر باقی بمانند و آنها (بهترین حالت ممکن) محتوای مستند مشابهی را نشان دهند.

مفاهیم: محدوده، نقطه مرزی و انحراف

یک محدوده دو نقطه مرزی دارد، یعنی یک نقطه شروع و یک نقطه پایان. هر نقطه مرزی توسط یک نود و انحراف آن نود مشخص می‌شود. این نود معمولاً نود Elementونود Documentیا نود Textبرای نود Element و نود Document، انحراف به معنای فرزندان نود است. انحراف 0 به معنای این است که نقطه مرزی قبل از اولین فرزند نود قرار دارد. انحراف 1 به معنای این است که نقطه مرزی پس از اولین فرزند نود و قبل از دومین فرزند نود قرار دارد. اما اگر نود مرزی نود Text باشد، انحراف به معنای موقعیت بین دو کاراکتر در متن است.

ثابت‌های شیء Range

این ثابت‌ها مشخص می‌کنند که چگونه نقطه‌های مرزی Range‌ها مقایسه می‌شوند.

این‌ها پارامترهای compareBoundaryPoints() روش هستند. how مقدارهای مجاز پارامترها:

ثابت‌ها توضیح
START_TO_START مقایسه نقطه شروع Range مشخص شده با نقطه شروع Range فعلی.
START_TO_END مقایسه نقطه شروع Range مشخص شده با نقطه پایان Range فعلی.
END_TO_END مقایسه نقطه پایان Range مشخص شده با نقطه پایان Range فعلی.
END_TO_START مقایسه نقطه پایان Range مشخص شده با نقطه شروع Range فعلی.

ویژگی‌های شیء Range

توجه:تمام ویژگی‌ها فقط خواندنی هستند و نمی‌توان از طریق تنظیم این ویژگی‌ها نقطه شروع و پایان Range را تغییر داد، بلکه باید از روش‌های setEnd() و setStart() استفاده کرد.

توجه:بعد از فراخوانی روش detach()، هر خواندن از این ویژگی‌ها خطای INVALID_STATE_ERR را خواهد انداخت. DOMException خطا.

ویژگی‌ها توضیح
collapsed اگر نقطه شروع و پایان Range در یک موقعیت واحد از مستند باشند، این مقدار true خواهد بود، یعنی Range خالی است یا تا شده است.
commonAncestorContainer نقطه شروع و پایان Range (یعنی نقطه‌های والد آن‌ها)، مستند عمیق‌ترین Document.
endContainer نقطه مستند شامل پایان نقطه Range.
endOffset موقعیت پایان نقطه در endContainer.
startContainer نقطه مستند شامل شروع نقطه Range.
startOffset موقعیت شروع نقطه در startContainer.

روش‌های شیء Range

توجه:اگر روش detach() Range فراخوانی شده باشد، هر روش دیگری که بر روی شیء Range فراخوانی شود، خطای INVALID_STATE_ERR را خواهد انداخت. DOMException خطا.

روش توضیح
cloneContents() یک شیء جدید DocumentFragment را بازمی‌گرداند که شامل کپی منطقه مستند نشان‌دهنده این Range است.
cloneRange() ایجاد یک شیء جدید Range که منطقه مستند مربوط به Range فعلی را نشان می‌دهد.
collapse() محدوده را تا حدی که مرزهای آن همپوشانی دارند تا حد امکان جمع‌بندی کنید.
compareBoundaryPoints() محدوده‌های مرزی مشخص شده و محدوده‌ی فعلی را مقایسه کنید و بر اساس ترتیب آن‌ها -1، 0 و 1 بازگردانید. مقایسه‌ای که باید انجام شود توسط اولین پارامتر مشخص می‌شود و باید یکی از مقادیر تعریف‌شده قبلی باشد.
deleteContents() محتوای محدوده‌ی فعلی Range را حذف کنید.
detach() اطلاع دهید که کاربرد فعلی محدوده دیگر استفاده نمی‌شود و می‌توان از دنبال کردن آن دست کشید. اگر از این روش برای محدوده استفاده شود، هر روش دیگری که برای آن محدوده فراخوانی شود، خطای INVALID_STATE_ERR را به‌همراه خواهد داشت. DOMException خطا.
extractContents() محتوای محدوده‌ی فعلی را حذف کنید و آن را به عنوان یک شیء DocumentFragment بازگردانید. این روش به‌طور مشابه با ترکیب deleteContents() و cloneContents() است.
insertNode() نقطه‌ی مشخص شده را به نقطه‌ی شروع محدوده‌ی مستند اضافه کنید.
selectNode() نقطه‌های مرزی محدوده را تنظیم کنید تا شامل نقطه‌ی مشخص شده و همه‌ی فرزندان آن باشد.
selectNodeContents() نقطه‌های مرزی محدوده را تنظیم کنید تا شامل فرزندان نقطه‌ی مشخص شده باشد، اما نقطه‌ی مشخص شده خود را شامل نشود.
setEnd() نقطه‌ی پایان محدوده را به نزدیکی‌ترین نقطه‌ی مشخص شده و با استفاده از تعداد مشخص شده تنظیم کنید.
setEndAfter() نقطه‌ی پایان محدوده را به نزدیکی‌ترین نقطه‌ی بعد از نقطه‌ی مشخص شده تنظیم کنید.
setEndBefore() نقطه‌ی پایان محدوده را به نزدیکی‌ترین نقطه‌ی قبل از نقطه‌ی مشخص شده تنظیم کنید.
setStart() نقطه‌ی شروع محدوده را به نزدیکی‌ترین نقطه‌ی مشخص شده و با استفاده از تعداد مشخص شده تنظیم کنید.
setStartAfter() نقطه‌ی شروع محدوده را به نزدیکی‌ترین نقطه‌ی بعد از نقطه‌ی مشخص شده تنظیم کنید.
setStartBefore() نقطه‌ی شروع محدوده را به نزدیکی‌ترین نقطه‌ی قبل از نقطه‌ی مشخص شده تنظیم کنید.
surroundContents() نقطه‌ی شروع محدوده‌ی مستند را تنظیم کنید و سپس همه‌ی نقطه‌های والد در محدوده را تنظیم کنید تا به فرزندان نقطه‌ی جدید اضافه شوند.
toString() محتوای متن خالصی که توسط این محدوده‌ی سند نشان‌دهنده است را بازگرداند.