Object.getOwnPropertyDescriptor Function (JavaScript)
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
Returns the definition of a data property or an accessor property.
Object.getOwnPropertyDescriptor(object, propertyname)
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.
