عرض مصدر JavaScript/Object/defineProperties

<noinclude>{{DISPLAYTITLE:<code>Object.defineProperties()‎</code>}}</noinclude>
الدالة <code>Object.defineProperties()‎</code> تُعرِّف خاصياتٍ جديدةً على كائنٍ مباشرةً، أو تُعدِّل خاصياتٍ موجودةً مسبقًا في كائنٍ ثم تُعيد هذا الكائن.
==البنية العامة==
<syntaxhighlight lang="javascript">
Object.defineProperties(obj, props)

</syntaxhighlight>

=== <code>obj</code> ===
الكائن الذي نريد تعريف الخاصيات فيه أو تعديلها.

=== <code>props</code> ===
كائنٌ فيه خاصياتٌ تابعةٌ له وقابلةٌ للإحصاء تُحدِّد واصفات الخاصيات (property descriptors) التي ستُضاف إلى الكائن أو تُعدِّله والتي سترتبط بأسماء الخاصيات. وهنالك نوعان للواصفات: واصفات البيانات (data descriptors) وواصفات الوصول (accessor descriptors)، راجع صفحة الدالة <code>[[JavaScript/Object/defineProperty|Object.defineProperty()‎]]</code> لمزيدٍ من التفاصيل.    

واصفات البيانات وواصفات الوصول هما كائنات، ويتشاركان المفاتيح المطلوبة الآتية:    
*<code>configurable</code>: إذا كانت قيمة هذا المفتاح هي <code>true</code> فيمكن تعديل '''واصف الخاصية''' (وليس قيمة الخاصية) ويمكن [[JavaScript/delete|حذف]] الخاصية من الكائن. القيمة الافتراضية هي <code>false</code>.
*<code>enumerable</code>: إذا كانت قيمة هذا المفتاح هي <code>true</code> فستظهر هذه الخاصية عند إحصاء خاصيات (enumeration) الكائن. القيمة الافتراضية هي <code>false</code>.
يمكن أن تتواجد المفاتيح الاختيارية الآتية في واصفات البيانات:
*<code>value</code>: تحديد القيمة المرتبطة مع الخاصية، ويمكن أن تكون أيّ قيمة مسموحة في JavaScript (مثل الأعداد أو الدوال أو الكائنات ...إلخ.). القيمة الافتراضية هي <code>[[JavaScript/undefined|undefined]]</code>.
*<code>writable</code>: إذا كانت قيمة هذا المفتاح هي <code>true</code> فسيمكن تعديل القيمة المرتبطة بهذا الخاصية باستخدام [[JavaScript/Assignment Operators|معاملات الإسناد]]. القيمة الافتراضية هي <code>false</code>.
يمكن أن تتواجد المفاتيح الاختيارية الآتية في واصفات الوصول:
*<code>get</code>: الدالة التي ستُعدّ [[JavaScript/get|كدالة getter]] لهذا الخاصية، أو القيمة <code>[[JavaScript/undefined|undefined]]</code> إذا لم تكن هنالك [[JavaScript/get|دالة getter]] مرتبطة مع هذه الخاصية؛ القيمة التي ستُعيدها هذه الدالة ستُستخدَم كقيمة للخاصية. القيمة الافتراضية هي <code>[[JavaScript/undefined|undefined]]</code>.
*<code>set</code>: الدالة التي ستُعدّ [[JavaScript/set|كدالة setter]] لهذا الخاصية، أو القيمة <code>[[JavaScript/undefined|undefined]]</code> إذا لم تكن هنالك [[JavaScript/set|دالة setter]] مرتبطة مع هذه الخاصية؛ تقبل هذه الدالة وسيطًا واحدًا هو القيمة الجديدة التي حاول المستخدم إسنادها إلى هذه الخاصية. القيمة الافتراضية هي <code>[[JavaScript/undefined|undefined]]</code>.
=== القيمة المعادة ===
الكائن الذي مُرِّرَ إلى الدالة.

== الوصف ==
الدالة <code>Object.defineProperties()‎</code> تُعرِّف جميع الخاصيات على الكائن <code>obj</code>، والتي تكون تابعة للكائن <code>props</code> (ويجب أن تكون قابلةً للإحصاء أيضًا). 

== أمثلة ==
مثال عن تعريف خاصيتين <code>property1</code> و <code>property2</code> على الكائن <code>obj</code>، وإحدى تلك الخاصيتين قابلةٌ للكتابة (عبر إسناد القيمة <code>true</code> للمفتاح <code>writable</code>) وأخرى غير قابلة للكتابة (عبر إسناد القيمة <code>false</code> للمفتاح <code>writable</code>):<syntaxhighlight lang="javascript">
var obj = {};
Object.defineProperties(obj, {
  'property1': {
    value: true,
    writable: true
  },
  'property2': {
    value: 'Hello',
    writable: false
  }
  // ...
});
</syntaxhighlight>

== تعويض نقص دعم المتصفحات ==
بفرض أنَّ بيئة التشغيل غير مُعدَّلة، إذ تُشير فيها جميع الأسماء والخاصيات إلى قيمها الابتدائية، فالدالة الآتية تكافئ الدالة <code>Object.defineProperties()‎</code> تقريبًا:

<syntaxhighlight lang="javascript">
function defineProperties(obj, properties) {
  function convertToDescriptor(desc) {
    function hasProperty(obj, prop) {
      return Object.prototype.hasOwnProperty.call(obj, prop);
    }

    function isCallable(v) {
      // NB: modify as necessary if other values than functions are callable.
      return typeof v === 'function';
    }

    if (typeof desc !== 'object' || desc === null)
      throw new TypeError('bad desc');

    var d = {};

    if (hasProperty(desc, 'enumerable'))
      d.enumerable = !!desc.enumerable;
    if (hasProperty(desc, 'configurable'))
      d.configurable = !!desc.configurable;
    if (hasProperty(desc, 'value'))
      d.value = desc.value;
    if (hasProperty(desc, 'writable'))
      d.writable = !!desc.writable;
    if (hasProperty(desc, 'get')) {
      var g = desc.get;

      if (!isCallable(g) && typeof g !== 'undefined')
        throw new TypeError('bad get');
      d.get = g;
    }
    if (hasProperty(desc, 'set')) {
      var s = desc.set;
      if (!isCallable(s) && typeof s !== 'undefined')
        throw new TypeError('bad set');
      d.set = s;
    }

    if (('get' in d || 'set' in d) && ('value' in d || 'writable' in d))
      throw new TypeError('identity-confused descriptor');

    return d;
  }

  if (typeof obj !== 'object' || obj === null)
    throw new TypeError('bad obj');

  properties = Object(properties);

  var keys = Object.keys(properties);
  var descs = [];

  for (var i = 0; i < keys.length; i++)
    descs.push([keys[i], convertToDescriptor(properties[keys[i]])]);

  for (var i = 0; i < descs.length; i++)
    Object.defineProperty(obj, descs[i][0], descs[i][1]);

  return obj;
}

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|5
|4
|9
|11.6
|5
|}

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