Export (0) Print
Expand All

Object.defineProperty Function (JavaScript)

Adds a property to an object, or modifies attributes of an existing property.

Object.defineProperty(object, propertyname, descriptor)

object

Required. The object on which to add or modify the property. This can be a native JavaScript object (that is, a user-defined object or a built in object) or a DOM object.

propertyname

Required. A string that contains the property name.

descriptor

Required. A descriptor for the property. It can be for a data property or an accessor property.

The modified object.

You can use the Object.defineProperty function to do the following:

  • Add a new property to an object. This occurs when the object does not have the specified property name.

  • Modify attributes of an existing property. This occurs when the object already has the specified property name.

The property definition is provided in a descriptor object, which describes the attributes of a data property or an accessor property. The descriptor object is a parameter of the Object.defineProperty function.

To add multiple properties to an object, or to modify multiple existing properties, you can use the Object.defineProperties Function (JavaScript).

A TypeError exception is thrown if any one of the following conditions is true:

  • The object argument is not an object.

  • The object is not extensible and the specified property name does not exist..

  • The descriptor has a value or writable attribute, and has a get or set attribute.

  • The descriptor has a get or set attribute that is not a function or undefined.

  • The specified property name already exists, the existing property has a configurable attribute of false, and the descriptor contains one or more attributes that are different from those in the existing property. However, when the existing property has a configurable attribute of false and a writable attribute of true, it is permitted for the value or writable attribute to be different.

In the following example, the Object.defineProperty function adds a data property to a user-defined object. To instead add the property to an existing DOM object, uncomment the var = window.document line.

var newLine = "<br />";

// Create a user-defined object.
var obj = {};

// Add a data property to the object.
Object.defineProperty(obj, "newDataProperty", {
    value: 101,
    writable: true,
    enumerable: true,
    configurable: true
});

// Set the property value.
obj.newDataProperty = 102;
document.write("Property value: " + obj.newDataProperty + newLine);

// Output:
// Property value: 102

To list the object properties, add the following code to this example.

var names = Object.getOwnPropertyNames(obj);
for (var i = 0; i < names.length; i++) {
    var prop = names[i];

    document.write(prop + ': ' + obj[prop]);
    document.write(newLine);
}

// Output:
//  newDataProperty: 102

To modify a property attribute for the object, add the following code to the addDataProperty function shown earlier. The descriptor parameter contains only a writable attribute. The other data property attributes remain the same.

// Modify the writable attribute of the property.
Object.defineProperty(obj, "newDataProperty", { writable: false });

// List the property attributes by using a descriptor.
// Get the descriptor with Object.getOwnPropertyDescriptor.
var descriptor = Object.getOwnPropertyDescriptor(obj, "newDataProperty");
for (var prop in descriptor) {
    document.write(prop + ': ' + descriptor[prop]);
    document.write(newLine);
}

// Output
// writable: false
// value: 102
// configurable: true
// enumerable: true

In the following example, the Object.defineProperty function adds an accessor property to a user-defined object.

var newLine = "<br />";

// Create a user-defined object.
var obj = {};

// Add an accessor property to the object.
Object.defineProperty(obj, "newAccessorProperty", {
    set: function (x) {
        document.write("in property set accessor" + newLine);
        this.newaccpropvalue = x;
    },
    get: function () {
        document.write("in property get accessor" + newLine);
        return this.newaccpropvalue;
    },
    enumerable: true,
    configurable: true
});

// Set the property value.
obj.newAccessorProperty = 30;
document.write("Property value: " + obj.newAccessorProperty + newLine);

// Output:
// in property set accessor
// in property get accessor
// Property value: 30

To list the object properties, add the following code to this example.

var names = Object.getOwnPropertyNames(obj);
for (var i = 0; i < names.length; i++) {
    var prop = names[i];

    document.write(prop + ': ' + obj[prop]);
    document.write(newLine);
}
// Output:
// in property get accessor
// newAccessorProperty: 30

To modify a property attribute for the object, add the following code to the code shown earlier. The descriptor parameter contains only a get accessor definition. The other property attributes remain the same.

// Modify the get accessor.
Object.defineProperty(obj, "newAccessorProperty", {
    get: function () { return this.newaccpropvalue; }
});

// List the property attributes by using a descriptor.
// Get the descriptor with Object.getOwnPropertyDescriptor.
var descriptor = Object.getOwnPropertyDescriptor(obj, "newAccessorProperty");
for (var prop in descriptor) {
    document.write(prop + ': ' + descriptor[prop]);
    document.write(newLine);
}

// Output:
// get: function () { return this.newaccpropvalue; }
// set: function (x) { document.write("in property set accessor" + newLine); this.newaccpropvalue = x; }
// configurable: true
// enumerable: true

The following example demonstrates how to customize built-in DOM properties by using the Object.getOwnPropertyDescriptor function to get and modify the property's property descriptor. For this example, there must by a DIV element with an ID of "div".

// Get the querySelector property descriptor.
var descriptor = Object.getOwnPropertyDescriptor(Element.prototype, "querySelector");

// Make the property read-only.
descriptor.value = "query";
descriptor.writable = false;
// Apply the changes to the Element prototype.
Object.defineProperty(Element.prototype, "querySelector", descriptor);

// Get a DOM element from the HTML body.
var elem = document.getElementById("div");

// Attempt to change the value. This causes the revised value attribute to be called.
elem.querySelector = "anotherQuery";
document.write(elem.querySelector);

// Output:
// query

Internet Explorer 9 standards mode and Internet Explorer 10 standards mode, as well as Windows Store apps, support all features.

Internet Explorer 8 standards mode supports DOM objects but not user-defined objects. The enumerable and configurable attributes can be specified, but they are not used.

Show:
© 2014 Microsoft