عرض مصدر JavaScript/Document/getSelection

<noinclude>{{DISPLAYTITLE:<code>Document.getSelection()‎</code>}}</noinclude>
'''تنبيه:''' هذه تقنيّة تجريبيّة، انظر جدول دعم المتصفّحات قبل استخدام هذا التّابع في شيفرة إنتاجيّة.

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

==البنية العامة==
<syntaxhighlight lang="javascript">
var selection = documentOrShadowRootInstance.getSelection()
</syntaxhighlight>
===المعاملات===
لا توجد مُعاملات.

===القيمة المعادة===
كائن من النّوع <code>Selection</code>.

==مثال==
<syntaxhighlight lang="javascript">
function foo() {
    var selObj = document.getSelection(); 
    alert(selObj);
    var selRange = selObj.getRangeAt(0);
    // نفّذ عمليّة ما بعد الحصول على مجال النّص المظلَّل
}
</syntaxhighlight>
==ملاحظات==
===تمثيل الكائن  <code>Selection</code> على شكل سلسلة نصيّة===
عند تمرير كائن إلى دالّة تتوقَّع سلسلةً نصيّة في لغة JavaScript (مثل <code>window.alert()‎</code>)، فإنّ تابع <code>toString()‎</code> الخاصّ بالكائن يُستدعَى وتُمرّر القيمة المعادة إلى الدّالة. هذا يجعل الكائن يبدو كسلسةٍ نصيّة، لكنّه في الواقع كائن ذو توابع وخاصيّات مختلفة.

في المثال أعلاه، يُستدعى التّابع  <code>selObj.toString‎()‎</code> تلقائيًّا عندما يتمّ تمرير الكائن إلى التّابع <code>window.alert()‎</code>. لكنّ محاولة استخدام تابعٍ أو خاصيّة للتعامل مع الكائن <code>Selection</code> مباشرةً كما يُتَعامل مع السّلاسل النّصيّة من النّوع String في JavaScript مثل <code>length‎</code> أو <code>substr</code> ستُنتِج (أي المحاولة) خطأً إن لم يكن الكائن يمتلك الخاصيّة أو التّابعَ المُراد استدعاؤه أو قد يُعيد نتائج غير متوقّعة إن كان التّابع موجودا. لاستخدام الكائن  <code>Selection</code> كسلسلة نصيّة، استدعِ التّابع <code>toString‎()‎</code> على الكائن مُباشرةً كما يلي:
<syntaxhighlight lang="javascript">
var selectedText = selObj.toString();
</syntaxhighlight>
بحيث:
* <code>selObj</code> هو الكائن من النّوع  <code>Selection</code>.
* <code>selectedText‎</code> سلسلة نصيّة (تحتوي النّص المظلّل).
===الكائنات ذات الصلة===
تُوفّر نماذج الإدخال في HTML واجهات برمجيّة أكثر بساطة للتّعامل مع النّصوص المظلَّلة (انظر <code>HTMLInputElement.setSelectionRange‎()‎</code>).

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

==دعم المتصفّحات==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|53
|نعم
|نعم
|40
|نعم
|-
|}

==مصادر ومواصفات==
* مواصفة [https://w3c.github.io/webcomponents/spec/shadow/#extensions-to-the-documentorshadowroot-mixin Shadow DOM]

[[تصنيف:JavaScript]]
 [[تصنيف:Web API]]
 [[تصنيف:DOM]]
 [[تصنيف:Document]]