Метаданные

Что такое аннотации метаданных?

Начинаются с символа @, добавляют к коду статическую дополнительную информацию. Читаются компилятором, IDE и статическим анализатором, не влияют на логику выполнения.

Два допустимых варианта записи:

1. Встроенные константы времени компиляции: @override, @deprecated
2. Вызовы конструкторов-констант: @Deprecated("Текст предупреждения"), пользовательские аннотации @Todo("xxx", "xxx")

Обычно применяются к классам, методам, переменным, функциям, параметрам, импортам, перечислениям и другим элементам.

@Deprecated

Отмечает устаревший API. Обязательно указывайте альтернативу и дату удаления. Существуют статические методы для ограничения отдельных сценариев использования.

class Television {
  /// Альтернатива: используйте turnOn
  @Deprecated('Используйте turnOn() вместо этого метода, он будет удален в конце 2026 года')
  void activate() {
    turnOn();
  }

  void turnOn() {
    print("Телевизор включен");
  }
}

// Примеры ограничений для разных сценариев устаревания
@Deprecated.instantiate() // Запрет на создание экземпляров через new
class OldDevice {}

@Deprecated.extend() // Запрет на наследование этого класса
class Base {}

// Попытка наследовать Base вызовет предупреждение в редакторе
class Sub extends Base {}

void main() {
  Television tv = Television();
  // Вызов метода с @Deprecated: в IDE появится зачеркнутый текст и предупреждение
  tv.activate();
  // Рекомендуемый новый метод
  tv.turnOn();

  // Создание экземпляра OldDevice активирует предупреждение @Deprecated.instantiate()
  OldDevice device = OldDevice();
}
Code language: Dart (dart)

Приведенный код нормально компилируется и запускается, предупреждения отображаются только в IDE и компиляторе. Проверьте поведение в Android Studio или IntelliJ IDEA.

@deprecated

Без пользовательского описания, простая пометка устаревания. Предпочитайте запись @Deprecated("Описание")

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

@override

Отмечает члены, переопределяющие одноименные элементы родительского класса или интерфейса. IDE выполняет проверку: при опечатке в названии метода появится красная ошибка.

class Animal {
  void speak() {}
}

class Dog extends Animal {
  // @override указывает на переопределение родительского метода speak
  @override
  void speak() {
    print("Гав");
  }
}

class Cat extends Animal {
  @override
  void speak() {
    print("Мяу");
  }
}

class Pig extends Animal {
   // Переопределения нет
}

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

  dog.speak(); // Вывод: Гав
  cat.speak(); // Вывод: Мяу
  pig.speak();
}
Code language: Dart (dart)

@pragma

Передает низкоуровневые инструкции оптимизации и распознавания компилятору и статическому анализатору, используется в низкоуровневой разработке.

// Пример: указать компилятору инлайнить эту функцию
@pragma('vm:prefer-inline')
int add(int a, int b) => a + b;
Code language: Dart (dart)