JavaScript/Object/getOwnPropertyDescriptor

الدالة Object.getOwnPropertyDescriptor()‎ تُعيد واصف إحدى الخاصيات التابعة لكائنٍ ما مباشرةً (أي أنها معرَّفة في الكائن نفسه، وليس في سلسلة prototype).

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

Object.getOwnPropertyDescriptor(obj, prop)

obj

الكائن الذي نريد الحصول على واصف إحدى خاصياته.

prop

اسم الخاصية التي نريد الحصول على واصفها.

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

واصف الخاصية (property descriptor) المعطاة إن كانت موجودةً في الكائن، أو القيمة undefined فيما عدا ذلك.

الوصف

تسمح لنا هذه الدالة بالحصول على الوصف الدقيق لإحدى خاصيات الكائن؛ وتتألف الخاصيات في JavaScript من سلسلة نصية تُشكِّل اسم الخاصية وواصف لتلك الخاصية؛ لمزيدٍ من المعلومات حول أنواع واصفات الخاصيات والمفاتيح التي يمكن ضبطها عليها فيمكن الرجوع إلى صفحة الدالة Object.defineProperty()‎.

لدى واصفات الخاصيات المفاتيح الآتية:

• configurable: إذا كانت قيمة هذا المفتاح هي true فيمكن تعديل واصف الخاصية (وليس قيمة الخاصية) ويمكن حذف الخاصية من الكائن. القيمة الافتراضية هي false.
• enumerable: إذا كانت قيمة هذا المفتاح هي true فستظهر هذه الخاصية عند إحصاء خاصيات (enumeration) الكائن. القيمة الافتراضية هي false.

• value: تحديد القيمة المرتبطة مع الخاصية، ويمكن أن تكون أيّ قيمة مسموحة في JavaScript (مثل الأعداد أو الدوال أو الكائنات ...إلخ.). القيمة الافتراضية هي undefined. هذا المفتاح موجودٌ في واصفات البيانات (data descriptors) فقط.
• writable: إذا كانت قيمة هذا المفتاح هي true فسيمكن تعديل القيمة المرتبطة بهذا الخاصية باستخدام معاملات الإسناد. القيمة الافتراضية هي false. هذا المفتاح موجودٌ في واصفات البيانات (data descriptors) فقط.

• get: الدالة التي ستُعدّ كدالة getter لهذا الخاصية، أو القيمة undefined إذا لم تكن هنالك دالة getter مرتبطة مع هذه الخاصية؛ القيمة التي ستُعيدها هذه الدالة ستُستخدَم كقيمة للخاصية. القيمة الافتراضية هي undefined. هذا المفتاح موجودٌ في واصفات الوصول (accessor descriptors) فقط.
• set: الدالة التي ستُعدّ كدالة setter لهذا الخاصية، أو القيمة undefined إذا لم تكن هنالك دالة setter مرتبطة مع هذه الخاصية؛ تقبل هذه الدالة وسيطًا واحدًا هو القيمة الجديدة التي حاول المستخدم إسنادها إلى هذه الخاصية. القيمة الافتراضية هي undefined. هذا المفتاح موجودٌ في واصفات الوصول (accessor descriptors) فقط.

لاحظ أنَّه في معيار ECMAScript 5 كان استعمال هذه الدالة على وسيطٍ ليس كائنًا (أي قيمةً أوليةً) سيؤدي إلى رمي TypeError، لكن بدءًا من ECMAScript 2015 (أي ES6) فستُعامل الوسائط التي لا تُمثِّل كائنات على أنها كائنات:

Object.getOwnPropertyDescriptor('foo', 0);
// TypeError: "foo" is not an object  // ES5

Object.getOwnPropertyDescriptor('foo', 0);
// الكائن المُعاد في ES2015: {
//   configurable: false,
//   enumerable: true,
//   value: "f",
//   writable: false
// }

أمثلة

سنستخدم الدالة Object.getOwnPropertyDescriptor()‎ على كائنٍ فيه دالة getter، وعلى كائنٍ فيه خاصية عادية، وعلى كائنٍ خاصيته مُنشَأة عبر الدالة Object.defineProperty()‎:

var o, d;

o = { get foo() { return 17; } };
d = Object.getOwnPropertyDescriptor(o, 'foo');
// d is {
//   configurable: true,
//   enumerable: true,
//   get: /* the getter function */,
//   set: undefined
// }

o = { bar: 42 };
d = Object.getOwnPropertyDescriptor(o, 'bar');
// d is {
//   configurable: true,
//   enumerable: true,
//   value: 42,
//   writable: true
// }

o = {};
Object.defineProperty(o, 'baz', {
  value: 8675309,
  writable: false,
  enumerable: false
});
d = Object.getOwnPropertyDescriptor(o, 'baz');
// d is {
//   value: 8675309,
//   writable: false,
//   enumerable: false,
//   configurable: false
// }

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	5	4	8	12	5

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

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