Export (0) Print
Expand All

Object.getOwnPropertyDescriptor Function (JavaScript)

Returns the definition of a data property or an accessor property.

Object.getOwnPropertyDescriptor(object, propertyname)

object

Required. The object that contains the property. This can be a native JavaScript object or a Document Object Model (DOM) object.

propertyname

Required. A string that contains the name of the property.

A JavaScript object that is a descriptor that provides a definition of the property. The definition can be for a data property or an accessor property.

You can use the Object.getOwnPropertyDescriptor function to obtain the definition of a property. The method returns a descriptor object that describes attributes of the property. The attributes of the descriptor object determine whether the property is a data property or an accessor property.

The Object.defineProperty Function (JavaScript) is used to add a data property or an accessor property to an object. A descriptor object is a parameter of the Object.defineProperty function.

Data Properties

A data property is a property that can store and retrieve a value. The descriptor object for a data property contains a value attribute, a writable attribute, or both.

The following table lists the attributes for a data property descriptor object.

Data descriptor attribute

Description

value

The current value of the property.

writable

true or false. If writable is set to true, the property value can be changed.

enumerable

true or false. If enumerable is set to true, the property can be enumerated by a for…in statement.

configurable

true or false. If configurable is set to true, property attributes can be changed, and the property can be deleted.

When the configurable attribute is false and writable is true, the value and writable attributes can be changed.

Accessor Properties

An accessor property calls a user-provided function every time that the property value is set or retrieved. The descriptor object for an accessor property contains a get attribute, a set attribute, or both.

The following table lists the attributes for an accessor property descriptor object.

Accessor descriptor attribute

Description

get

A function that returns the property value. The function has no parameters.

set

A function that has one parameter that contains the value to be assigned. The set accessor function is used to set the property value.

enumerable

true or false. If enumerable is set to true, the property can be enumerated by a for…in statement.

configurable

true or false. If configurable is set to true, property attributes can be changed, and the property can be deleted.

When a get accessor is not specified and an attempt is made to access the property value, the value undefined is returned. When a set accessor is not specified and an attempt is made to assign a value to the accessor property, nothing occurs.

The following example obtains a property descriptor from an object and uses the descriptor to modify the property attributes.

function modifyDataProperty() {
    // Create a user-defined object.
    // To instead use an existing DOM object, uncomment the line below.
    var obj = {};
    // var obj = window.document;

    // Add a data property by using the assignment operator.
    obj.newDataProperty = "abc";

    // Get a descriptor that contains the property attributes.
    var descriptor = Object.getOwnPropertyDescriptor(obj, "newDataProperty");

    // Change a property attribute.
    descriptor.writable = false;
    Object.defineProperty(obj, "newDataProperty", descriptor);
}

To obtain and list the property attributes, you can add the following code to this example.

    // Get the descriptor from the object.
    var desc2 = Object.getOwnPropertyDescriptor(obj, "newDataProperty");

    // List the descriptor attributes.
    for (var prop in desc2) {
        document.write(prop + ': ' + desc2[prop]);
        document.write("<br />");
    }

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

The following example adds an accessor property and then obtains and displays the property attributes.

function showAccessorProperty() {
    // Create a user-defined object.
    // To instead use an existing DOM object, uncomment the line below.
    var obj = {};
    // var obj = window.document;

    // Add an accessor property.
    addAccessorProperty(obj);

    // Get the descriptor from the object's property.
    var descriptor = Object.getOwnPropertyDescriptor(obj, "newAccessorProperty");

    // List the descriptor properties, which are the attributes
    // of newAccessorProperty.
    for (var prop in descriptor) {
        document.write(prop + ': ' + descriptor[prop]);
        document.write("<br />");
    }

    // Output:
    //  get: function () { return this.newaccpropvalue; }
    //  set: function (x) { this.newaccpropvalue = x; }
    //  configurable: true
    //  enumerable: true
}

function addAccessorProperty(obj) {
    // Create the descriptor object for a new accessor property.
    var descriptor =
    {
        set: function (x) {
            this.newaccpropvalue = x;
        },
        get: function () {
            return this.newaccpropvalue;
        },
        enumerable: true,
        configurable: true
    };

    // Add an accessor property to the object.
    Object.defineProperty(obj, "newAccessorProperty", descriptor);
}

The following example demonstrates how to customize built-in DOM properties. It supplements the inner functionality of the built-in innerHTML property of HTML elements. It uses the Object.getOwnPropertyDescriptor function to cache the original property descriptor before customizing the property.

function ModifyDOMPrototype() {
    // Get a descriptor that contains the original innerHTML property
    // attributes. This descriptor is used by the revised set accessor
    // below.
    var originalDescriptor = Object.getOwnPropertyDescriptor(Element.prototype, "innerHTML");

    // Create a descriptor that contains property attribute changes.
    // This descriptor contains only a revised set accessor.
    var descriptorWithChanges =
    {
        set: function (htmlContent) {
            // To do: Add new set accessor code.
            // Display an alert stating that the set accessor was called.
            alert("Set accessor called for " + this.id);

            // Call the original set accessor when done.
            originalDescriptor.set.call(this, htmlContent);
        }
    };

    // Apply property changes to the Element prototype.
    // This revises the innerHTML set accessor for all
    // DOM element instances.
    // The get accessor continues to work as before.
    Object.defineProperty(Element.prototype, "innerHTML", descriptorWithChanges);

    // Get the element from the HTML body.
    var theElement = document.getElementById("TheDiv");

    alert("Original innerHTML: " + theElement.innerHTML);

    // Change the innerHTML value. This causes the revised set accessor to be called.
    theElement.innerHTML = "Revised HTML text.";

    alert("Revised innerHTML: " + theElement.innerHTML);
}

To run the example, you can add the following to the body section of the HTML.

<div id="TheDiv">This is text in an HTML division.</div>

Following is the output.

// Alert output:
//  Original innerHTML: This is text in an HTML division.
//  Set accessor called for TheDiv
//  Revised innerHTML: Revised HTML text.

// Page output:
//  Revised HTML text.

Internet Explorer 9 standards mode supports all described 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.

Community Additions

Show:
© 2014 Microsoft