kotlin更多語(yǔ)言結(jié)構(gòu)——>選擇加入要求-創(chuàng)新互聯(lián)

1.3.70 中引入了 @RequireOptIn 與 @OptIn 注解以取代先前使用的 @Experimental 與 @UseExperimental;同時(shí) -Xopt-in 編譯器選項(xiàng)也取代了 -Xuse-experimental。 　　Kotlin 標(biāo)準(zhǔn)庫(kù)提供了一種機(jī)制，用于要求并明確同意使用 API 的某些元素。通過(guò)這種機(jī)制，庫(kù)開(kāi)發(fā)人員可以將使 用其 API 需要選擇加入的特定條件告知用戶，例如，如果某個(gè) API 處于實(shí)驗(yàn)狀態(tài)，并且將來(lái)可能會(huì)更改。

為了避免潛在的問(wèn)題，編譯器會(huì)向此類 API 的用戶發(fā)出警告，告知他們這些條件，并要求他們?cè)谑褂?API 之前選 擇加入

創(chuàng)新互聯(lián)建站專注為客戶提供全方位的互聯(lián)網(wǎng)綜合服務(wù)，包含不限于做網(wǎng)站、成都做網(wǎng)站、青縣網(wǎng)絡(luò)推廣、微信小程序、青縣網(wǎng)絡(luò)營(yíng)銷、青縣企業(yè)策劃、青縣品牌公關(guān)、搜索引擎seo、人物專訪、企業(yè)宣傳片、企業(yè)代運(yùn)營(yíng)等，從售前售中售后，我們都將竭誠(chéng)為您服務(wù)，您的肯定，是我們大的嘉獎(jiǎng)；創(chuàng)新互聯(lián)建站為所有大學(xué)生創(chuàng)業(yè)者提供青縣建站搭建服務(wù)，24小時(shí)服務(wù)熱線：028-86922220，官方網(wǎng)址：muchs.cn

選擇使用API

如果庫(kù)作者將一個(gè)庫(kù)的 API 聲明標(biāo)記為要求選擇加入 你應(yīng)該明確同意在代碼中使用它。有多種方式可以選擇加入使用此類 API，所有方法均不受技術(shù)限制。你可以自由選擇最適合自己的方式。

傳播選擇加入

在使用供第三方(庫(kù))使用的 API 時(shí)，你也可以把其選擇加入的要求傳播到自己的 API。為此，請(qǐng)?jiān)谀愕?API 主體 聲明中添加注解 要求選擇加入的注解。這可以讓你使用帶有此注解的 API 元素。

// 庫(kù)代碼 @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 // 錯(cuò)誤:DateProvider 要求選擇加入 // ... } @MyDateTime fun getDate(): Date { val dateProvider: DateProvider // OK:該函數(shù)也需要選擇加入 // ... } fun displayDate() { println(getDate()) // 錯(cuò)誤:getDate() 需要選擇加入 }

如本例所示，帶注釋的函數(shù)看起來(lái)是 @MyDateTime API 的一部分。因此，這種選擇加入會(huì)將選擇加入的要求 傳播到客戶端代碼;其客戶將看到相同的警告消息，并且也必須同意。要使用多個(gè)需要選擇加入的API，請(qǐng)?jiān)诼暶髦袠?biāo)記所有需要選擇加入的注解

非傳播的用法

在不公開(kāi)其自身API的模塊(例如應(yīng)用程序)中，你可以選擇使用 API 而無(wú)需將選擇加入的要求傳播到代碼中。這種情況下，請(qǐng)使用 @OptIn 標(biāo)記你的聲明，并以要求選擇加入的注解作為參數(shù)

// 庫(kù)代碼 @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:不要求選擇加入 }

當(dāng)有人調(diào)用函數(shù) getDate() 時(shí)，不會(huì)通知他們函數(shù)主體中使用的選擇加入 API 的要求。

要在一個(gè)文件的所有函數(shù)和類中使用要求選擇加入的 API，請(qǐng)?jiān)谖募捻敳?，文件包說(shuō)明和導(dǎo)入聲明前添加文件級(jí)注釋 @file:OptIn

//客戶端代碼 @file:OptIn(MyDateTime::class)

模塊范圍的選擇加入

如果你不想在使用要求選擇加入 API 的每個(gè)地方都添加注解，則可以為整個(gè)模塊選擇加入這些 API。要選擇在 模塊中使用 API，請(qǐng)使用參數(shù) -Xopt-in 進(jìn)行編譯，使用 -Xopt-in = org.mylibrary.OptInAnnotation 指定該 API 使用的要求選擇加入注解的標(biāo)準(zhǔn)名稱。使用此參數(shù)進(jìn)行編 譯的效果與模塊中每個(gè)聲明都有注解 @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 模塊是多平臺(tái)模塊，請(qǐng)使用 useExperimentalAnnotation 方法

sourceSets { all { languageSettings { useExperimentalAnnotation('org.mylibrary.OptInAnnotation') } } }sourceSets { all { languageSettings.useExperimentalAnnotation("org.mylibrary.OptInAnnotation") } }

對(duì)于 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>

要在模塊級(jí)別選擇加入多個(gè) API，請(qǐng)為每個(gè)要求選擇加入的 API 添加以上描述的參數(shù)之一

要求選擇加入 API

要求選擇加入的注解

如果想獲得使用者使用你的模塊 API 的明確同意，請(qǐng)創(chuàng)建一個(gè)注解類，作為_(kāi)要求選擇加入的注解_。這個(gè)類必須 使用 @RequiresOptIn 注解:

@RequiresOptIn @Retention(AnnotationRetention.BINARY) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION) annotation class MyDateTime

要求選擇加入的注解必須滿足以下幾個(gè)要求:

— BINARY retention
　　　　— targets中沒(méi)有 EXPRESSION 與 FILE

— 沒(méi)有參數(shù)

選擇加入的要求可以具有以下兩個(gè)嚴(yán)格級(jí)別之一:

— RequiresOptIn.Level.ERROR 。選擇加入是強(qiáng)制性的。否則，使用標(biāo)記 API 的代碼將無(wú)法編譯。默認(rèn)級(jí)別。

— RequiresOptIn.Level.WARNING 。選擇加入不是強(qiáng)制性的，而是建議使用的。沒(méi)有它，編譯器會(huì)發(fā)出警告。

要設(shè)置所需的級(jí)別，請(qǐng)指定 @RequiresOptIn 注解的 level 參數(shù)

另外，你可以提供一個(gè) message 來(lái)通知用戶有關(guān)使用該 API 的特定條件。編譯器會(huì)將其顯示給使用該 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ā)布了多個(gè)需要選擇加入的獨(dú)立功能，請(qǐng)為每個(gè)功能聲明一個(gè)注解。這使你的用戶可以更安全地使用 API:他們只能使用其明確接受的功能。這也使你可以獨(dú)立地從功能中刪除選擇加入的要求

標(biāo)記 API 元素

要在使用 API 時(shí)要求選擇加入，請(qǐng)給它的聲明添加要求選擇加入的注解

@MyDateTime class DateProvider @MyDateTime fun getTime(): Time {}

穩(wěn)定前 API 的選擇加入要求

如果要求選擇加入尚未穩(wěn)定的特性，請(qǐng)仔細(xì)處理 API 由實(shí)驗(yàn)狀態(tài)到穩(wěn)定狀態(tài)的轉(zhuǎn)換，以避免破壞客戶端代碼。

當(dāng)穩(wěn)定前 API 穩(wěn)定之后并以穩(wěn)定狀態(tài)發(fā)布后，請(qǐng)從聲明中刪除其要求選擇加入的注解?？蛻舳藢⒖梢圆皇芟拗?地使用它們。但是，你應(yīng)該將注解類留在模塊中，以便與現(xiàn)有的客戶端代碼保持兼容。

為了讓 API 用戶相應(yīng)地更新其模塊(從代碼中刪除注解并重新編譯)，請(qǐng)將注解標(biāo)記為 @Deprecated 并在棄 用 message 中提供說(shuō)明

@Deprecated("This opt-in requirement is not used anymore. Remove its usages from your code.") @RequiresOptIn annotation class ExperimentalDateTime

選擇加入要求的實(shí)驗(yàn)狀態(tài)

選擇加入要求的機(jī)制在 Kotlin 1.3 中是實(shí)驗(yàn)性的。這意味著在將來(lái)的版本中，可能會(huì)以不兼容的方式進(jìn)行更改。

為了讓使用注解 @OptIn 和 @RequiresOptIn 的用戶了解其實(shí)驗(yàn)狀態(tài)，編譯器會(huì)在編譯代碼時(shí)發(fā)出警告:

This class can only be used with the compiler argument '-Xopt- in=kotlin.RequiresOptIn'

要移除警告，請(qǐng)?zhí)砑泳幾g器參數(shù) -Xopt-in=kotlin.RequiresOptIn 。

當(dāng)前題目：kotlin更多語(yǔ)言結(jié)構(gòu)——&gt;選擇加入要求-創(chuàng)新互聯(lián)
標(biāo)題URL：http://muchs.cn/article10/dejido.html

成都網(wǎng)站建設(shè)公司_創(chuàng)新互聯(lián)，為您提供靜態(tài)網(wǎng)站、營(yíng)銷型網(wǎng)站建設(shè)、網(wǎng)站營(yíng)銷、ChatGPT、域名注冊(cè)、網(wǎng)站排名

廣告

聲明：本網(wǎng)站發(fā)布的內(nèi)容（圖片、視頻和文字）以用戶投稿、用戶轉(zhuǎn)載內(nèi)容為主，如果涉及侵權(quán)請(qǐng)盡快告知，我們將會(huì)在第一時(shí)間刪除。文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng)，如需處理請(qǐng)聯(lián)系客服。電話：028-86922220；郵箱：631063699@qq.com。內(nèi)容未經(jīng)允許不得轉(zhuǎn)載，或轉(zhuǎn)載時(shí)需注明來(lái)源： 創(chuàng)新互聯(lián)