metadados

O que são anotações de metadados?

Iniciam com @ e anexam informações estáticas extras ao código. São lidas pelo compilador, IDE e analisador estático e não alteram a lógica de execução.

Dois formatos válidos:

1. Constantes nativas de tempo de compilação: @override, @deprecated
2. Chamadas de construtores constantes: @Deprecated("Texto de aviso"), anotações personalizadas como @Todo("xxx", "xxx")

Geralmente aplicadas em classes, métodos, variáveis, funções, parâmetros, imports, enums e outros elementos.

@Deprecated

Marca uma API obsoleta. É obrigatório informar a alternativa e a data de remoção. Também possui métodos estáticos para restringir cenários específicos.

class Television {
  /// Alternativa: utilize turnOn
  @Deprecated('Use turnOn() no lugar. Este método será removido no final de 2026')
  void activate() {
    turnOn();
  }

  void turnOn() {
    print("TV ligada");
  }
}

// Exemplos de restrições de obsolescência específicas
@Deprecated.instantiate() // Impede instanciar essa classe com new
class OldDevice {}

@Deprecated.extend() // Impede que outras classes herdem dela
class Base {}

// Tentar herdar de Base gera aviso de obsolescência no editor
class Sub extends Base {}

void main() {
  Television tv = Television();
  // Chamar método marcado com @Deprecated mostra risco e aviso no IDE
  tv.activate();
  // Novo método recomendado
  tv.turnOn();

  // Instanciar OldDevice dispara aviso de @Deprecated.instantiate()
  OldDevice device = OldDevice();
}
Code language: Dart (dart)

O código acima compila e executa normalmente, apenas exibe avisos no IDE e compilador. Você pode testar com Android Studio ou IntelliJ IDEA.

@deprecated

Sem mensagem personalizada, marca apenas obsolescência simples. Dê preferência a @Deprecated("Descrição")

@deprecated
void oldFunc() {}
Code language: Dart (dart)

@override

Marca membros que sobrescrevem elementos de mesmo nome da superclasse ou interface. O IDE faz validação: nomes de métodos escritos errados aparecem com erro vermelho.

class Animal {
  void speak() {}
}

class Dog extends Animal {
  // @override indica sobrescrita do método speak da classe pai
  @override
  void speak() {
    print("Au au");
  }
}

class Cat extends Animal {
  @override
  void speak() {
    print("Miau");
  }
}

class Pig extends Animal {
   // Sem sobrescrita
}

void main() {
  Animal dog = Dog();
  Animal cat = Cat();
  Animal pig = Pig();

  dog.speak(); // Saída: Au au
  cat.speak(); // Saída: Miau
  pig.speak();
}
Code language: Dart (dart)

@pragma

Envia diretivas de otimização de baixo nível ou identificação ao compilador e analisador estático, usado principalmente em desenvolvimento de baixo nível.

// Exemplo: Pedir ao compilador para inlinear essa função
@pragma('vm:prefer-inline')
int add(int a, int b) => a + b;
Code language: Dart (dart)