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.