Object.freeze()

Die Object.freeze() Methode friert ein Objekt ein: dass heißt, es verhindert das Hinzufügen von neuen Eigenschaften zum Objekt; verhindert das Entfernen von bestehenden Eigenschaften; und verhindert, dass bestehende Eigenschaften, oder deren Abzählbarkeit, Konfigurierbarkeit oder Beschreibbarkeit verändert werden. Im Wesentlichen wird das Objekt praktisch unveränderbar gemacht. Die Methode gibt das Objekt in einer eingefrorenen Version zurück.

Syntax

Object.freeze(obj)

Parameter

obj

Das einzufrierende Objekt.

Rückgabewert

Das eingefrorende Objekt.

Beschreibung

Einem eingefrorenen Objekt können Eigenschaft weder entfernt noch hinzugefügt werden. Jeder Versuch dies durchzufüren scheitert, entweder ohne Rückmeldung , oder durch den Wurf einer TypeError Ausnahme (in den meisten Fällen, aber nicht ausschließlich im strict mode). 

Werte können für Daten-Eigenschaften nicht verändert werden. Zugriffs-Eigenschaften  (getter und setter) funktionieren gleich (und geben die Illusion, dass der Wert verändert wurde). Zu bemerken ist, dass Werte, die Objekte sind, trotzdem verändert werden können, außer sie wurden auch eingefroren.

Beispiele

var obj = {
  prop: function() {},
  foo: 'bar'
};

// Neue Eigenschaften können hinzugefügt, bestehende verändert oder entfernt werden 
obj.foo = 'baz';
obj.lumpy = 'woof';
delete obj.prop;

// Sowohl das übergebene als auch das zurückgegebene Objekt werden eingefroren.
// Es nicht nötig das zurückgegebene Objekt in einer Variable zu speichern, wenn das
// Original eingefroren werden soll.
var o = Object.freeze(obj);

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

// Nun scheitern jegliche Veränderungen
obj.foo = 'quux'; // tut (stillschweigend) nichts
obj.quaxxor = 'the friendly duck';  // fügt die Eigenschaft (stillschweigend) nicht hinzu

// ... und im strict mode werfen solche Versuche TypeErrors
function fail(){
  'use strict';
  obj.foo = 'sparky'; // wirft einen TypeError
  delete obj.quaxxor; // wirft einen TypeError
  obj.sparky = 'arf'; // wirft einen TypeError
}

fail();

// Versuchte Veränderungen durch Object.defineProperty werfen ebenso TypeErrors
Object.defineProperty(obj, 'ohai', { value: 17 }); // wirft einen TypeError
Object.defineProperty(obj, 'foo', { value: 'eit' }); // wirft einen TypeError 

Das folgende Beispiel zeigt, dass Objekt-Werte in einem eingefrorenen Objekt verändert werden können (freeze ist flach).

obj1 = {
  internal: {}
};

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

obj1.internal.a // 'aValue'

// To make obj fully immutable, freeze each object in obj.
// To do so, we use this function.

// Um obj vollständig unveränderbar zu machen, friere jedes Objekt in obj ein.
function deepFreeze(obj) {

  // Ermittle die Namen der für obj definierten Eigenschaften
  var propNames = Object.getOwnPropertyNames(obj);

  // Friere die Eigenschaften ein, bevor obj selbst eingefroren wird
  propNames.forEach(function(name) {
    var prop = obj[name];

    // Friere prop ein wenn es ein Objekt ist
    if (typeof prop == 'object' && prop !== null)
      deepFreeze(prop);
  });

  // Friere obj selbst ein
  return Object.freeze(obj);
}

obj2 = {
  internal: {}
};

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

Bemerkungen

In ES5 wird ein TypeError geworfen wenn das Argument für diese Methode kein Objekt (sondern ein primitiver Typ) ist. In ES6 wird jedes nicht-Objekt-Argument so behandelt als wenn es ein gewöhnliches, bereits eingefrorenes Objekt wäre und einfach zurückgegeben.

> Object.freeze(1)
TypeError: 1 is not an object // ES5 code

> Object.freeze(1)
1                             // ES6 code

Spezifikationen

Browserkompatibilität

Siehe auch

• Object.isFrozen()
• Object.preventExtensions()
• Object.isExtensible()
• Object.seal()
• Object.isSealed()