Object.defineProperty()

Esta traducción está incompleta. Por favor, ayuda a traducir este artículo del inglés.

Resumen

El  método Object.defineProperty() define una nueva propiedad sobre un objeto, o modifica una ya existente, y devuelve el objeto modificado.

Sintaxis

Object.defineProperty(obj, prop, descriptor)

Parámetros

obj
El objeto sobre el cual se define la propiedad.
prop
El nombre de la propiedad a ser definida o modificada.
descriptor
El descriptor de la propiedad que está siendo definida o modificada.

Descripción

Este método permite añadir o modificar una propiedad en un objeto.

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 (for...in o el método Object.keys), cuyos valores pueden modificarse y pudiendo incluso eliminar la propiedad del objeto mediante el método delete.

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.

Existen dos tipos de desciptores: De datos y de acceso.  Un descriptor de datos 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.

Ambos tipos de descriptores son objetos y comparten las siguientes claves opcionales:

configurable
true si y solo si el tipo de descriptor de propiedad puede modificarse y si la propiedad puede ser eliminada del correspondiente objeto.
Por defecto es false.
enumerable
true si y solo si dicha propiedad se muestra durante la enumeración de las propiedades del objeto correspondiente.
Por defecto es false.

Un descriptor de datos tiene además las siguientes claves opcionales:

value
El valor asociado a la propiedad. Puede ser cualquier tipo valido de JavaScript  (number, object, function, etc).
Por defecto es undefined.
writable
true Indica si el valor de la propiedad puede modificarse con el  operador de asignación.
Defaults to false.

Un descriptor de acceso además tiene las siguientes claves opcionales:

get
Una función cuyo valor retornado será el que se use como valor de la propiedad.
Defaults to undefined.
set
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.
Defaults to undefined.

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 Object.prototype con Object.freeze, definir todas las opciones explicitamente, o establecer a null la propiedad __proto__.

// 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);

Ejemplos

Si quiere ver algunos ejemplos de utilización del método Object.defineProperty con una sintaxis tipo binary-flags, vea ejemplos adicionales.

Ejemplo: Creando una propiedad

Cuando la propiedad especificada no existe en el objeto, Object.defineProperty() 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 value, get y set se establecerán por defecto a undefined. Una propiedad definida sin indicar  get/set/value/writable es denominada “genérica” y  “tipificada” como un descriptor de datos.

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

Ejemplo: Modificando una propiedad

Cuando la propiedad realmente existe, Object.defineProperty() 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 false (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.

Si una propiedad no tiene capacidad de configuración, su atributo writabble solo puede ser cambiada to false.

Un TypeError es arrojado cuando se intenta cambiar las propiedades de atributos sin capacidad de configuración (adeḿas del atributo writable) a menos que el valor actual y el valor nuevo sean los mismos.

Atributo writable

Cuando la propiedad de un atributo writable es establecido to false, la propiedad se dice esta "sin capacidad de escritura". No puede ser reasignada.

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ó

Como es visto en el ejemplo anterior, intentar escribir en una propiedad "sin capacidad de  escritura" no la cambia pero sí arroja un error.

Atributo enumerable

El atributo de la propiedad enumerable se define si la propiedad aparece en un ciclo for...inObject.keys() o no.

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

Atributo configurable

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.

Example: Adding properties and default values

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: Custom Setters and Getters

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 }]

Especificaciones

Specification Status Comment
ECMAScript 5.1 (ECMA-262)
The definition of 'Object.defineProperty' in that specification.
Standard Initial definition. Implemented in JavaScript 1.8.5.
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Object.defineProperty' in that specification.
Standard  

Compatibilidad con navegadores

Característica Firefox (Gecko) Chrome Internet Explorer Opera Safari
Soporte Básico 4.0 (2) 5 (versiones previas sin testear) 9 (8, pero solo con objetos DOM y con muchos comportamientos no estándares  See below.) 11.60 5.1 (5, but not on DOM objects)
Característica Firefox Mobile (Gecko) Android IE Mobile Opera Mobile Safari Mobile
Soporte Básico 4.0 (2) (Yes) 9 and above 11.50 (Yes)

Based on Kangax's compat tables.

Redefining the length property of an Array object

It is possible to redefine the length property of arrays, subject to the usual redefinition restrictions. (The length property is initially non-configurable, non-enumerable, and writable. Thus on an unaltered array it is possible to change the 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 TypeError on any attempt whatsoever (whether permitted or not) to redefine the 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 length property. In some circumstances changing writability seems to silently not work (and not throw an exception). Also, relatedly, some array-mutating methods like 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 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 length property of arrays. For now, don't rely on redefining the 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 specific notes

Internet Explorer 8 implemented a Object.defineProperty() method that could only be used on DOM objects. A few things need to be noted:

  • Trying to use Object.defineProperty() on native objects throws an error.
  • Property attributes must be set to some values. true, true, 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.
  • Reconfiguring a property requires first deleting the property. If the property isn't deleted, it stays as it was before the reconfiguration attempt.

See also

Etiquetas y colaboradores del documento

 Colaboradores en esta página: mishelashala, victorgavilan, Siro_Diaz
 Última actualización por: mishelashala,