Symbol.for(key)‎

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

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

Symbol.for(key);

key

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

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

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

الوصف

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

سجل الرموز العام

سجل الرموز العام (global symbol registry) هو قائمةٌ لعناصرها البنية العامة الآتية، وتكون فارغةً مبدئيًا:

اسم الحقل	القيمة
[[key]]	سلسلة نصيّة تُستخدَم لتعريف (identify) رمز.
[[symbol]]	الرمز الذي سيكون متاحًا في كامل البرنامج.

أمثلة

سنستخدم الدالة Symbol.for()‎ لإنشاء رمز عام جديد ثم سنحصل على قيمته:

Symbol.for('foo'); // إنشاء رمز عام جديد
Symbol.for('foo'); // الحصول على قيمته

نبين في المثال الآتي أنَّ الرمز bar له نفس القيم في السجل العام، لكن ليس في السجل المحلي:

Symbol.for('bar') === Symbol.for('bar'); // true
Symbol('bar') === Symbol('bar');         // false

لاحظ أنَّ المفتاح يُستخدَم أيضًا لوصف الرمز:

var sym = Symbol.for('mario');
sym.toString(); // "Symbol(mario)"

لتفادي التضاربات بالأسماء بين رموز السجلات العامة التي تُنشِئها وبين الرموز العامة الأخرى التي تُنشِئها المكتبات (مثلًا)، فمن المناسب وضع سابقة (prefix) قبل الرموز:

Symbol.for('hsoub.foo');
Symbol.for('hsoub.bar');

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	40	36	غير مدعومة	نعم	9

على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة.

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

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.