Аннотации

Аннотация — специальная синтаксическая конструкция, которая позволяет добавить метаданные в программный код. Добавленные метаданные могут использоваться компилятором/интерпретатором и другими механизмами при работе с исходным кодом. Аннотации могут размещаться на объявлениях структур, исключений, перечислений, констант, свойств, методов, параметров и конструкторов — в зависимости от применимости конкретной аннотации.

В программном коде аннотации отмечаются специальным символом @ и указываются перед аннотируемым объектом:

@ИмяАннотации
объект

Например:

@ИменованныеПараметры(КромеПервого = Истина)
метод Пример(П1: Число = 22, П2: Число, П3 = 44)
;

В примере выше аннотация @ИменованныеПараметры дает возможность указать, что в методе/конструкторе допускаются только именованные аргументы для всех параметров, кроме первого. При попытке вызвать такой метод с позиционной формой параметров будет ошибка:

метод ВызватьМетод()
  Пример(П2 = 22)     // Ошибки нет
  Пример(0, П2 = 22)  // Ошибки нет, т. к. задан параметр КромеПервого = Истина
  Пример(0, 22)       // Ошибка. Допустим вызов только с именованной формой параметров
;

Аннотации могут иметь параметры. Параметры могут быть как обязательными, так и необязательными (иметь значение по умолчанию).

На типы параметров аннотаций и их значения (выражения инициализации) накладываются следующие ограничения:

• Выражение, которое присваивается в качестве значения параметра, должно быть вычислимо во время компиляции. Выражение является вычислимым на этапе компиляции, если оно удовлетворяет следующим критериям:

  • Литералы (включая литералы коллекций) являются вычислимыми.
  • Обращения к константам модулей являются вычислимыми.
  • Операции над вычислимыми являются вычислимыми, кроме следующих исключений:
    • Вызовы методов и обращения к свойствам.
    • Вызовы конструкторов.
    • Операции сложения значения типа Строка со значением другого типа.

примечание

Если выражение инициализации не указано, то в параметр присваивается значение по умолчанию. Если для выбранного параметра аннотации нет значения по умолчанию, то во время компиляции возникает ошибка.

Дополнительно разрешается использовать аннотации как параметры других аннотаций:

@Аннотация1(Параметр11 = @Аннотация2(Параметр21 = "ЗначениеПараметра"))

Синтаксис аннотаций с параметрами

• Именованная форма:

  @Аннотация(Параметр1 = Значение1, ... , ПараметрN = ЗначениеN)

• Позиционная форма: допускается использовать позиционную форму только для первого параметра, если аннотация имеет соответствующий признак.

  

  @Аннотация(Значение1, Параметр2 = Значение2, ... , ПараметрN = ЗначениеN)

  @Аннотация(Параметр1 = Значение1, ... , ПараметрN = ЗначениеN)

  

  @Аннотация(Значение1, Значение2, ...)

  @Аннотация(Параметр1 = Значение1, Значение2, ...)

Типы аннотаций

• @ИменованныеПараметры — запрещает вызывать метод с позиционными аргументами (допускаются только именованные аргументы). Имеет параметр КромеПервого: Булево, который указывает, что первый параметр можно использовать в позиционной форме.

• @Контекстный — помечает контекстные серверные нестатические методы, доступные в модулях компонентов интерфейса (подробнее).

• @Обработчик — помечает методы-обработчики.

• @Подписка — используется для объявления подписки на события (подробнее).

• @Реализация — помечает методы, которые являются реализацией абстрактного метода контракта (подробнее).

• Аннотации ОбластиВидимости — определяют область видимость элемента (подробнее):

  • @ВПодсистеме,

  • @ВПроекте,

  • @ВТипе,

  • @Глобально,

  • @Локально.

• Аннотации Окружения — определяют окружение элемента (подробнее):

  • @ДоступноСКлиента;

    примечание

    Можно использовать с параметром КешироватьРезультат типа Булево. Значение по умолчанию — Ложь. Если значение параметра Истина, то результат первого вызова метода сохраняется в кеше на клиенте, а последующие вызовы, осуществляемые в течение данного сеанса пользователя, используют прошлый результат, не выполняя реального обращения к серверу.

  • @НаКлиенте;

  • @НаСервере.

• Аннотации Проверки — определяют необходимость проверки элемента:

  • @ПроверятьИспользованиеЗначения (подробнее).

• Аннотации Проект — используются для настройки и обновления приложений (подробнее):

  • @НастройкаПриложения,

  • @ОбновлениеПроекта.

• @Устарело — помечает некоторую функциональность как устаревшую (подробнее). Аннотация может применяться к следующим элементам языка «1С:Элемент»:

  • элементы перечислений,

    перечисление ОперационныеСистемы
      @Устарело(Сообщение = "Больше не поддерживаем Linux!")
      Linux,
      macOS,
      Windows умолчание
    ;

  • методы,

    @Устарело(Сообщение = "Устаревшая функциональность!")
    метод ПолучитьДанные()
    ;

  • конструкторы,

    структура БухгалтерскийДокумент
    @Устарело(Сообщение = "Устаревший конструктор для старого формата")
    конструктор
    ;

  • параметры методов и конструкторов,

    метод ДесериализоватьСтруктуруУстаревший(@Устарело СтрокаJSON: Строка)
    ;

  • свойства.

    структура БухгалтерскийДокумент
    @Устарело(Сообщение = "Устаревшее свойство")
    пер Сумма: Число
    ;

Информация об устаревшей функциональности отображается в панели Проблемы и во всплывающей подсказке:

Для типов стандартной библиотеки в сообщении отображается информация об актуальной функциональности: