Metadatos

Usa metadatos para proporcionar información estática adicional sobre tu código. Una anotación de metadatos comienza con el carácter @, seguido de una referencia a una constante en tiempo de compilación (como deprecated) o una llamada a un constructor constante.

Los metadatos se pueden adjuntar a la mayoría de los constructos de programas Dart añadiendo anotaciones antes de la declaración o directiva del constructo.

Las siguientes anotaciones están disponibles para todo el código Dart:

@Deprecated

Marca una declaración como obsoleta (deprecated), indicando que debería ser migrada, con un mensaje que explica el reemplazo y la posible fecha de eliminación.

Además de la anotación general @Deprecated, puedes usar anotaciones específicas para desaprobar ciertos usos de una declaración:

• @Deprecated.extend(): Extender la clase está desaprobado.
• @Deprecated.implement(): Implementar la clase o mixin está desaprobado.
• @Deprecated.subclass(): Subclasificar (extender o implementar) la clase o mixin está desaprobado.
• @Deprecated.mixin(): Mezclar (mixin) la clase está desaprobado.
• @Deprecated.instantiate(): Instanciar la clase está desaprobado.
• @Deprecated.optional(): Omitir un argumento para el parámetro está desaprobado.

Aquí tienes un ejemplo de uso de la anotación @Deprecated:

dart

class Television {
  /// Use [turnOn] to turn the power on instead.
  @Deprecated('Use turnOn instead')
  void activate() {
    turnOn();
  }
​
  /// Turns the TV's power on.
  void turnOn() {
    // ···
  }
  // ···
}

content_copy

@deprecated

Marca una declaración como obsoleta (deprecated) hasta una futura versión no especificada. Es preferible usar @Deprecated y proporcionar un mensaje de obsolescencia.

@override

Marca un miembro de instancia como una anulación (override) o implementación de un miembro con el mismo nombre de una clase o interfaz padre. Para ver ejemplos del uso de @override, consulta Extender una clase.

@pragma

Proporciona instrucciones o sugerencias específicas sobre una declaración a las herramientas de Dart, como el compilador o el analyzer.

El analyzer de Dart proporciona retroalimentación en forma de diagnósticos si se necesita la anotación @override y cuando se usan miembros anotados con @deprecated o @Deprecated.

Además de proporcionar soporte y análisis para las anotaciones incorporadas, el analyzer de Dart ofrece soporte y diagnósticos adicionales para una variedad de anotaciones de package:meta. Algunas anotaciones de uso común que proporciona el paquete incluyen:

@visibleForTesting

Marca un miembro de un paquete como público únicamente para que se pueda acceder al miembro desde las pruebas del paquete. El analyzer oculta el miembro de las sugerencias de autocompletado y advierte si se utiliza desde otro paquete.

@awaitNotRequired

Marca las variables que tienen un tipo Future o funciones que devuelven un Future indicando que no requieren que el llamador espere (await) al Future. Esto evita que el analyzer advierta a los llamadores que no esperan al Future debido a las reglas del linter discarded_futures o unawaited_futures.

Para obtener más información sobre estas y las demás anotaciones que proporciona el paquete, qué indican, qué funcionalidad habilitan y cómo usarlas, consulta la documentación de la API de package:meta/meta.dart.

Puedes definir tus propias anotaciones de metadatos. Aquí tienes un ejemplo de cómo definir una anotación @Todo que toma dos argumentos:

class Todo {
  final String who;
  final String what;
​
  const Todo(this.who, this.what);
}

Y aquí tienes un ejemplo de uso de esa anotación @Todo:

@Todo('Dash', 'Implement this function')
void doSomething() {
  print('Do something');
}

Para indicar el tipo de constructos de lenguaje que deberían anotarse con tu anotación, usa la anotación @Target de package:meta.

Por ejemplo, si quisieras que la anotación @Todo anterior solo se permitiera en funciones y métodos, añadirías la siguiente anotación:

import 'package:meta/meta_meta.dart';
​
@Target({TargetKind.function, TargetKind.method})
class Todo {
  // ···
}

Con esta configuración, el analyzer advertirá si Todo se usa como una anotación en cualquier declaración que no sea una función o método de nivel superior.