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

CKTIS / JavaScript

Object.defineProperty: descritor preciso de uma propriedade

Object.defineProperty define ou altera uma propriedade própria através de um descritor explícito de dados ou accessor.

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

Sintaxe

Object.defineProperty(obj, key, descriptor)

Object.defineProperty(obj, key, descriptor) exige um objeto real como obj e não encapsula primitivas. key passa por ToPropertyKey, tornando-se texto ou símbolo. descriptor é lido por ToPropertyDescriptor e o método devolve o mesmo objeto alvo.

Um descritor de dados usa value e writable, enquanto um descritor accessor usa get e set; misturar campos dos dois tipos lança TypeError. Ao criar uma nova propriedade, writable, enumerable e configurable ausentes tornam-se false, e value, get e set ausentes significam undefined; ao atualizar uma propriedade existente, os campos omitidos deixam inalterados os atributos atuais. Getter e setter têm de ser invocáveis ou undefined.

O método existe desde ECMAScript 5. DefinePropertyOrThrow lança TypeError ao adicionar uma nova propriedade a um objeto não extensível, quando a alteração viola as regras de uma propriedade não configurável ou quando um Proxy quebra invariantes. Uma redefinição compatível de uma propriedade existente pode ter êxito mesmo num objeto não extensível. Ao contrário de uma atribuição, controla atributos sem invocar um setter herdado, embora ler o descritor e traps Proxy possa executar código e lançar.

Exemplos

const account = {};
const same = Object.defineProperty(account, "balance", {
  value: 10, writable: false, enumerable: true, configurable: false
});
let reads = 0;
Object.defineProperty(account, "label", {
  get() { return `#${++reads}`; }, configurable: true
});
console.log(same === account, Object.keys(account).join(","));
console.log(account.balance, account.label, account.label);
const balance = Object.getOwnPropertyDescriptor(account, "balance");
const label = Object.getOwnPropertyDescriptor(account, "label");
console.log(balance.writable, balance.configurable, label.set);
try { Object.defineProperty(account, "balance", { value: 11 }); }
catch (error) { console.log(error.name, account.balance); }
try { Object.defineProperty({}, "x", { value: 1, get() {} }); }
catch (error) { console.log(error.name); }

Resultado

true balance
10 #1 #2
false false undefined
TypeError 10
TypeError

O exemplo define uma propriedade de dados e um getter, inspeciona atributos e testa dois TypeError.

Fontes