English 中文 العربية 日本語 Português

@decorator Decoradores

Última atualização: 2026-10-22

@decorator Decoradores

Um decorador é uma sintaxe especial (@name) colocada antes de classes, métodos, propriedades ou parâmetros: uma função de empacotamento que anexa comportamento (log, validação, injeção de dependência) a uma classe sem tocar no código dela. Decoradores ainda são experimentais no TypeScript e exigem experimentalDecorators no tsconfig; frameworks como NestJS e TypeORM dependem fortemente deles, o que os torna leitura obrigatória para essas bases de código.

GrupoConfiguração e Prática
TipoSintaxe
Modo strictNão necessário

ℹ️ Info O editor transpila TypeScript para JavaScript e o executa (sem verificação de tipos); veja a Saída de cada exemplo para o resultado da verificação.

📝 Sintaxe

// Decorator de classe: recebe o construtor
function sealed(Ctor: Function): void {
  Object.seal(Ctor);
  Object.seal(Ctor.prototype);
}

// Decorator de método: recebe (protótipo, nome do método, descritor de propriedade)
function logged(target: object, key: string, desc: PropertyDescriptor): void {
  const original = desc.value;
  desc.value = function (...args: unknown[]) {
    console.log("call", key, args);
    return original.apply(this, args);
  };
}

@sealed
class Calculator {
  @logged
  add(a: number, b: number) { return a + b; }
}

⚙️ Parâmetros

ClassDecoratorRecebe o construtor da classe; pode mutar a classe ou retornar uma substituta — usado para restrições de classe inteira como @sealed
MethodDecoratorExecuta uma vez no momento da definição da classe; envolve o original reescrevendo desc.value, ou substitui o descritor inteiro pelo valor de retorno
experimentalDecoratorsFlag do tsconfig; sem ela, decoradores são um erro de compilação. O ecossistema de frameworks (NestJS etc.) atualmente se baseia nesta versão experimental

Retorno：Um decorador de classe pode retornar um novo construtor que substitui a classe original (ou nada, mantendo a original); um decorador de método pode retornar um novo property descriptor ou undefined, agindo apenas por efeitos colaterais.

▶ Exemplo

Edite o código abaixo e clique em Testar para ver o resultado transpilado:

Saída：

-> add(2, 3)
add = 5
-> mul(4, 5)
mul = 20

(Saída de execução após a transpilação; o decorador de método envolve no momento da definição da classe — cada chamada registra "-> add(2, 3)" antes de retornar o resultado)
▶ Testar

💡 Observações

ℹ️ Info Decoradores executam no momento da definição da classe, não no momento da chamada: a função decoradora roda uma vez quando a classe é avaliada, trocando desc.value pela versão empacotada; toda chamada posterior passa pelo empacotador.
💡 Dica Para parametrizar um decorador, use uma fábrica: @log("debug") é uma função que retorna um decorador — a chamada externa recebe a configuração, a interna recebe (target, key, desc). O @Injectable() do NestJS com parênteses é exatamente isso.
⚠️ Atenção As assinaturas experimental e padrão são incompatíveis: desde o TS 5 é possível dispensar experimentalDecorators e usar decoradores padrão ES, em que o decorador de método recebe um objeto context em vez de (target, key, desc). Confirme qual versão está em jogo antes de ler código legado ou de frameworks.
classes-basics implements-interfaces
Mais casos em breve.

📚 Tutoriais relacionados

Decoradores do TypeScript
Lição 23: Decoradores do TypeScript

❓ Perguntas frequentes

P Como os decoradores diferem de funções de ordem superior comuns?
R Em essência, ambos empacotam funções. A diferença é o posicionamento: decoradores ficam acima do membro decorado e o compilador faz a ligação, mantendo o corpo da classe limpo; funções de ordem superior precisam ser aplicadas explicitamente onde criadas. Decoradores funcionam como etiquetas e servem a preocupações transversais.
P Como o @Injectable() do NestJS funciona?
R @Injectable() é uma fábrica de decoradores; o decorador de classe retornado anexa metadados marcando a classe como instanciável pelo contêiner de DI. Ao construir um Controller, o contêiner lê os metadados dos parâmetros do construtor e resolve as dependências automaticamente — o decorador apenas registra informações; a injeção acontece no contêiner.
P Um projeto novo deve usar decoradores experimentais ou padrão?
R Siga o seu framework: com ecossistemas NestJS/TypeORM, mantenha experimentalDecorators (eles dependem da semântica antiga); para código próprio, prefira os decoradores padrão (padrão do TS 5+) — padronizados no ES, sem o fardo experimental. Os dois estilos não podem ser misturados.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%