عرض مصدر JavaScript/Symbol/for

<noinclude>{{DISPLAYTITLE:<code>Symbol.for(key)‎</code>}}</noinclude>
الدالة <code>Symbol.for(key)‎</code> تبحث عن رمزٍ موجودٍ مسبقًا في سجل الرموز العام الذي له مفتاحٌ معيّن وستُعيده عند وجوده؛ وإن لم يكن موجودًا فسيُنشَأ رمزٌ جديدٌ في سجل الرموز العام له هذا المفتاح.

== البنية العامة ==
<syntaxhighlight lang="javascript">
Symbol.for(key);

</syntaxhighlight>

=== <code>key</code> ===
سلسلة نصيّة تُمثِّل مفتاح الرمز الذي سنبحث عنه (وستُستخدَم أيضًا لوصف الرمز).

=== القيمة المعادة ===
الرمز المرتبط بالمفتاح إن كان موجودًا؛ وإلا فسيُنشَأ ويُعاد رمزٌ جديد.

== الوصف ==
بخلاف الدالة <code>Symbol()‎</code>، تُنشِئ الدالة <code>Symbol.for()‎</code> رمزًا في سجل الرموز العام (global symbol registry)؛ ليس من الضروري أن تُنشِئ الدالة <code>Symbol.for()‎</code> رمزًا جديدًا في كل استدعاء، فهي تتحقق أوّلًا إن كان الرمز المرتبط بالمفتاح <code>key</code> موجودًا من قبل في السجل، ففي تلك الحالة سيُعاد ذاك الرمز؛ وإن لم يُعثَر على رمزٍ له المفتاح المعطى فستُنشِئ الدالة <code>Symbol.for()</code>‎ رمزًا جديدًا عامًا.

=== سجل الرموز العام ===
سجل الرموز العام (global symbol registry) هو قائمةٌ لعناصرها البنية العامة الآتية، وتكون فارغةً مبدئيًا:
{| class="wikitable"
!اسم الحقل
!القيمة
|-
|<code><nowiki>[[key]]</nowiki></code>
|سلسلة نصيّة تُستخدَم لتعريف (identify) رمز.
|-
|<code><nowiki>[[symbol]]</nowiki></code>
|الرمز الذي سيكون متاحًا في كامل البرنامج.
|}

== أمثلة ==
سنستخدم الدالة <code>Symbol.for()‎</code> لإنشاء رمز عام جديد ثم سنحصل على قيمته:<syntaxhighlight lang="javascript">
Symbol.for('foo'); // إنشاء رمز عام جديد
Symbol.for('foo'); // الحصول على قيمته

</syntaxhighlight>نبين في المثال الآتي أنَّ الرمز <code>bar</code> له نفس القيم في السجل العام، لكن ليس في السجل المحلي:<syntaxhighlight lang="javascript">
Symbol.for('bar') === Symbol.for('bar'); // true
Symbol('bar') === Symbol('bar');         // false

</syntaxhighlight>لاحظ أنَّ المفتاح يُستخدَم أيضًا لوصف الرمز:<syntaxhighlight lang="javascript">
var sym = Symbol.for('mario');
sym.toString(); // "Symbol(mario)"

</syntaxhighlight>لتفادي التضاربات بالأسماء بين رموز السجلات العامة التي تُنشِئها وبين الرموز العامة الأخرى التي تُنشِئها المكتبات (مثلًا)، فمن المناسب وضع سابقة (prefix) قبل الرموز:<syntaxhighlight lang="javascript">
Symbol.for('hsoub.foo');
Symbol.for('hsoub.bar');

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|40
|36
|غير مدعومة
|نعم
|9
|}
على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة.

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-symbol.for ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-symbol.for ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Symbol|{{SUBPAGENAME}}]]