<init>

Требования к платформе и версии: JVM (1.0), JS (1.0), Native (1.0)

RequiresOptIn(
    message: String = "", 
    level: Level = Level.ERROR)

Указывает, что аннотированный класс аннотации является маркером API, для которого требуется явное включение.

Вызовы любого объявления, аннотированного таким маркером или упоминающего в своей сигнатуре любое другое объявление, требующее включения, должны включить API, используя OptIn или, будучи аннотированными этим маркером, что приводит к дальнейшему распространению требования к включению.

Предполагаемые варианты использования маркеров включения включают, но не ограничиваются ими:

• Экспериментальный API для публичной предварительной версии, который может изменить свою семантику или повлиять на двоичную совместимость.
• Внутренние объявления, которые не должны использоваться за пределами библиотеки объявления, но public по техническим причинам.
• Хрупкий или сложный API, для использования которого требуется большой опыт, и поэтому требуется явное включение.

Заражаемость

Когда объявление помечено требованием включения, оно считается заразительным, что означает, что все его использования или упоминания в других объявлениях потребуют явного включения. Правило большого пальца для распространения таково: если помеченное объявление перестает существовать, только места с явным включением (или соответствующим предупреждением) выйдут из строя. Это правило не подразумевает транзитивность, например, распространение не распространяет включение через инлайнирование, что делает его обязанностью inline автора функции правильно его пометить.

Сферы типов

Тип считается требующим включения, если он помечен маркером включения или внешнее объявление (класс или интерфейс) требует включения. Любое использование любого объявления, упоминающего такой тип в своей сигнатуре, потребует явного включения, даже если оно не используется непосредственно в месте вызова и даже если такие объявления не требуют включения напрямую.

Например, рассмотрите следующие объявления, помеченные не распространяющимся включением:

@UnstableApi
class Unstable

@OptIn(UnstableApi::class)
fun foo(): Unstable = Unstable()

@OptIn(UnstableApi::class)
fun bar(arg: Unstable = Unstable()) {}

@OptIn(UnstableApi::class)
fun Unstable?.baz() {}

и их соответствующие места вызова:

fun outerFun() {
    val s = foo()
    bar()
    null.baz()
}

Несмотря на то, что места вызова не упоминают Unstable тип напрямую, соответствующее предупреждение или ошибка включения будут срабатывать в каждом месте вызова из-за заразительности распространения. Обратите внимание, что распространение не является транзитивным, т. е. вызовы к outerFun сам по себе не будет вызывать дополнительных требований к включению.

Лексические области

Если тип требует включения, такое требование распространяется на его лексическую область и все его вложенные объявления. Например, для следующей области:

@UnstableApi
class Unstable {
    fun memberFun() = ...

    class NestedClass {
        fun nestedFun() = ...
    }
}

Любое использование Unstable, NestedClass, или их методов-членов потребует явного включения.

Переопределенные объявления

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

См. также Документацию по языку Kotlin для получения дополнительной информации.