Die Methode Object.defineProperty() definiert eine neue Eigenschaft direkt auf ein Objekt, oder modifiziert eine Eigenschaft. Schließlich gibt die Funktion das Objekt zurück.
Object.defineProperty(obj, prop, descriptor)objpropdescriptorDas Objekt, welches behandelt wurde.
Diese Methode erlaubt präzises Hinzufügen oder Modifizieren von Eigenschaften eines Objektes. Normal property addition through assignment creates properties which show up during property enumeration ({{jsxref("Statements/for...in", "for...in")}} loop or {{jsxref("Object.keys")}} method), whose values may be changed, and which may be {{jsxref("Operators/delete", "deleted", "", 1)}}. This method allows these extra details to be changed from their defaults. Standardmäßig sind Werte die mit Object.defineProperty() hinzugefügt wurden unveränderbar.
Attribut Deskriptoren unterscheiden sich in zwei Varianten: Daten Deskriptoren und Zugiffsdeskriptoren. Ein Datendeskriptor ist ein Attribut welches einen Wert hat das schreibbar oder nicht schreibbar sein kann. Ein Zugriffsdeskriptor ist ein Attribut das mit einem "getter/setter Paar" beschrieben wird. Ein Deskriptor muss von einer dieser beiden Arten sein, er kann nicht beides sein.
Beide, Daten- und Zugriffsdeskriptoren sind Objekte. Sie teilen die folgenden benötigten Objektschlüssel:
configurabletrue if and only if the type of this property descriptor may be changed and if the property may be deleted from the corresponding object.false.enumerabletrue if and only if this property shows up during enumeration of the properties on the corresponding object.false.Ein Datendeskriptor hat außerdem die folgenden, optionalen Schlüssel:
valuewritabletrue if and only if the value associated with the property may be changed with an {{jsxref("Operators/Assignment_Operators", "assignment operator", "", 1)}}.false.Ein Zugriffsdeskriptor hat außerdem die folgenden, optionalen Schlüssel:
getsetBear in mind that these options are not necessarily the descriptor's own properties, and properties inherited from the prototype chain will be considered too. In order to ensure these defaults are preserved you might freeze the {{jsxref("Object.prototype")}} upfront or specify all options explicitly.
// being explicit
Object.defineProperty(obj, 'key', {
enumerable: false,
configurable: false,
writable: false,
value: 'static'
});
// recycling same object
function withValue(value) {
var d = withValue.d || (
withValue.d = {
enumerable: false,
writable: false,
configurable: false,
value: null
}
);
d.value = value;
return d;
}
// ... and ...
Object.defineProperty(obj, 'key', withValue('static'));
// if freeze is available, prevents adding or
// removing the object prototype properties
// (value, get, set, enumerable, writable, configurable)
(Object.freeze || Object)(Object.prototype);
If you want to see how to use the Object.defineProperty method with a binary-flags-like syntax, see additional examples.
When the property specified doesn't exist in the object, Object.defineProperty() creates a new property as described. Fields may be omitted from the descriptor, and default values for those fields are imputed. All of the Boolean-valued fields default to false. The value, get, and set fields default to {{jsxref("undefined")}}. A property which is defined without get/set/value/writable is called “generic” and is “typed” as a data descriptor.
var o = {}; // Creates a new object
// Example of an object property added with defineProperty with a data property descriptor
Object.defineProperty(o, 'a', {
value: 37,
writable: true,
enumerable: true,
configurable: true
});
// 'a' property exists in the o object and its value is 37
// Example of an object property added with defineProperty with an accessor property descriptor
var bValue = 38;
Object.defineProperty(o, 'b', {
get: function() { return bValue; },
set: function(newValue) { bValue = newValue; },
enumerable: true,
configurable: true
});
o.b; // 38
// 'b' property exists in the o object and its value is 38
// The value of o.b is now always identical to bValue, unless o.b is redefined
// You cannot try to mix both:
Object.defineProperty(o, 'conflict', {
value: 0x9f91102,
get: function() { return 0xdeadbeef; }
});
// throws a TypeError: value appears only in data descriptors, get appears only in accessor descriptors
When the property already exists, Object.defineProperty() attempts to modify the property according to the values in the descriptor and the object's current configuration. If the old descriptor had its configurable attribute set to false (the property is said to be “non-configurable”), then no attribute besides writable can be changed. In that case, it is also not possible to switch back and forth between the data and accessor property types.
If a property is non-configurable, its writable attribute can only be changed to false.
A {{jsxref("TypeError")}} is thrown when attempts are made to change non-configurable property attributes (besides the writable attribute) unless the current and new values are the same.
When the writable property attribute is set to false, the property is said to be “non-writable”. It cannot be reassigned.
var o = {}; // Creates a new object
Object.defineProperty(o, 'a', {
value: 37,
writable: false
});
console.log(o.a); // logs 37
o.a = 25; // No error thrown (it would throw in strict mode, even if the value had been the same)
console.log(o.a); // logs 37. The assignment didn't work.
As seen in the example, trying to write into the non-writable property doesn't change it but doesn't throw an error either.
The enumerable property attribute defines whether the property shows up in a {{jsxref("Statements/for...in", "for...in")}} loop and {{jsxref("Object.keys()")}} or not.
var o = {};
Object.defineProperty(o, 'a', { value: 1, enumerable: true });
Object.defineProperty(o, 'b', { value: 2, enumerable: false });
Object.defineProperty(o, 'c', { value: 3 }); // enumerable defaults to false
o.d = 4; // enumerable defaults to true when creating a property by setting it
for (var i in o) {
console.log(i);
}
// logs 'a' and 'd' (in undefined order)
Object.keys(o); // ['a', 'd']
o.propertyIsEnumerable('a'); // true
o.propertyIsEnumerable('b'); // false
o.propertyIsEnumerable('c'); // false
The configurable attribute controls at the same time whether the property can be deleted from the object and whether its attributes (other than writable) can be changed.
var o = {};
Object.defineProperty(o, 'a', {
get: function() { return 1; },
configurable: false
});
Object.defineProperty(o, 'a', { configurable: true }); // throws a TypeError
Object.defineProperty(o, 'a', { enumerable: true }); // throws a TypeError
Object.defineProperty(o, 'a', { set: function() {} }); // throws a TypeError (set was undefined previously)
Object.defineProperty(o, 'a', { get: function() { return 1; } }); // throws a TypeError (even though the new get does exactly the same thing)
Object.defineProperty(o, 'a', { value: 12 }); // throws a TypeError
console.log(o.a); // logs 1
delete o.a; // Nothing happens
console.log(o.a); // logs 1
If the configurable attribute of o.a had been true, none of the errors would be thrown and the property would be deleted at the end.
It's important to consider the way default values of attributes are applied. There is often a difference between simply using dot notation to assign a value and using Object.defineProperty(), as shown in the example below.
var o = {};
o.a = 1;
// is equivalent to:
Object.defineProperty(o, 'a', {
value: 1,
writable: true,
configurable: true,
enumerable: true
});
// On the other hand,
Object.defineProperty(o, 'a', { value: 1 });
// is equivalent to:
Object.defineProperty(o, 'a', {
value: 1,
writable: false,
configurable: false,
enumerable: false
});
Example below shows how to implement a self-archiving object. When temperature property is set, the archive array gets a log entry.
function Archiver() {
var temperature = null;
var archive = [];
Object.defineProperty(this, 'temperature', {
get: function() {
console.log('get!');
return temperature;
},
set: function(value) {
temperature = value;
archive.push({ val: temperature });
}
});
this.getArchive = function() { return archive; };
}
var arc = new Archiver();
arc.temperature; // 'get!'
arc.temperature = 11;
arc.temperature = 13;
arc.getArchive(); // [{ val: 11 }, { val: 13 }]
or
var pattern = {
get: function () {
return 'I always return this string, whatever you have assigned';
},
set: function () {
this.myname = 'this is my name string';
}
};
function TestDefineSetAndGet() {
Object.defineProperty(this, 'myproperty', pattern);
}
var instance = new TestDefineSetAndGet();
instance.myproperty = 'test';
console.log(instance.myproperty); // I always return this string, whatever you have assigned
console.log(instance.myname); // this is my name string
| Specification | Status | Comment |
|---|---|---|
| {{SpecName('ES5.1', '#sec-15.2.3.6', 'Object.defineProperty')}} | {{Spec2('ES5.1')}} | Initial definition. Implemented in JavaScript 1.8.5. |
| {{SpecName('ES6', '#sec-object.defineproperty', 'Object.defineProperty')}} | {{Spec2('ES6')}} | |
| {{SpecName('ESDraft', '#sec-object.defineproperty', 'Object.defineProperty')}} | {{Spec2('ESDraft')}} |
| Feature | Firefox (Gecko) | Chrome | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|
| Basic support | {{CompatGeckoDesktop("2")}} | {{CompatChrome("5")}} | {{CompatIE("9")}} [1] | {{CompatOpera("11.60")}} | {{CompatSafari("5.1")}} [2] |
| Feature | Firefox Mobile (Gecko) | Android | IE Mobile | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|
| Basic support | {{CompatGeckoMobile("2")}} | {{CompatVersionUnknown}} | {{CompatIE("9")}} | {{CompatOperaMobile("11.5")}} | {{CompatVersionUnknown}} |
[1] In Internet Explorer 8 only on DOM objects and with some non-standard behaviors.
[2] Also supported in Safari 5, but not on DOM objects.
length property of an Array objectIt is possible to redefine the {{jsxref("Array.length", "length")}} property of arrays, subject to the usual redefinition restrictions. (The {{jsxref("Array.length", "length")}} property is initially non-configurable, non-enumerable, and writable. Thus on an unaltered array it is possible to change the {{jsxref("Array.length", "length")}} property's value, or to make it non-writable. It is not allowed to change its enumerability or configurability, or if it is non-writable to change its value or writability.) However, not all browsers permit this redefinition.
Firefox 4 through 22 will throw a {{jsxref("TypeError")}} on any attempt whatsoever (whether permitted or not) to redefine the {{jsxref("Array.length", "length")}} property of an array.
Versions of Chrome which implement Object.defineProperty() in some circumstances ignore a length value different from the array's current {{jsxref("Array.length", "length")}} property. In some circumstances changing writability seems to silently not work (and not throw an exception). Also, relatedly, some array-mutating methods like {{jsxref("Array.prototype.push")}} don't respect a non-writable length.
Versions of Safari which implement Object.defineProperty() ignore a length value different from the array's current {{jsxref("Array.length", "length")}} property, and attempts to change writability execute without error but do not actually change the property's writability.
Only Internet Explorer 9 and later, and Firefox 23 and later, appear to fully and correctly implement redefinition of the {{jsxref("Array.length", "length")}} property of arrays. For now, don't rely on redefining the {{jsxref("Array.length", "length")}} property of an array to either work, or to work in a particular manner. And even when you can rely on it, there's really no good reason to do so.
Internet Explorer 8 implemented a Object.defineProperty() method that could only be used on DOM objects. A few things need to be noted:
Object.defineProperty() on native objects throws an error.Configurable, enumerable and writable attributes should all be set to true for data descriptor and true for configurable, false for enumerable for accessor descriptor.(?) Any attempt to provide other value(?) will result in an error being thrown.Object.defineProperty examples