Document.getSelection()‎

تنبيه: هذه تقنيّة تجريبيّة، انظر جدول دعم المتصفّحات قبل استخدام هذا التّابع في شيفرة إنتاجيّة.

يعيد التّابع Document.getSelection‎()‎ كائنًا من النّوع Selection يمثّل مجال النّص المظلَّل من طرف المستخدم، أو موقع علامة الإقحام (caret) حاليًّا.

البنية العامة

var selection = documentOrShadowRootInstance.getSelection()

المعاملات

لا توجد مُعاملات.

القيمة المعادة

كائن من النّوع Selection.

مثال

function foo() {
    var selObj = document.getSelection(); 
    alert(selObj);
    var selRange = selObj.getRangeAt(0);
    // نفّذ عمليّة ما بعد الحصول على مجال النّص المظلَّل
}

ملاحظات

تمثيل الكائن Selection على شكل سلسلة نصيّة

عند تمرير كائن إلى دالّة تتوقَّع سلسلةً نصيّة في لغة JavaScript (مثل window.alert()‎)، فإنّ تابع toString()‎ الخاصّ بالكائن يُستدعَى وتُمرّر القيمة المعادة إلى الدّالة. هذا يجعل الكائن يبدو كسلسةٍ نصيّة، لكنّه في الواقع كائن ذو توابع وخاصيّات مختلفة.

في المثال أعلاه، يُستدعى التّابع selObj.toString‎()‎ تلقائيًّا عندما يتمّ تمرير الكائن إلى التّابع window.alert()‎. لكنّ محاولة استخدام تابعٍ أو خاصيّة للتعامل مع الكائن Selection مباشرةً كما يُتَعامل مع السّلاسل النّصيّة من النّوع String في JavaScript مثل length‎ أو substr ستُنتِج (أي المحاولة) خطأً إن لم يكن الكائن يمتلك الخاصيّة أو التّابعَ المُراد استدعاؤه أو قد يُعيد نتائج غير متوقّعة إن كان التّابع موجودًا. لاستخدام الكائن Selection كسلسلة نصيّة، استدعِ التّابع toString‎()‎ على الكائن مُباشرةً كما يلي:

var selectedText = selObj.toString();

بحيث:

• selObj هو الكائن من النّوع Selection.
• selectedText‎ سلسلة نصيّة (تحتوي النّص المظلّل).

الكائنات ذات الصلة

تُوفّر نماذج الإدخال في HTML واجهات برمجيّة أكثر بساطة للتّعامل مع النّصوص المظلَّلة (انظر HTMLInputElement.setSelectionRange‎()‎).

لاحظ أنّ هناك فرقًا بين التّظليل والتّركيز على النّص. يُعيد التّابع Document.activeElement‎()‎ العنصر المُركّز عليه.

دعم المتصفّحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	53	نعم	نعم	40	نعم

مصادر ومواصفات

• مواصفة Shadow DOM.