Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Object.defineProperties: vários descritores de uma vez

Object.defineProperties define várias propriedades com descritores completos depois de recolher e validar todo o mapa.

Versão: ECMAScript 5 onward; example target: Node.js 24.22.2

Sintaxe

Object.defineProperties(obj, properties)

Object.defineProperties(obj, properties) exige que obj seja um objeto e não encapsula primitivas. properties passa por ToObject, pelo que null e undefined lançam TypeError. O método guarda uma fotografia das chaves próprias de texto e símbolo do mapa e inclui apenas as cujo descritor próprio atual é enumerável.

Primeiro obtém cada valor selecionado e converte-o com ToPropertyDescriptor; só depois de recolher com êxito todos os descritores começa a definir propriedades no alvo. Um descritor inválido ou getter que lance nesta fase deixa, portanto, o alvo intacto. A fase de definição é sequencial, não transacional: se uma definição posterior falhar, as anteriores podem permanecer.

O método devolve o mesmo obj e existe desde ECMAScript 5. Ao criar uma nova propriedade, writable, enumerable e configurable omitidos tornam-se false, enquanto value, get e set omitidos tornam-se undefined; ao atualizar uma propriedade existente, os campos omitidos ficam inalterados. value/writable não podem ser misturados com get/set, e um accessor tem de ser invocável ou undefined. Getters e traps Proxy no mapa ou alvo podem executar código e lançar exceções.

Exemplos

const token = Symbol("token");
const target = {};
Object.defineProperties(target, {
  visible: { value: 3, enumerable: true },
  doubled: { get() { return this.visible * 2; }, enumerable: true },
  [token]: { value: "ok" }
});
console.log(Object.keys(target).join(","), target.doubled, target[token]);
console.log(Object.getOwnPropertyDescriptor(target, "visible").writable);
const untouched = {};
try {
  Object.defineProperties(untouched, {
    first: { value: 1 },
    bad: { get: 1 }
  });
} catch (error) { console.log(error.name, Object.hasOwn(untouched, "first")); }
const partial = {};
Object.defineProperty(partial, "locked", { value: 1 });
try {
  Object.defineProperties(partial, {
    added: { value: 2 },
    locked: { value: 3 }
  });
} catch (error) { console.log(error.name, partial.added, partial.locked); }

Resultado

visible,doubled 6 ok
false
TypeError false
TypeError 2 1

O exemplo mostra símbolos, valores restritivos, validação prévia e uma alteração parcial ao definir.

Fontes