...
Eroare Kotlin · Biblioteca standard, Java și formatare

This declaration needs opt-in. Its usage must be marked with '@kotlin.concurrent.atomics.ExperimentalAtomicApi' or '@OptIn(kotlin.concurrent.atomics.ExperimentalAtomicApi::class)'

Pe scurt

Folosești un API marcat experimental (de exemplu ExperimentalAtomicApi, ExperimentalCoroutinesApi sau o adnotare a unei biblioteci), care cere acordul explicit. Adaugă @OptIn(NumeAdnotare::class) pe funcție, clasă sau fișier, după ce accepți că API-ul se poate schimba.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

Bibliotecile Kotlin marchează API-urile instabile cu adnotări de tip @RequiresOptIn: biblioteca standard (ExperimentalAtomicApi, ExperimentalStdlibApi), kotlinx.coroutines (ExperimentalCoroutinesApi, DelicateCoroutinesApi, FlowPreview), Compose (ExperimentalMaterial3Api). Ca să le folosești, trebuie să confirmi explicit că accepți riscul ca API-ul să se schimbe.

Fără confirmare primești This declaration needs opt-in. Its usage must be marked with '@X' or '@OptIn(X::class)'. Unele adnotări produc doar un avertisment, altele (ca aici) o eroare de compilare.

Ai două variante: @OptIn(X::class) pe declarația care folosește API-ul (efectul rămâne local), sau @X pe declarația ta, care propagă cerința de opt-in mai departe la cei care o apelează. Pentru tot modulul există opțiunea de compilator -opt-in=X.

De ce apare: cauzele frecvente

1API experimental din biblioteca standard

Greșit
KOTLIN
import kotlin.concurrent.atomics.*

fun main() {
    val n = AtomicInt(0)
    println(n.addAndFetch(1))
}
Corect
KOTLIN
import kotlin.concurrent.atomics.*

@OptIn(ExperimentalAtomicApi::class)
fun main() {
    val n = AtomicInt(0)
    println(n.addAndFetch(1))
}

@OptIn confirmă folosirea API-ului experimental în această funcție.

2Compose Material 3 experimental

Greșit
KOTLIN
@Composable
fun Ecran() {
    TopAppBar(title = { Text("Comenzi") })
}
Corect
KOTLIN
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun Ecran() {
    TopAppBar(title = { Text("Comenzi") })
}

Componente ca TopAppBar sunt încă marcate experimentale în Material 3 și cer opt-in.

3Opt-in pentru tot modulul

Greșit
KOTLIN
// @OptIn repetat în zeci de fișiere
Corect
KOTLIN
// build.gradle.kts
kotlin {
    compilerOptions {
        optIn.add("kotlinx.coroutines.ExperimentalCoroutinesApi")
    }
}

Când folosești același API experimental peste tot, opt-in-ul la nivel de modul evită repetarea.

Repară tu

Repară eroarea, direct în pagină

Programul numără vizitele cu AtomicInt din kotlin.concurrent.atomics, un API experimental, și nu compilează: This declaration needs opt-in. Adaugă opt-in-ul pe funcția main ca programul să afișeze Vizite: 3.

Codul care dă eroarea
KOTLIN
import kotlin.concurrent.atomics.*

fun main() {
    val vizite = AtomicInt(0)
    repeat(3) { vizite.addAndFetch(1) }
    println("Vizite: ${vizite.load()}")
}
După reparație, programul afișează
Vizite: 3
Indiciu

Pune @OptIn(ExperimentalAtomicApi::class) deasupra lui fun main().

Alte forme ale mesajului

  • error: this declaration needs opt-in. Its usage must be marked with '@kotlin.concurrent.atomics.ExperimentalAtomicApi' or '@OptIn(kotlin.concurrent.atomics.ExperimentalAtomicApi::class)'
  • This declaration needs opt-in. Its usage should be marked with '@kotlinx.coroutines.ExperimentalCoroutinesApi' or '@OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)'
  • This material API is experimental and is likely to change or to be removed in the future.
  • This is a delicate API and its use requires care. Make sure you fully read and understand documentation of the declaration that is marked as a delicate API.

Cum o eviți pe viitor

Înainte să adaugi @OptIn, citește documentația API-ului: află de ce e experimental și dacă există o alternativă stabilă. Ține opt-in-urile cât mai local (pe funcție, nu pe tot modulul) dacă API-ul e folosit în puține locuri, ca să știi ce trebuie verificat la actualizarea bibliotecii. La actualizări de versiune, caută @OptIn în proiect și verifică notele de lansare.

Întrebări frecvente

Care e diferența dintre @OptIn(X::class) și @X?

@OptIn consumă cerința: codul tău folosește API-ul, dar apelanții tăi nu mai trebuie să știe. @X pe funcția ta o face și pe ea experimentală, iar fiecare apelant trebuie să facă opt-in.

E periculos să folosesc API-uri experimentale?

Nu neapărat; înseamnă doar că semnătura sau comportamentul se pot schimba într-o versiune viitoare. Pentru cod de producție, verifică dacă API-ul a devenit stabil la fiecare actualizare.

Erori înrudite

← Toate erorile Kotlin

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață Kotlin de la zero, cu exerciții la fiecare lecție

Curs Kotlin (Android): lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.