This declaration needs opt-in. Its usage must be marked with '@kotlin.concurrent.atomics.ExperimentalAtomicApi' or '@OptIn(kotlin.concurrent.atomics.ExperimentalAtomicApi::class)'
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
import kotlin.concurrent.atomics.*
fun main() {
val n = AtomicInt(0)
println(n.addAndFetch(1))
}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
@Composable
fun Ecran() {
TopAppBar(title = { Text("Comenzi") })
}@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
// @OptIn repetat în zeci de fișiere// 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ă 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.
import kotlin.concurrent.atomics.*
fun main() {
val vizite = AtomicInt(0)
repeat(3) { vizite.addAndFetch(1) }
println("Vizite: ${vizite.load()}")
}Vizite: 3
Indiciu
Pune @OptIn(ExperimentalAtomicApi::class) deasupra lui fun main().
Reparația
import kotlin.concurrent.atomics.*
@OptIn(ExperimentalAtomicApi::class)
fun main() {
val vizite = AtomicInt(0)
repeat(3) { vizite.addAndFetch(1) }
println("Vizite: ${vizite.load()}")
}De ce merge
Clasa AtomicInt și funcțiile ei sunt marcate cu @ExperimentalAtomicApi, o adnotare @RequiresOptIn de nivel eroare. Compilatorul cere să confirmi explicit că folosești un API care se poate schimba. @OptIn(ExperimentalAtomicApi::class) pe main dă acordul pentru tot corpul funcției, iar cele trei apeluri addAndFetch(1) duc contorul la 3.
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
'fun String.toUpperCase(): String' is deprecated. Use uppercase() instead. Codul folosește o funcție veche din biblioteca standard, scoasă din uz (toUpperCase, toLowerCase, capitalize). În Kotlin 2.x apelul e eroare de compilare. Înlocuiește cu varianta nouă: uppercase(), lowercase(), replaceFirstChar { it.uppercase() }. Unresolved reference 'totl' Compilatorul nu găsește niciun nume totl: nu există o variabilă, funcție sau clasă cu numele ăsta în locul în care l-ai folosit. De obicei e o greșeală de scriere, o variabilă declarată în alt bloc sau un import lipsă. Corectează numele sau declară-l. Suspend function 'suspend fun delay(timeMillis: Long): Unit' can only be called from a coroutine or another suspend function Apelezi o funcție suspend (delay, o funcție proprie marcată suspend) dintr-o funcție obișnuită. Funcțiile suspend pot fi apelate doar din corutine sau din alte funcții suspend. Marchează și funcția apelantă cu suspend, sau pornește o corutină, de exemplu cu runBlocking { } în main. Î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.
