Android API 个库的 Android 级注释

Question

我正在编写一个 Android 库。 lbirary 中的绝大多数接口都支持 Android API 级别 10 或更高级别。但是，某些功能需要更高的 API 级别。例如，部分库需要 API 18 用于低功耗蓝牙。

为了具体起见，假设库产生三个 classes ClassA、ClassB 和 ClassC。 ClassA 使用 API 10 中可用的功能，ClassB 使用 API 14 中可用的功能，ClassC 使用 API 18 中可用的功能。

我希望能够在有人使用我的库中的 class 而他们的项目中没有所需的 API 级别时触发 lint 问题 (warning/error)（除非他们使用适当的注释抑制警告），类似于 lint 使用的已经内置的 NewApi 问题。

经过搜索，我找到了以下可能的解决方案：

1) 此解决方案不符合 lint 的要求：将库拆分为三个 .jar 文件，例如 lib_10.jar，其中包括使用 [=68= 中可用功能的所有 classes ] 10（示例中的 A 类），lib_14.jar 包括使用 API 中可用功能的所有 class 14（示例中的 ClassB）和 lib_18.jar 包括所有 classes 使用 API 18 中可用的功能（示例中的 ClassC）。该解决方案允许可移植性，但会使代码库的后期可维护性复杂化，并且可能还需要一些代码重复。

2) 创建我自己的注释（例如，@RequireAndroidApi(API_LEVEL) 指示注释的 class/method/etc... 所需的最低 API 级别）并使用 lint-api.jar ( http://tools.android.com/tips/lint-custom-rules) 创建自定义 lint 规则，检查任何带注释的 classes/methods/etc... 的使用情况 API 低于要求。以后看起来像这样的东西：

@RequireAndroidApi(10)
Class ClassA {
}

@RequireAndroidApi(14)
Class ClassB {
}

@RequireAndroidApi(18)
Class ClassC {
}

问题是我找不到关于 lint API 的好的文档，这似乎是在重新发明 lint 已经支持的功能（lint 已经检查了 "NewApi" 问题）。

3) 最后，我成功编辑了<SDK>/platform-tools/api/api-versions.xml，以表明每个class所需的API等级如下：

<api version="1">
    ...
    <class name="package/path/ClassA" since="10">
        <extends name="java/lang/Object" />
        <method name="&lt;init>()V" />
    </class>
    <class name="package/path/ClassB" since="14">
        <extends name="java/lang/Object" />
        <method name="&lt;init>()V" />
    </class>
    <class name="package/path/ClassC" since="18">
        <extends name="java/lang/Object" />
        <method name="&lt;init>()V" />
    </class>
</api>

这导致 lint 以与 Android APIs 相同的方式触发 NewApi 问题。我喜欢这种类型的解决方案，因为它不会重新发明轮子，而且以这种方式抛出的任何错误都会利用 Eclipse 或 Android Studio 中编程的建议解决方案来处理问题（即 Eclipse 中的 "quick fixes" ).这个解决方案的问题是它需要编辑 Android SDK 附带的 api-versions.xml，这使得这个解决方案对于发布库来说不是很便携，原因包括：a) api-versions.xml文件不是项目的本地文件，它会更改所有 android 项目的 lint 行为，包括那些不使用该库的项目；和 b) api-versions.xml 每次从 Android SDK 管理器更新 SDK 时都会被覆盖，这将覆盖所做的任何更改。

我想知道是否有更简单的解决方案来实现这个 "minimum API errors/warnings" 或者是否有办法编写一个类似于 api-versions.xml 的单独文件，该文件可以放在项目目录中，可以只要 lint 在相关项目上运行（类似于 lint.xml），就会被 lint 读取。

感谢您在如此长的问题描述过程中耐心等待，感谢您提前提供的帮助。

Answer 1

我最近在自定义视图 class 上完成了此操作，某些 api 关卡需要特殊的构造函数。

我已经用 @TargetApi 注释完成了。

如果方法仅在 api 级别 16 之后可用：

@TargetApi(16)
public void someMethod () {}

这应该可以解决问题，包括 lint 错误。

Answer 2

无需创建您自己的注释，android 支持库的 @RequiresApi 注释正是您所需要的。例如：

@RequiresApi(Build.VERSION_CODES.LOLLIPOP)
public void someMethod() {}

如果在可能具有较低 API 级别的上下文中使用 someMethod()，此注释告诉 lint 发出警告。

请注意，@TargetApi 是不同的：它用于确保 linter 只会使用目标 API 调用带注释的方法，否则它会警告您不要使用那个方法。因此 @TargetApi 可用于消除 @RequiresApi.

触发的 lint 警告

Android API 个库的 Android 级注释

Android API level annotation for Android libraries

android

android-sdk-tools

android-lint