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

<noinclude>{{DISPLAYTITLE:<code>Object.freeze()‎</code>}}</noinclude>
الدالة <code>Object.freeze()‎</code> تُجمِّد كائنًا، مما يمنع إضافة خاصيات جديدة إليه، ويمنع حذف الخاصيات الموجودة فيه، ويمنع تعديل قيمة أو قابلية إحصاء أو قابلية ضبط أو قابلية الكتابة التابعة لخاصياته؛ ويمنع أيضًا تعديل سلسلة prototype، وستُعيد هذه الدالة الكائن في الحالة «المُجمَّدة».
==البنية العامة==
<syntaxhighlight lang="javascript">
Object.freeze(obj)

</syntaxhighlight>

=== <code>obj</code> ===
الكائن الذي سيُجمَّد.
=== القيمة المعادة ===
الكائن المُجمَّد.

== الوصف ==
لا يمكن إضافة أو حذف أيّ شيء من خاصيات الكائنات المجمّدة؛ وأي محاولة لفعل ذلك ستفشل إما بصمت أو سترمي الاستثناء <code>[[JavaScript/TypeError|TypeError]]</code> (وسيرمى هذا الخطأ عادةً في [[JavasScript/Strict Mode|نمط strict]]).

لا يمكن تغيير قيم الخاصيات التي تحمل بيانات، أو دوال [[JavaScript/get|getter]] و [[JavaScript/set|setter]]، لاحظ أنَّه ما يزال بالإمكان تعديل قيم الكائنات المُسنَدة إلى الخاصيات ما لم تُجمَّد أيضًا.

من الممكن تجمد المصفوفات مثل الكائنات، إذ لن نستطيع تعديل قيم عناصرها، أو إضافة أو حذف عناصر منها. 

لاحظ أنَّه في معيار ECMAScript 5 كان استعمال هذه الدالة على وسيطٍ ليس كائنًا (أي قيمةً أوليةً) سيؤدي إلى رمي <code>[[JavaScript/TypeError|TypeError]]</code>، لكن بدءًا من ECMAScript 2015 (أي ES6) فستُعامل الوسائط التي لا تُمثِّل كائنات على أنها كائنات مُجمَّدة، أي أن قيمتها ستُعاد كما هي: <syntaxhighlight lang="javascript">
> Object.freeze(1)
TypeError: 1 is not an object // ES5

> Object.freeze(1)
1                             // ES2015

</syntaxhighlight>

== أمثلة ==

=== تجميد الكائنات ===
سنُنشِئ في المثال الآتي كائنًا باسم <code>obj</code> ونُضيف إليه خاصيات جديدة، ونُعدِّل خاصيات موجودة فيه، ونحذف أخرى:<syntaxhighlight lang="javascript">
var obj = {
  prop: function() {},
  foo: 'bar'
};

obj.foo = 'baz';
obj.lumpy = 'woof';
delete obj.prop;

</syntaxhighlight>لاحظ أنَّ الدالة <code>Object.freeze()‎</code> ستُعيد الكائن المُجمّد، لكنها ستُجمِّد الكائن الأصلي أيضًا؛ لذا من غير الضروري حفظ الكائن المُعاد من الدالة لتجميد الكائن الأصلي:<syntaxhighlight lang="javascript">
var o = Object.freeze(obj);

o === obj; // true
Object.isFrozen(obj); // === true

</syntaxhighlight>لاحظ أنَّ عملية تعديل قيم الخاصيات أو إضافة خاصيات جديدة ستفشل بصمت، أما إذا كان [[JavaScript/Strict Mode|نمط strict]] مفعَّلًا فسيرمى الخطأ <code>[[JavaScript/TypeError|TypeError]]</code>:<syntaxhighlight lang="javascript">
obj.foo = 'quux'; // لن يحدث شيء
// ولن تُضاف الخاصية الجديدة
obj.quaxxor = 'the friendly duck';

function fail(){
  'use strict';
  obj.foo = 'sparky'; // TypeError
  delete obj.quaxxor; // TypeError
  obj.sparky = 'arf'; // TypeError
}

fail();
</syntaxhighlight>محاولة إجراء تعديلات باستخدام الدالة <code>[[JavaScript/Object/defineProperty|Object.defineProperty()‎]]</code> ستُسبِّب برمي الخطأ <code>[[JavaScript/TypeError|TypeError]]</code>:<syntaxhighlight lang="javascript">
Object.defineProperty(obj, 'ohai', { value: 17 });   // TypeError
Object.defineProperty(obj, 'foo', { value: 'eit' }); // TypeError

</syntaxhighlight>من المستحيل تعديل قيمة الخاصية <code>prototype</code>، وكلا التعبيرين الآتيين سيرمي الخطأ <code>[[JavaScript/TypeError|TypeError]]</code>:<syntaxhighlight lang="javascript">
Object.setPrototypeOf(obj, { x: 20 })
obj.__proto__ = { x: 20 }

</syntaxhighlight>

=== تجميد المصفوفات ===
سنُنشِئ مصفوفةً باسم <code>a</code>، ثم سنجمِّدها ونحاول تعديل قيمها، وستفشل تلك المحاولات بصمت؛ أما إذا كنّا في [[JavaScript/Strict Mode|نمط strict]] فسيرمى الخطأ <code>[[JavaScript/TypeError|TypeError]]</code>:<syntaxhighlight lang="javascript">
let a = [0];
Object.freeze(a); // لم يعد بالإمكان تعديل المصفوفة

a[0]=1;    // ستفشل بصمت
a.push(2); // ستفشل بصمت

// سيرمى الخطأ TypeError
function fail() {
  "use strict"
  a[0] = 1;
  a.push(2);
}

fail();

</syntaxhighlight>

=== التجميد العميق ===
صحيحٌ أنَّ الكائن المُجمَّد لن يكون قابلًا للتعديل، لكنه ليس «ثابتًا» (constant) بالضرورة؛ ففي المثال الآتي سيكون التجميد سطحيًا:<syntaxhighlight lang="javascript">
obj1 = {
  internal: {}
};

Object.freeze(obj1);
obj1.internal.a = 'aValue';

obj1.internal.a // 'aValue'

</syntaxhighlight>أما لجعل الكائن ساكنًا فيجب تجميد كل خاصية من خاصيات ذاك الكائن، وهذا ما يدعى «التجميد العميق»:<syntaxhighlight lang="javascript">
function deepFreeze(obj) {

  // الحصول على أسماء الخاصيات الموجودة في الكائن
  var propNames = Object.getOwnPropertyNames(obj);

  // تجميد تلك الخاصيات قبل تجميد الكائن
  propNames.forEach(function(name) {
    var prop = obj[name];

    // تجميد الخاصية إن كانت كائنًا
    if (typeof prop == 'object' && prop !== null)
      deepFreeze(prop);
  });

  // تجميد الكائن نفسه
  return Object.freeze(obj);
}

obj2 = {
  internal: {}
};

deepFreeze(obj2);
obj2.internal.a = 'anotherValue';
obj2.internal.a; // undefined

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|6
|4
|9
|12
|5.1
|}
== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-object.freeze ECMAScript Latest Draft].
*معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-object.freeze ECMAScript 2015 (6th Edition)]‎.
*معيار [http://www.ecma-international.org/ecma-262/5.1/#sec-15.2.3.9 ECMAScript 5.1]. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Object|{{SUBPAGENAME}}]]