diff options
Diffstat (limited to 'files/es/web/javascript/reference/global_objects/object/defineproperty/index.html')
-rw-r--r-- | files/es/web/javascript/reference/global_objects/object/defineproperty/index.html | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/files/es/web/javascript/reference/global_objects/object/defineproperty/index.html b/files/es/web/javascript/reference/global_objects/object/defineproperty/index.html new file mode 100644 index 0000000000..f971d5a131 --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/object/defineproperty/index.html @@ -0,0 +1,419 @@ +--- +title: Object.defineProperty() +slug: Web/JavaScript/Referencia/Objetos_globales/Object/defineProperty +tags: + - ECMAScript5 + - JavaScript + - JavaScript 1.8.5 + - Método(2) + - Objeto +translation_of: Web/JavaScript/Reference/Global_Objects/Object/defineProperty +--- +<div>{{JSRef("Global_Objects", "Object")}}</div> + +<h2 id="summary" name="summary">Resumen</h2> + +<p>El método estático <code><strong>Object.defineProperty()</strong></code> define una nueva propiedad sobre un objeto, o modifica una ya existente, y devuelve el objeto modificado.</p> + +<div class="note"> +<p><strong>Nota:</strong> Ud. puede llamar a este método directamente mediante el constructor {{jsxref("Object")}} en vez de crear una instancia del tipo <code>Object</code>.</p> +</div> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox"><code>Object.defineProperty(<var>obj</var>, <var>prop</var>, <var>descriptor</var>)</code></pre> + +<h3 id="Parameters" name="Parameters">Parámetros</h3> + +<dl> + <dt><code>obj</code></dt> + <dd>El objeto sobre el cual se define la propiedad.</dd> + <dt><code>prop</code></dt> + <dd>El nombre de la propiedad a ser definida o modificada.</dd> + <dt><code>descriptor</code></dt> + <dd>El descriptor de la propiedad que está siendo definida o modificada.</dd> +</dl> + +<h2 id="Description" name="Description">Descripción</h2> + +<p>Este método permite añadir o modificar una propiedad en un objeto.</p> + +<p>La adición normal de una propiedad a través de la asignación crea propiedades que aparecen durante la enumeración de propiedades en el bucle ({{jsxref("Sentencias/for...in", "for...in")}} o el método {{jsxref("Object.keys")}}), cuyos valores pueden modificarse y pudiendo incluso eliminar la propiedad del objeto mediante el método {{jsxref("Operadores/delete", "delete")}}.</p> + +<p>Este método nos permite modificar el comportamiento por defecto de las propiedades. Es decir, nos permite definir una propiedad como no enumerable, no modificable o incluso evitar que pueda ser eliminada del objeto.</p> + +<p>Existen dos tipos de descriptores: De datos y de acceso. Un <em><dfn>descriptor de datos</dfn></em> define una propiedad que tiene un valor, el cual puede ser o no modificado. Un descriptor de acceso define una propiedad mediante un par de funciones getter-setter que describe como se obtiene o se modifica el contenido de dicha propiedad. Un descriptor debe de ser de uno de estos dos tipos; no puede ser ambos.</p> + +<p>Ambos tipos de descriptores son objetos y comparten las siguientes claves opcionales:</p> + +<dl> + <dt><code>configurable</code></dt> + <dd><code>true</code> si y solo si el tipo de descriptor de propiedad puede modificarse y si la propiedad puede ser eliminada del correspondiente objeto.<br> + <strong>Por defecto es <code>false</code>.</strong></dd> + <dt><code>enumerable</code></dt> + <dd><code>true</code> si y solo si dicha propiedad se muestra durante la enumeración de las propiedades del objeto correspondiente.<br> + <strong>Por defecto es <code>false</code>.</strong></dd> +</dl> + +<p>Un descriptor de datos tiene además las siguientes claves opcionales:</p> + +<dl> + <dt><code>value</code></dt> + <dd>El valor asociado a la propiedad. Puede ser cualquier tipo valido de JavaScript (number, object, function, etc).<br> + <strong>Por defecto es {{jsxref("Objetos_Globales/undefined", "undefined")}}.</strong></dd> + <dt><code>writable</code></dt> + <dd><code>true</code> Indica si el valor de la propiedad puede modificarse con el {{jsxref("Operators/Assignment_Operators", "operador de asignación", "", 1)}}.<br> + <strong>Defaults to <code>false</code>.</strong></dd> +</dl> + +<p>Un descriptor de acceso además tiene las siguientes claves opcionales:</p> + +<dl> + <dt><code>get</code></dt> + <dd>Una función cuyo valor retornado será el que se use como valor de la propiedad.<br> + <strong>Defaults to {{jsxref("Objetos_Globales/undefined", "undefined")}}.</strong></dd> + <dt><code>set</code></dt> + <dd>Una función que recibe como único argumento el nuevo valor que se desea asignar a la propiedad y que devuelve el valor que se almacenará finalmente en el objeto.<br> + <strong>Defaults to {{jsxref("Objetos_Globales/undefined", "undefined")}}.</strong></dd> +</dl> + +<p>Hay que tener en cuenta que estas opciones también pueden heredarse; es decir, las opciones de la propiedad se han podido establecer en el prototipo de una clase de la que hereda el objeto. De modo que si queremos asegurarnos unos valores por defecto tenemos tres opciones: fijar el {{jsxref("Object.prototype")}} con {{jsxref("Object.freeze")}}, definir todas las opciones explicitamente, o establecer a {{jsxref("Objetos_Globales/null", "null")}} la propiedad {{jsxref("Object.prototype.__proto__", "__proto__")}}.</p> + +<pre class="brush: js">// Usando __proto__ +Object.defineProperty(obj, 'key', { + __proto__: null, // no aceptar propiedades heredadas + value: 'static' // no enumerable + // no configurable + // no modificable + // como opciones por defecto +}); + +// Definiendo todo explicitamente +Object.defineProperty(obj, 'key', { + enumerable: false, + configurable: false, + writable: false, + value: 'static' +}); + +// Reciclando el mismo objeto +function withValue(value) { + var d = withValue.d || ( + withValue.d = { + enumerable: false, + writable: false, + configurable: false, + value: null + } + ); + d.value = value; + return d; +} +// ... y ... +Object.defineProperty(obj, 'key', withValue('static')); + +// Si está disponible freeze, previene añadir o eliminar +//del prototipo del objeto las propiedades +// (value, get, set, enumerable, writable, configurable) +(Object.freeze || Object)(Object.prototype); +</pre> + +<h2 id="Examples" name="Examples">Ejemplos</h2> + +<p>Si quiere ver algunos ejemplos de utilización del método <code>Object.defineProperty</code> con una sintaxis tipo <em>binary-flags</em>, vea <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty/Additional_examples">ejemplos adicionales</a>.</p> + +<h3 id="Example:_Creating_a_property" name="Example:_Creating_a_property">Ejemplo: Creando una propiedad</h3> + +<p>Cuando la propiedad especificada no existe en el objeto<code>, Object.defineProperty()</code> crea una nueva. En el descriptor pueden omitirse campos, a los cuales se les asignará el valor por defecto. A todos los que sean de tipo Booleano se les asignará el valor falso. Los campos <code>value</code>, <code>get</code> y <code>set</code> se establecerán por defecto a {{jsxref("Objetos_Globales/undefined", "undefined")}}. Una propiedad definida sin indicar <code>get</code>/<code>set</code>/<code>value</code>/<code>writable</code> es denominada “genérica” y “tipificada” como un descriptor de datos.</p> + +<pre class="brush: js">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 +</pre> + +<h3 id="Example:_Modifying_a_property" name="Example:_Modifying_a_property">Ejemplo: Modificando una propiedad</h3> + +<p>Cuando la propiedad realmente existe, <code>Object.defineProperty()</code> intenta modificar la propiedad de acuerdo a los valores en la descripción y la configuración actual del objeto. Si la descripción antigüa tenía su atributo de configuración establecido en <code>false</code> (la propiedad se dice "sin capacidad de configuración"), entonces ningún atributo además de los que tienen capacidad de escritura pueden ser cambiados. En ese caso, no es posible cambiar hacía atras o hacía delante entre datos y métodos de acceso de tipos de propiedades.</p> + +<p>Si una propiedad no tiene capacidad de configuración, su atributo <code>writabble</code> solo puede ser cambiada to <code>false</code>.</p> + +<p>Un {{jsxref("Global_Objects/TypeError", "TypeError")}} es arrojado cuando se intenta cambiar las propiedades de atributos sin capacidad de configuración (adeḿas del atributo <code>writable</code>) a menos que el valor actual y el valor nuevo sean los mismos.</p> + +<h4 id="Writable_attribute" name="Writable_attribute">Atributo writable</h4> + +<p>Cuando la propiedad de un atributo <code>writable</code> es establecido to <code>false</code>, la propiedad se dice esta "sin capacidad de escritura". No puede ser reasignada.</p> + +<pre class="brush: js">var o = {}; // Crea un objeto nuevo + +Object.defineProperty(o, 'a', { + value: 37, + writable: false +}); + +console.log(o.a); // logs 37 +o.a = 25; // Ningún error arrojado (lo tiraría en modo estricto, aún si el valor fuera el mismo) +console.log(o.a); // muestra 37. La asignación no funcionó +</pre> + +<p>Como es visto en el ejemplo anterior, intentar escribir en una propiedad "sin capacidad de escritura" no la cambia pero sí arroja un error.</p> + +<h4 id="Enumerable_attribute" name="Enumerable_attribute">Atributo enumerable</h4> + +<p>El atributo de la propiedad <code>enumerable</code> se define si la propiedad aparece en un ciclo {{jsxref("Statements/for...in", "for...in")}} y {{jsxref("Object.keys()")}} o no.</p> + +<pre class="brush: js">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 +</pre> + +<h4 id="Configurable_attribute" name="Configurable_attribute">Atributo configurable</h4> + +<p>El atributo <code>configurable</code> define si la propiedad puede ser eliminada del objeto, y si sus atributos (excepto <code>writable</code>) pueden ser modificados</p> + +<pre class="brush: js">var o = {}; +Object.defineProperty(o, 'a', { + get: function() { return 1; }, + configurable: false +}); + +Object.defineProperty(o, 'a', { configurable: true }); // arroja TypeError +Object.defineProperty(o, 'a', { enumerable: true }); // arroja TypeError +Object.defineProperty(o, 'a', { set: function() {} }); // arroja TypeError (set estaba definido como undefined) +Object.defineProperty(o, 'a', { get: function() { return 1; } }); // arroja TypeError (incluso aunque los get hacen lo mismo) +Object.defineProperty(o, 'a', { value: 12 }); // arroja TypeError + +console.log(o.a); // logs 1 +delete o.a; // No hace nada +console.log(o.a); // logs 1 +</pre> + +<p>Si <code>o.a</code> tuviese <code>configurable</code> a <code>true</code>, no se habrían arrojado errores y la propiedad habría sido eliminada. </p> + +<h3 id="Example:_Adding_properties_and_default_values" name="Example:_Adding_properties_and_default_values">Ejemplo: Añadiendo propiedades y valores por defecto</h3> + +<p>Es importante tener en cuenta la forma en la se aplican los valores por defecto de los atributos. Suele haber diferencias entre simplemente usar la notación con '.' y usar <code>Object.defineProperty()</code>, como se muestra en el siguiente ejemplo:</p> + +<pre class="brush: js">var o = {}; + +o.a = 1; +// es equivalente a : +Object.defineProperty(o, 'a', { + value: 1, + writable: true, + configurable: true, + enumerable: true +}); + + +// Sin embargo, +Object.defineProperty(o, 'a', { value: 1 }); +// es equivalente a : +Object.defineProperty(o, 'a', { + value: 1, + writable: false, + configurable: false, + enumerable: false +}); +</pre> + +<h3 id="Example:_Custom_setters_and_getters" name="Example:_Custom_setters_and_getters">Ejemplo: Setters y Getters a medida</h3> + +<p>Example below shows how to implement a self-archiving object. When <code>temperature</code> property is set, the <code>archive</code> array gets a log entry.</p> + +<pre class="brush: js">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 }] +</pre> + +<p>or</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">var</span> pattern <span class="operator token">=</span> <span class="punctuation token">{</span> + <span class="keyword token">get</span><span class="punctuation token">:</span> <span class="keyword token">function</span> <span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">return</span> <span class="string token">'I always return this string, whatever you have assigned'</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="keyword token">set</span><span class="punctuation token">:</span> <span class="keyword token">function</span> <span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">this</span><span class="punctuation token">.</span>myname <span class="operator token">=</span> <span class="string token">'this is my name string'</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span><span class="punctuation token">;</span> + + +<span class="keyword token">function</span> <span class="function token">TestDefineSetAndGet</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + Object<span class="punctuation token">.</span><span class="function token">defineProperty</span><span class="punctuation token">(</span><span class="keyword token">this</span><span class="punctuation token">,</span> <span class="string token">'myproperty'</span><span class="punctuation token">,</span> pattern<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + + +<span class="keyword token">var</span> instance <span class="operator token">=</span> <span class="keyword token">new</span> <span class="class-name token">TestDefineSetAndGet</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +instance<span class="punctuation token">.</span>myproperty <span class="operator token">=</span> <span class="string token">'test'</span><span class="punctuation token">;</span> +console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>instance<span class="punctuation token">.</span>myproperty<span class="punctuation token">)</span><span class="punctuation token">;</span> <span class="comment token">// I always return this string, whatever you have assigned</span> + +console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>instance<span class="punctuation token">.</span>myname<span class="punctuation token">)</span><span class="punctuation token">;</span> <span class="comment token">// this is my name string</span></code></pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('ES5.1', '#sec-15.2.3.6', 'Object.defineProperty')}}</td> + <td>{{Spec2('ES5.1')}}</td> + <td>Initial definition. Implemented in JavaScript 1.8.5.</td> + </tr> + <tr> + <td>{{SpecName('ES6', '#sec-object.defineproperty', 'Object.defineProperty')}}</td> + <td>{{Spec2('ES6')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_con_navegadores">Compatibilidad con navegadores</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Característica</th> + <th>Firefox (Gecko)</th> + <th>Chrome</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Soporte Básico</td> + <td>{{CompatGeckoDesktop("2")}}</td> + <td>{{CompatChrome("5")}} (versiones previas sin testear)</td> + <td>{{CompatIE("9")}} ({{CompatIE("8")}}, pero solo con objetos DOM y con muchos comportamientos no estándares <a href="#Internet_Explorer_8_specific_notes">See below</a>.)</td> + <td>{{CompatOpera("11.60")}}</td> + <td>{{CompatSafari("5.1")}} ({{CompatSafari("5")}}, but not on DOM objects)</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Característica</th> + <th>Firefox Mobile (Gecko)</th> + <th>Android</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Soporte Básico</td> + <td>{{CompatGeckoMobile("2")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatIE("9")}} and above</td> + <td>{{CompatOperaMobile("11.50")}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>Based on <a class="external" href="http://kangax.github.com/es5-compat-table/">Kangax's compat tables</a>.</p> + +<h3 id="Redefining_the_length_property_of_an_Array_object" name="Redefining_the_length_property_of_an_Array_object">Redefining the <code>length</code> property of an <code>Array</code> object</h3> + +<p>It 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.</p> + +<p>Firefox 4 through 22 will throw a {{jsxref("Global_Objects/TypeError", "TypeError")}} on any attempt whatsoever (whether permitted or not) to redefine the {{jsxref("Array.length", "length")}} property of an array.</p> + +<p>Versions of Chrome which implement <code>Object.defineProperty()</code> 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.</p> + +<p>Versions of Safari which implement <code>Object.defineProperty()</code> ignore a <code>length</code> 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.</p> + +<p>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 <em>can</em> rely on it, <a href="http://whereswalden.com/2013/08/05/new-in-firefox-23-the-length-property-of-an-array-can-be-made-non-writable-but-you-shouldnt-do-it/">there's really no good reason to do so</a>.</p> + +<h3 id="Particularidades_de_Internet_Explorer_8">Particularidades de Internet Explorer 8</h3> + +<p>El método <code>Object.defineProperty()</code> de Internet Explorer <a href="http://msdn.microsoft.com/en-us/library/dd229916%28VS.85%29.aspx">sólo puede ser usado en objetos del DOM.</a> Algunas explicaciones al respecto:</p> + +<ul> + <li>Intentar usar <code>Object.defineProperty()</code> en objetos nativos produce un error.</li> + <li>Hay que definir un valor para todos los atributos de una propiedad: <code>true, true, true</code> para descriptores de datos y <code>true</code> para configurables, <code>false</code> para el descriptor de acceso <code>enumerable</code>.(?) Cualquier intento de proporcionar otro valor(?) lanzará un error.</li> + <li>Para reconfirurar una propiedad primero hay que eliminarla. Si no se elimina, la propiedad no cambia aunque se intente modificar.</li> +</ul> + +<h2 id="See_also" name="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Enumerability_and_ownership_of_properties">Enumerability and ownership of properties</a></li> + <li>{{jsxref("Object.defineProperties()")}}</li> + <li>{{jsxref("Object.propertyIsEnumerable()")}}</li> + <li>{{jsxref("Object.getOwnPropertyDescriptor()")}}</li> + <li>{{jsxref("Object.prototype.watch()")}}</li> + <li>{{jsxref("Object.prototype.unwatch()")}}</li> + <li>{{jsxref("Operators/get", "get")}}</li> + <li>{{jsxref("Operators/set", "set")}}</li> + <li>{{jsxref("Object.create()")}}</li> + <li><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty/Additional_examples">Additional <code>Object.defineProperty</code> examples</a></li> +</ul> |