Annotation

公开元数据，帮助工具开发者和其他开发者了解您的应用代码。

下表列出了 androidx.annotation 组中的所有工件。

工件	稳定版	候选版	Beta 版	Alpha 版
annotation	1.6.0	-	-	-
annotation-experimental	1.4.0-dev01	-	-	-

此库的最后更新时间：2023 年 2 月 22 日

声明依赖项

如需添加 Annotation 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库。

在应用或模块的 build.gradle 文件中为所需制品添加依赖项：

Groovy

dependencies {
    implementation "androidx.annotation:annotation:1.6.0"
    // To use the Java-compatible @Experimental API annotation
    implementation "androidx.annotation:annotation-experimental:1.4.0-dev01"
}

Kotlin

dependencies {
    implementation("androidx.annotation:annotation:1.6.0")
    // To use the Java-compatible @Experimental API annotation
    implementation("androidx.annotation:annotation-experimental:1.4.0-dev01")
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.6

版本 1.6.0

2023 年 2 月 22 日

发布了 androidx.annotation:annotation:1.6.0 和 androidx.annotation:annotation-jvm:1.6.0。版本 1.6.0 中包含这些提交内容。

自 1.5.0 以来的重要变更

添加了 @RequiresExtension 注解，以表明 API 需要特定扩展 SDK 的特定版本 (I5e4fe)
将注解库转换为使用 Kotlin 多平台工具链进行构建 (I3be8d)

版本 1.6.0-rc01

2023 年 2 月 8 日

发布了 androidx.annotation:annotation:1.6.0-rc01 和 androidx.annotation:annotation-jvm:1.6.0-rc01。版本 1.6.0-rc01 中包含这些提交内容。

对于候选版本 1.6.0-rc01，Annotation 已稳定。

版本 1.6.0-dev01

2023 年 2 月 8 日

发布了 androidx.annotation:annotation-*:1.6.0-dev01。版本 1.6.0-dev01 中包含这些提交内容。

Annotation 针对开发者预览版 1.6.0-dev01 启用了 Kotlin 多平台。

版本 1.6.0-beta01

2023 年 1 月 25 日

发布了 androidx.annotation:annotation:1.6.0-beta01 和 androidx.annotation:annotation-jvm:1.6.0-beta01，这两个版本与 1.6.0-alpha01 相比没有变化。

版本 1.6.0-alpha01

2023 年 1 月 11 日

发布了 androidx.annotation:annotation-*:1.6.0-alpha01。版本 1.6.0-alpha01 中包含这些提交内容。

新功能

添加了 @RequiresExtension 注解，以表明 API 需要特定扩展 SDK 的特定版本。(I5e4fe)
将注解库转换为使用 Kotlin 多平台工具链进行构建 (I3be8d)

版本 1.5.0

2022 年 9 月 21 日

发布了 androidx.annotation:annotation:1.5.0。版本 1.5.0 中包含这些提交内容。

自版本 1.4.0 以来的重要变更

注解库已完全迁移到 Kotlin 源代码，因此支持特定于 Kotlin 的目标使用网站和其他与 Kotlin 兼容的注解功能。

版本 1.5.0-rc01

2022 年 9 月 7 日

发布了 androidx.annotation:annotation:1.5.0-rc01。版本 1.5.0-rc01 中包含这些提交内容。

与之前的 1.5.0 Beta 版本相比没有变化。

版本 1.5.0-beta01

2022 年 8 月 24 日

发布了 androidx.annotation:annotation:1.5.0-beta01。版本 1.5.0-beta01 中包含这些提交内容。

与上一个版本相比没有任何变化。API Surface 的 Beta 版已被冻结。

版本 1.5.0-alpha02

2022 年 8 月 10 日

发布了 androidx.annotation:annotation:1.5.0-alpha02。版本 1.5.0-alpha02 中包含这些提交内容。

与上个 Alpha 版相比没有变化。

版本 1.5.0-alpha01

2022 年 7 月 27 日

发布了 androidx.annotation:annotation:1.5.0-alpha01。版本 1.5.0-alpha01 中包含这些提交内容。

新功能

注解库已完全迁移到 Kotlin 源代码，因此支持特定于 Kotlin 的目标使用网站和其他与 Kotlin 兼容的注解功能。

版本 1.4.0

2022 年 6 月 15 日

发布了 androidx.annotation:annotation:1.4.0。版本 1.4.0 中包含这些提交内容。

自 1.3.0 以来的重要变更

@RestrictTo 已迁移到 Kotlin 源代码，现在支持 @file 用法网站。因此，注解库现在依赖于 Kotlin 标准库。
@ReturnThis (b/140249763)：确保相应方法的替换方法必须返回相同的实例（适用于构建器等）
@OpenForTesting (b/141539024)：标记为“open”的 Kotlin 类和方法可以添加此注解，并且 lint 将确保此类仅在单元测试中子类化（并且仅替换方法）
@DeprecatedSinceApi (b/37116481)：表示带注解的方法（或类/字段）是某个平台 API 的向后移植库的一部分，从指定的 API 级别开始将不再需要相应方法。
@EmptySuper：表示相应方法被定义为空方法，因此在替换该方法时不需要调用它（实际上，您不应调用该方法，例如，它可以包含向后兼容性检查）。

版本 1.4.0-rc01

2022 年 6 月 1 日

发布了 androidx.annotation:annotation:1.4.0-rc01。版本 1.4.0-rc01 中包含这些提交内容。

API Surface 和功能已最终确定并可以发布。

版本 1.4.0-beta01

2022 年 5 月 18 日

发布了 androidx.annotation:annotation:1.4.0-beta01。版本 1.4.0-beta01 中包含这些提交内容。

与上个 Alpha 版相比没有变化。API Surface 的 Beta 版已被锁定。

版本 1.4.0-alpha02

2022 年 2 月 9 日

发布了 androidx.annotation:annotation:1.4.0-alpha02。版本 1.4.0-alpha02 中包含这些提交内容。

新功能

添加了 @ReturnThis、@OpenForTesting、@EmptySuper 和 @DeprecatedSinceApi 注解。(21946a2)
@ReturnThis (b/140249763)：确保相应方法的替换方法必须返回相同的实例（适用于构建器等）
@OpenForTesting (b/141539024)：标记为“open”的 Kotlin 类和方法可以添加此注解，并且 lint 将确保此类仅在单元测试中子类化（并且仅替换方法）
@DeprecatedSinceApi (b/37116481)：表示带注解的方法（或类/字段）是某个平台 API 的向后移植库的一部分，从指定的 API 级别开始将不再需要相应方法。
@EmptySuper：表示相应方法被定义为空方法，因此在替换该方法时不需要调用它（实际上，您不应调用该方法，例如，它可以包含向后兼容性检查）。

版本 1.4.0-alpha01

2021 年 12 月 15 日

发布了 androidx.annotation:annotation:1.4.0-alpha01。版本 1.4.0-alpha01 中包含这些提交内容。

API 变更

将 RestrictTo 注解迁移到了 Kotlin 源代码 (Ia6336)

版本 1.3.0

2021 年 11 月 3 日

发布了 androidx.annotation:annotation:1.3.0。版本 1.3.0 中包含这些提交内容。

自 1.2.0 以来的重要变更

@Discouraged 注解：用于标记那些无法合理废弃但会对性能产生重大负面影响且不应在正常的生产代码中调用的 API
@Context 注解：用于标记通用上下文，以便开发者能够更轻松地迁移到新 API
@GravityInt 注解：用于标记包含已封装为整数的 gravity 值的元素
废弃了 @InspectableProperty，取而代之的是 @Attribute（适用于 androidx.resourceinspection）

版本 1.3.0-rc01

2021 年 10 月 27 日

发布了 androidx.annotation:annotation:1.3.0-rc01。版本 1.3.0-rc01 中包含这些提交内容。

版本 1.3.0-beta01

2021 年 9 月 29 日

发布了 androidx.annotation:annotation:1.3.0-beta01。版本 1.3.0-beta01 中包含这些提交内容。

API 变更

必须在 @Discouraged 的“message”中提供说明。(I3390f)
添加了 @Discouraged 注解，用于标记不推荐使用的元素。(Ib2549)
让 RestrictTo 注解可在 Studio 文档的弹出式窗口中显示（Ie8e1a、b/183134648）

bug 修复

添加了上下文注解以标记通用上下文，让开发者能够更轻松地迁移到新 API。(Ie581a)

版本 1.3.0-alpha01

2021 年 3 月 24 日

发布了 androidx.annotation:annotation:1.3.0-alpha01。版本 1.3.0-alpha01 中包含这些提交内容。

API 变更

废弃了 androidx.resourceinspection 中的 @InspectableProperty，取而代之的是 @Attribute。(Ic0eff)
添加了 @GravityInt 注解，用于标记包含已压缩为整数的 gravity 值的元素。（Ifcaa4、b/180620048）

Annotation-Experimental 版本 1.4

版本 1.4.0-dev01

2023 年 2 月 8 日

发布了 androidx.annotation:annotation-experimental:1.4.0-dev01。版本 1.4.0-dev01 中包含这些提交内容。

Annotation-experimental 针对开发者预览版 1.4.0-dev01 启用了 Kotlin 多平台。

Annotation-Experimental 版本 1.3.0

版本 1.3.0

2022 年 9 月 7 日

发布了 androidx.annotation:annotation-experimental:1.3.0。版本 1.3.0 中包含这些提交内容。

自 1.2.0 以来的重要变更

添加了在软件包级使用 @androidx.annotation.OptIn 的支持 (I24d58)
已将 Kotlin stdlib 依赖项转为 API 类型，而不是仅编译。这意味着 Annotation-Experimental 库的所有客户端都会在传递依赖项中添加 Kotlin 标准库。

版本 1.3.0-rc01

2022 年 8 月 24 日

发布了 androidx.annotation:annotation-experimental:1.3.0-rc01。版本 1.3.0-rc01 中包含这些提交内容。

与上一个版本相比没有任何变化。RC 的实现已被冻结。

版本 1.3.0-beta01

2022 年 8 月 10 日

发布了 androidx.annotation:annotation-experimental:1.3.0-beta01。版本 1.3.0-beta01 中包含这些提交内容。

与 Alpha 版相比没有变化。此库已经实现稳定，可用于 Beta 版。

版本 1.3.0-alpha01

2022 年 7 月 27 日

发布了 androidx.annotation:annotation-experimental:1.3.0-alpha01。版本 1.3.0-alpha01 中包含这些提交内容。

API 变更

添加了在软件包级使用 @androidx.annotation.OptIn 的支持 (I24d58)

Annotation-Experimental 版本 1.2.0

版本 1.2.0

2021 年 12 月 15 日

发布了 androidx.annotation:annotation-experimental:1.2.0。版本 1.2.0 中包含这些提交内容。

自 1.1.0 以来的重要变更

该库现在以 Java 8 语言级别为目标。

版本 1.2.0-rc01

2021 年 12 月 1 日

发布了 androidx.annotation:annotation-experimental:1.2.0-rc01。版本 1.2.0-rc01 中包含这些提交内容。

与 Beta 版相比没有任何变化。

版本 1.2.0-beta01

2021 年 11 月 17 日

发布了 androidx.annotation:annotation-experimental:1.2.0-beta01。版本 1.2.0-beta01 中包含这些提交内容。

API 变更

Beta 版的 API 已最终确定。

Annotation-Experimental 版本 1.2.0-alpha01

2021 年 6 月 30 日

发布了 androidx.annotation:annotation-experimental:1.2.0-alpha01。版本 1.2.0-alpha01 中包含这些提交内容。

新功能

该库现在以 Java 8 语言级别为目标

版本 1.2.0

2021 年 3 月 24 日

发布了 androidx.annotation:annotation:1.2.0。版本 1.2.0 中包含这些提交内容。

自 1.1.0 以来的重要变更

添加了 @ChecksSdkIntAtLeast 注解，可用于标识用于限制对 SDK 级别的访问并满足 NewApi lint 检查要求的方法和字段。
添加了 @DoNotInline 注解，其与 Proguard 规则搭配使用来防止成员在优化期间被内嵌。
各种注解现在都带有 @Documented，以确保注解会显示在有注解成员的文档中。

版本 1.2.0-rc01

2021 年 2 月 24 日

发布了 androidx.annotation:annotation:1.2.0-rc01。版本 1.2.0-rc01 中包含这些提交内容。

版本 1.2.0-beta01

2021 年 1 月 13 日

发布了 androidx.annotation:annotation:1.2.0-beta01。版本 1.2.0-beta01 中包含这些提交内容。

API 变更

新增 @DoNotInline 注解，用于指示代码优化器（例如 Proguard、R8）不要内联添加了该注解的方法。（I3dfe8、b/141326133）

版本 1.2.0-alpha01

2020 年 5 月 14 日

发布了 androidx.annotation:annotation:1.2.0-alpha01。版本 1.2.0-alpha01 中包含这些提交内容。

新功能

添加了 @ChecksSdkIntAtLeast 注解。这让用户可以为表示 SDK_INT 检查的方法和字段添加注解。（I89a54、b/120255046）

Annotation-Experimental 版本 1.1.0

版本 1.1.0

2021 年 4 月 7 日

发布了 androidx.annotation:annotation-experimental:1.1.0。版本 1.1.0 中包含这些提交内容。

自 1.0.0 以来的重要变更

使用 Kotlin 重写了 Jetpack 的实验性注解，以便支持多个 Marker 类，并改进了对废弃的处理。
添加了 RequiresOptIn 和 OptIn 注解以与 Kotlin 保持一致，并废弃了 Experimental 和 UsesExperimental 注解。

版本 1.1.0-rc02

2021 年 3 月 24 日

发布了 androidx.annotation:annotation-experimental:1.1.0-rc02。版本 1.1.0-rc02 中包含这些提交内容。

bug 修复

添加了 Proguard 规则，以确保在优化代码时不会收到有关缺少 Kotlin 元注解的警告。

版本 1.1.0-rc01

2021 年 3 月 10 日

发布了 androidx.annotation:annotation-experimental:1.1.0-rc01。版本 1.1.0-rc01 中包含这些提交内容。

自上一个 Beta 版推出以来没有任何变化。

版本 1.1.0-beta01

2021 年 1 月 27 日

发布了 androidx.annotation:annotation-experimental:1.1.0-beta01。版本 1.1.0-beta01 中包含这些提交内容。

API 变更

废弃了实验性注解的 androidx 变体，以与 Kotlin 保持一致。我们已将其替换为 RequiresOptIn 注解的 androidx 变体，并更新了面向 Java 的 linter，以支持新的 Kotlin 注解和新的 androidx 变体。（I52495、b/151331381）

版本 1.1.0-alpha01

2020 年 7 月 22 日

发布了 androidx.annotation:annotation-experimental:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

新功能

实验注解库现在用 Kotlin 编写，但不需要添加 Kotlin 标准库作为依赖项。它包含一个 Proguard 文件，如果项目只使用 Java 编程语言，可以通过该文件从项目中去掉不必要的 Kotlin 元数据。
@UseExperimental 现在支持多个 Marker 类（aosp/1185577、b/145137892）

Annotation-Experimental 版本 1.0.0

2019 年 11 月 7 日

发布了 androidx.annotation:annotation-experimental:1.0.0 和 androidx.annotation:annotation-experimental-lint:1.0.0，这两个版本与 1.0.0-rc01 相比没有变化。版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

在 Java 源代码中基于 Lint 强制执行 Kotlin @Experimental 语义
提供与 Kotlin 的 @Experimental 和 @UseExperimental 注解等效的行为的 Java 注解，而无需依赖 Kotlin

Annotation-Experimental 版本 1.0.0-rc01

2019 年 10 月 23 日

发布了 androidx.annotation:annotation-experimental:1.0.0-rc01 和 androidx.annotation:annotation-experimental-lint:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

已知问题

使用 Studio 3.5 稳定版时，该 IDE 不会针对 Java 中无效的 Kotlin @Experimental 注解用法显示来自 @Experimental 用法 lint 检测器的警告。请参阅 b/140640322。

Annotation-Experimental 版本 1.0.0-beta01

2019 年 10 月 9 日

发布了 androidx.annotation:annotation-experimental:1.0.0-beta01 和 androidx.annotation:annotation-experimental-lint:1.0.0-beta01，这两个版本与 1.0.0-alpha01 相比没有变化。版本 1.0.0-beta01 中包含这些提交内容。

Annotation-Experimental 版本 1.0.0-alpha01

2019 年 9 月 18 日

发布了 androidx.annotation:annotation-experimental:1.0.0-alpha01 和 androidx.annotation:annotation-experimental-lint:1.0.0-alpha01。前者是 annotation-experimental 1.0.0-alpha01 中包含的提交内容，后者是 annotation-experimental-lint 1.0.0-alpha01 中包含的提交内容

新功能

Jetpack 实验性注解库提供 Kotlin 实验性 API 标记的 Java 兼容实现。-lint 工件会限制使用基于 Lint 实现的实验，同时会限制 Kotlin 原生实验 API 标记对 Java 的使用。
将 annotation-experimental 工件用作依赖项时，annotation-experimental-lint 工件提供的 Lint 规则会自动强制执行。

版本 1.1.0

2019 年 6 月 5 日

发布了 androidx.annotation:annotation:1.1.0，该版本与 1.1.0-rc01 相比没有变化。

版本 1.1.0-rc01

2019 年 5 月 7 日

发布了 androidx.annotation:annotation:1.1.0-rc01，该版本与 1.1.0-beta01 相比没有变化。点击此处可查看此版本中包含的提交内容。

版本 1.1.0-beta01

2019 年 4 月 3 日

发布了 androidx.annotation:annotation:1.1.0-beta01。点击此处可查看此版本中包含的提交内容。

新功能

新增了 @InspectableProperty 注解以支持在 Android 10 中添加新的视图检查 API。可将此注解应用于视图或其他界面元素上的 getter。代码生成工具可能会用它来创建伴生对象，这些对象将属性名称和属性 ID 映射到属性值，而不会产生反射开销。

API 变更

重大变更：@ContentView 已更改为构造函数注解，并移除了 @LayoutRes 值。希望支持 @ContentView 注解的类应将此注解添加到采用 @LayoutRes int 参数的构造函数中。这一变更修复了在库模块中使用此注解时出现的问题。(b/128352521)

版本 1.1.0-alpha02

2019 年 3 月 13 日

发布了 androidx.annotation:annotation:1.1.0-alpha02。点击此处可查看此版本中包含的完整提交内容列表。

新功能

新的 API 限制范围：RestrictTo.Scope.LIBRARY_GROUP_PREFIX。它会将代码的使用限制在软件包内，这些软件包中的组在最后一个 .（句点）之前的部分使用相同的库组前缀。例如，由于库 foo.bar:lib1 和 foo.baz:lib2 具有相同的前缀 foo，因此它们可以使用彼此的限定在此范围内的 API。同样，com.foo.bar:lib1 和 com.foo.baz:lib2 具有相同的前缀 com.foo.，因此可以共享限定在该范围内的 API。不过，库 com.bar.qux:lib3 无法使用限定在该范围内的 API，因为二者只有前缀 com. 相同，最后一个 .（句点）之前的部分不完全相同。

版本 1.1.0-alpha01

2019 年 1 月 30 日

发布了 androidx.annotation:annotation 1.1.0-alpha01。

新功能

添加了 @ContentView 注解，可让您指明应膨胀哪个布局 XML 文件。ComponentActivity 的 1.0.0-alpha04 版本和 Fragment 的 1.1.0-alpha04 版本支持此功能，它们分别作为使用 setContentView() 或替换 onCreateView() 的替代方法。(aosp/837619)

版本 1.0.2

2019 年 2 月 25 日

发布了 androidx.annotation:annotation 1.0.2。

bug 修复

更正了嵌入到 jar 中的 R8/ProGuard 规则。这些规则错误地引用了旧的 android.support.annotation 类型，而不是 androidx.annotation。注意：只有在您未使用 getDefaultProguardFile 的情况下，这才会对您的 build 产生影响，因为这些默认规则还包括两个软件包的正确规则。(aosp/891685)
添加了一个 R8/ProGuard 规则，该规则会明确保留 @Keep 注解本身。这样可确保 ProGuard 在确实遵守注解的语义之前不会将注解从类型中移除。注意：只有在您未使用 getDefaultProguardFile 的情况下，这才会对您的 build 产生影响，因为这些默认规则还包括两个软件包的正确规则。(aosp/903818)