kotlin更多語言結(jié)構(gòu)——>選擇加入要求
Kotlin 標準庫提供了一種機制，用于要求并明確同意使用 API 的某些元素。通過這種機制，庫開發(fā)人員可以將使 用其 API 需要選擇加入的特定條件告知用戶，例如，如果某個 API 處于實驗狀態(tài)，并且將來可能會更改。
為了避免潛在的問題，編譯器會向此類 API 的用戶發(fā)出警告，告知他們這些條件，并要求他們在使用 API 之前選 擇加入
選擇使用API
如果庫作者將一個庫的 API 聲明標記為要求選擇加入 你應該明確同意在代碼中使用它。有多種方式可以選擇加入使用此類 API，所有方法均不受技術(shù)限制。你可以自由選擇最適合自己的方式。
傳播選擇加入
在使用供第三方(庫)使用的 API 時，你也可以把其選擇加入的要求傳播到自己的 API。為此，請在你的 API 主體 聲明中添加注解 要求選擇加入的注解。這可以讓你使用帶有此注解的 API 元素。
// 庫代碼 @RequiresOptIn(message = "This API is experimental. It may be changed in the future without notice.") @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyDateTime // 要求選擇加入的注解 @MyDateTime class DateProvider // 要求選擇加入的類
// 客戶端代碼
fun getYear(): Int {
val dateProvider: DateProvider // 錯誤:DateProvider 要求選擇加入
// ...
}
@MyDateTime
fun getDate(): Date {
val dateProvider: DateProvider // OK:該函數(shù)也需要選擇加入
// ...
}
fun displayDate() {
println(getDate()) // 錯誤:getDate() 需要選擇加入
}
如本例所示，帶注釋的函數(shù)看起來是 @MyDateTime API 的一部分。因此，這種選擇加入會將選擇加入的要求 傳播到客戶端代碼;其客戶將看到相同的警告消息，并且也必須同意。要使用多個需要選擇加入的API，請在聲明中標記所有需要選擇加入的注解
非傳播的用法
在不公開其自身API的模塊(例如應用程序)中，你可以選擇使用 API 而無需將選擇加入的要求傳播到代碼中。這種情況下，請使用 @OptIn 標記你的聲明，并以要求選擇加入的注解作為參數(shù)
// 庫代碼 @RequiresOptIn(message = "This API is experimental. It may be changed in the future without notice.") @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyDateTime // 要求選擇加入的注解 @MyDateTime class DateProvider // 要求選擇加入的類
//客戶端代碼
@OptIn(MyDateTime::class)
fun getDate(): Date { // 使用 DateProvider;不傳播選擇加入的要求
val dateProvider: DateProvider
// ...
}
fun displayDate() {
println(getDate()) // OK:不要求選擇加入
}
當有人調(diào)用函數(shù) getDate() 時，不會通知他們函數(shù)主體中使用的選擇加入 API 的要求。
要在一個文件的所有函數(shù)和類中使用要求選擇加入的 API，請在文件的頂部，文件包說明和導入聲明前添加文件級注釋 @file:OptIn
//客戶端代碼 @file:OptIn(MyDateTime::class)
模塊范圍的選擇加入
如果你不想在使用要求選擇加入 API 的每個地方都添加注解，則可以為整個模塊選擇加入這些 API。要選擇在 模塊中使用 API，請使用參數(shù) -Xopt-in 進行編譯，使用 -Xopt-in = org.mylibrary.OptInAnnotation 指定該 API 使用的要求選擇加入注解的標準名稱。使用此參數(shù)進行編 譯的效果與模塊中每個聲明都有注解 @OptIn(OptInAnnotation::class) 的效果相同。
如果使用 Gradle 構(gòu)建模塊，可以添加如下參數(shù)
tasks.withType(KotlinCompile).configureEach {
kotlinOptions {
freeCompilerArgs += "-Xopt-in=org.mylibrary.OptInAnnotation"
}
}
tasks.withType<KotlinCompile>().configureEach {
kotlinOptions.freeCompilerArgs += "-Xopt-in=org.mylibrary.OptInAnnotation"
}
如果你的 Gradle 模塊是多平臺模塊，請使用 useExperimentalAnnotation 方法
sourceSets {
all {
languageSettings {
useExperimentalAnnotation('org.mylibrary.OptInAnnotation')
}
}
}
sourceSets {
all {
languageSettings.useExperimentalAnnotation("org.mylibrary.OptInAnnotation")
}
}
對于 Maven，它將是:
<build>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${ kotlin.version }</version>
<executions>...</executions>
<configuration>
<args>
<arg>-Xopt-in =org.mylibrary.OptInAnnotation</arg>
</args>
</configuration>
</plugin>
</plugins>
</build>
要在模塊級別選擇加入多個 API，請為每個要求選擇加入的 API 添加以上描述的參數(shù)之一
要求選擇加入 API
要求選擇加入的注解
如果想獲得使用者使用你的模塊 API 的明確同意，請創(chuàng)建一個注解類，作為_要求選擇加入的注解_。這個類必須 使用 @RequiresOptIn 注解:
@RequiresOptIn @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyDateTime
要求選擇加入的注解必須滿足以下幾個要求:
— BINARY retention
— targets中沒有 EXPRESSION 與 FILE
— 沒有參數(shù)
選擇加入的要求可以具有以下兩個嚴格級別之一:
— RequiresOptIn.Level.ERROR 。選擇加入是強制性的。否則，使用標記 API 的代碼將無法編譯。默認級別。
— RequiresOptIn.Level.WARNING 。選擇加入不是強制性的，而是建議使用的。沒有它，編譯器會發(fā)出警告。
要設置所需的級別，請指定 @RequiresOptIn 注解的 level 參數(shù)
另外，你可以提供一個 message 來通知用戶有關(guān)使用該 API 的特定條件。編譯器會將其顯示給使用該 API 但未選擇加入的用戶
@RequiresOptIn(level = RequiresOptIn.Level.WARNING, message = "This API is experimental. It can be incompatibly changed in the future.") @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class ExperimentalDateTime
如果你發(fā)布了多個需要選擇加入的獨立功能，請為每個功能聲明一個注解。這使你的用戶可以更安全地使用 API:他們只能使用其明確接受的功能。這也使你可以獨立地從功能中刪除選擇加入的要求
標記 API 元素
要在使用 API 時要求選擇加入，請給它的聲明添加要求選擇加入的注解
@MyDateTime
class DateProvider
@MyDateTime
fun getTime(): Time {}
穩(wěn)定前 API 的選擇加入要求
如果要求選擇加入尚未穩(wěn)定的特性，請仔細處理 API 由實驗狀態(tài)到穩(wěn)定狀態(tài)的轉(zhuǎn)換，以避免破壞客戶端代碼。
當穩(wěn)定前 API 穩(wěn)定之后并以穩(wěn)定狀態(tài)發(fā)布后，請從聲明中刪除其要求選擇加入的注解。客戶端將可以不受限制 地使用它們。但是，你應該將注解類留在模塊中，以便與現(xiàn)有的客戶端代碼保持兼容。
為了讓 API 用戶相應地更新其模塊(從代碼中刪除注解并重新編譯)，請將注解標記為 @Deprecated 并在棄 用 message 中提供說明
@Deprecated("This opt-in requirement is not used anymore. Remove its usages from your code.")
@RequiresOptIn
annotation class ExperimentalDateTime
選擇加入要求的實驗狀態(tài)
選擇加入要求的機制在 Kotlin 1.3 中是實驗性的。這意味著在將來的版本中，可能會以不兼容的方式進行更改。
為了讓使用注解 @OptIn 和 @RequiresOptIn 的用戶了解其實驗狀態(tài)，編譯器會在編譯代碼時發(fā)出警告:
This class can only be used with the compiler argument '-Xopt- in=kotlin.RequiresOptIn'
要移除警告，請?zhí)砑泳幾g器參數(shù) -Xopt-in=kotlin.RequiresOptIn 。
浙公網(wǎng)安備 33010602011771號