`Object.isFrozen()‎`

الدالة Object.isFrozen()‎ تُحدِّد إن كان أحد الكائنات مُجمَّدًا.

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

Object.isFrozen(obj)

`obj`

الكائن الذي نريد التحقق منه.

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

قيمة منطقية (Boolean) تبيّن إذا كان الكائن مجمَّدًا أم لا.

الوصف

يكون الكائن مجمدًا إذا لم يكن قابلًا للتوسعة، وكانت جميع خاصياته غير قابلة للضبط (non-configurable)، وكانت جميع خاصيات البيانات (data properties، أي الخاصيات التي ليست دوال getter و setter) غير قابلة للكتابة (non-writable).

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

Object.isFrozen(1);
// TypeError: 1 is not an object (ES5)

Object.isFrozen(1);
// true                          (ES2015)

أمثلة

الكائنات الجديدة تكون قابلةً للتوسعة، أي أنها ليست مجمَّدة:

Object.isFrozen({}); // === false

والكائنات الفارغة غير القابلة للتوسعة هي كائنات مجمَّدة (في الحالة الراهنة):

var emptyFrozen = Object.preventExtensions({});
Object.isFrozen(emptyFrozen); // === true

الكائنات الجديدة التي تملك خاصيةً واحدةً تكون قابلةً للتوسعة، أي أنها ليست مجمَّدة:

var oneProp = { p: 42 };
Object.isFrozen(oneProp); // === false

إذا منعنا توسعة الكائن oneProp (في المثال السابق) فلن يصبح الكائن مجمَّدًا، ذلك لأنَّ الخاصية الموجودة فيه ما تزال قابلةً للضبط (وقابلةً للكتابة):

Object.preventExtensions(oneProp);
Object.isFrozen(oneProp); // === false

لكن حذف (عبر المعامل delete) تلك الخاصية (الخاصية p من الكائن oneProp) سيؤدي إلى جعل الكائن مجمَّدًا في الحالة الراهنة:

delete oneProp.p;
Object.isFrozen(oneProp); // === true

هذا مثالٌ آخرٌ عن كائنٍ لا يمكن توسعته، وفيه خاصيةٌ غير قابلةٍ للكتابة، لكنه لن يُعدّ مجمَّدًا لأنَّ تلك الخاصية ما تزال قابلةً للضبط:

var nonWritable = { e: 'prop' };
Object.preventExtensions(nonWritable);
Object.defineProperty(nonWritable, 'e', {
  writable: false
}); // جعل الخاصية غير قابلةٍ للكتابة
Object.isFrozen(nonWritable); // === false

وإذا عدّلنا تلك الخاصية وجعلناها غير قابلةٍ للضبط، فسيصبح الكائن مجمَّدًا:

Object.defineProperty(nonWritable, 'e', {
  configurable: false
}); // جعل الخاصية غير قابلةٍ للضبط
Object.isFrozen(nonWritable); // === true

وكما في المثال السابق، إذا كان لدينا كائنٌ غيرُ قابلٍ للتوسعة وفيه خاصيةٌ غير قابلةٍ للضبط لكنها قابلةٌ للكتابة، فلن يكون مجمَّدًا:

var nonConfigurable = { release: 'NON_CONF' };
Object.preventExtensions(nonConfigurable);
Object.defineProperty(nonConfigurable, 'release', {
  configurable: false
});
Object.isFrozen(nonConfigurable); // === false

وتعديل تلك الخاصية وجعلها غير قابلةٍ للكتابة سيجعل الكائن مجمَّدًا:

Object.defineProperty(nonConfigurable, 'release', {
  writable: false
});
Object.isFrozen(nonConfigurable); // === true

وكائنٌ غيرُ قابلٍ للتوسعة وفيه خاصيةُ وصولٍ (accessor property، وهي دالة getter في مثالنا هذا) لا يُمثِّل كائنًا مجمَّدًا:

var accessor = { get food() { return 'yum'; } };
Object.preventExtensions(accessor);
Object.isFrozen(accessor); // === false

لكن جعل تلك الخاصية غير قابلةٍ للضبط سيؤدي إلى جعل الكائن مجمَّدًا:

Object.defineProperty(accessor, 'food', {
  configurable: false
});
Object.isFrozen(accessor); // === true

أسهل طريقة لتجميع الكائن هي استدعاء الدالة Object.freeze()‎ عليه:

var frozen = { 1: 81 };
Object.isFrozen(frozen); // === false
Object.freeze(frozen);
Object.isFrozen(frozen); // === true

// الكائنات المجمَّدة غير قابلة للتوسعة
Object.isExtensible(frozen); // === false

// الكائنات المجمَّدة هي كائنات مختومة أيضًا
Object.isSealed(frozen); // === true

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	6	4	9	12	5.1

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

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