创建 Android 库 (original) (raw)

Android 库的结构与 Android 应用模块的结构相同。它为构建应用提供了所需的一切，包括源代码、资源文件和 Android 清单。

不过，Android 库将编译为您可以用作 Android 应用模块依赖项的 Android ARchive (AAR) 文件，而不是编译为在设备上运行的 APK。与 JAR 文件不同，AAR 文件会为 Android 应用提供以下功能：

库模块在以下情况下非常有用：

无论在哪种情况下，您都只需将想要重复使用的文件移到库模块中，然后将库添加为每个应用模块的依赖项。

本页介绍了如何创建和使用 Android 库模块。如需有关如何发布库的指导，请参阅发布库

创建库模块

若要在您的项目中创建新的库模块，请按以下步骤操作：

  1. 依次点击 File > New > New Module。
  2. 在随即显示的 Create New Module 对话框中，依次点击 Android Library 和 Next。
    还有一个用于创建 Kotlin 或 Java 库的选项，它可以构建传统的 JAR 文件。虽然 JAR 文件对很多项目（尤其是当您想与其他平台共享代码时）都很有用，但它不允许您包含 Android 资源或清单文件，而要在 Android 项目中重复使用代码，Android 资源和清单文件是非常有用的。本指南侧重于介绍如何创建 Android 库。
  3. 为您的库命名，并为库中的代码选择一个最低 SDK 版本，然后点击 Finish。

在 Gradle 项目同步完毕后，库模块会显示在左侧的 Project 窗格中。如果您没看到新模块文件夹，请确保窗格当前显示的是 Android 视图。

将应用模块转换为库模块

如果现有的应用模块包含您想重复使用的代码，您可以按照以下步骤将其转换为库模块：

  1. 如果您使用的是 Groovy，请打开模块级 build.gradle 文件；如果您使用的是 Kotlin 脚本，请打开 build.gradle.kts 文件。
  2. 删除 applicationId 行。只有 Android 应用模块才能定义此行。
  3. 在文件的顶部找到“plugins”代码块，如下所示：

Groovy

plugins {
id 'com.android.application'
}

Kotlin

plugins {
id("com.android.application")
}

将其更改为以下代码：

Groovy

plugins {
id 'com.android.library'
}

Kotlin

plugins {
id("com.android.library")
} 4. 保存文件，然后依次点击 File > Sync Project with Gradle Files。

模块的结构保持不变，但现在它会作为 Android 库运行。build 会创建 AAR 文件，而不是 APK。

如果您想构建 AAR 文件，请在 Project 窗口中选择库模块，然后依次点击 Build > Build APK。

使用“Project Structure”对话框添加依赖项

您可以使用 Project Structure 对话框向项目中添加依赖项。以下部分介绍了如何使用该对话框添加依赖项。

在同一个项目中使用您的库

如需在同一项目中的另一个应用或库模块中使用新的 Android 库代码，请添加一个项目级依赖项：

  1. 依次选择 File > Project Structure > Dependencies。
  2. 选择要添加库的模块。
  3. 在 Declared Dependencies 标签页中，点击 ，然后从菜单中选择 Module Dependencies。
  4. 在 Add Module Dependency 对话框中，选择您的库模块。
    在“Project Structure”对话框中添加模块依赖项
  5. 选择那个需要此依赖项的配置，或选择 implementation（如果库适用于所有配置），然后点击 OK。

Android Studio 会修改模块的 build.gradle 或 build.gradle.kts 文件，以便按以下方式添加依赖项：

Groovy

implementation project(path: ":example-library")

Kotlin

implementation(project(":example-library"))

在其他项目中使用您的库

建议使用 Maven 制品库共享依赖项（JAR 和 AAR），Maven 制品库或者托管在 Maven Central 等服务上，或者以目录结构的形式存储在本地磁盘上。如需详细了解如何使用 Maven 制品库，请参阅远程仓库。

将 Android 库发布到 Maven 制品库时，元数据将会包含在内，这样库的依赖项将包含到正在使用的 build 中，这允许在多个位置使用库时自动删除重复信息。这样，如果库在多个位置使用，系统会自动删除重复信息。

如需在不同项目所含的另一个应用模块中使用您的 Android 库代码，请按以下步骤操作：

  1. 依次选择 File > Project Structure > Dependencies。
  2. 在 Declared Dependencies 标签页中，点击 ，然后在菜单中选择 Library Dependencies。
  3. 在 Add Library Dependencies 对话框中，使用搜索框查找要添加的库。此表单会在 settings.gradle 或 settings.gradle.kts 文件的 dependencyResolutionManagement { repositories {...}} 代码块中搜索指定的代码库。
    在“Project Structure”对话框中添加库依赖项
  4. 选择那个需要此依赖项的配置，或选择 implementation（如果库适用于所有配置），然后点击 OK。

检查应用的 build.gradle 或 build.gradle.kts 文件，确认是否显示了与下方示例类似的声明（具体取决于您选择的 build 配置）：

Groovy

implementation 'com.example:examplelibrary:1.0.0'

Kotlin

implementation("com.example:examplelibrary:1.0.0")

将 AAR 或 JAR 文件添加为依赖项

如需在另一个应用模块中使用您的 Android 库代码，请按以下步骤操作：

  1. 依次选择 File > Project Structure > Dependencies。
  2. 在 Declared Dependencies 标签页中，点击 ，然后在菜单中选择 Jar Dependency。
  3. 在 Add Jar/Aar Dependency 对话框中，输入 AAR 或 JAR 文件的路径，然后选择要应用依赖项的配置。如果库应适用于所有配置，请选择 implementation 配置。
    在“Project Structure”对话框中添加 AAR 依赖项
    检查应用的 build.gradle 或 build.gradle.kts 文件，确认是否显示了与下方示例类似的声明（具体取决于您选择的 build 配置）：

Groovy

implementation files('my_path/my_lib.aar')

Kotlin

implementation(files("my_path/my_lib.aar"))

如需导入在 Android Studio 之外运行的 Gradle build 的依赖项，请在应用的 build.gradle 或 build.gradle.kts 文件中添加该依赖项的路径。例如：

Groovy

dependencies { implementation fileTree(dir: "libs", include: [".jar", ".aar"]) }

Kotlin

dependencies { implementation(fileTree(mapOf("dir" to "libs", "include" to listOf(".jar", ".aar")))) }

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

声明公开资源

资源包括您项目的 res/ 目录中的所有文件，例如图像。库中的所有资源在默认情况下均处于公开状态。如需将所有资源隐式设为私有，您必须至少将一个特定属性定义为公开。

如需声明公开资源，请向库的 public.xml 文件添加 <public> 声明。如果您之前未添加过公开资源，则需要在库的 res/values/ 目录中创建 public.xml 文件。

以下示例代码会创建两个名称分别为 mylib_app_name 和 mylib_public_string 的公开字符串资源：

为了防止库的用户访问仅供内部使用的资源，请通过声明一个或多个公开资源的方式来使用这种自动私有标识机制。您也可以通过添加空的 <public /> 标记将所有资源设为私有。此标记不会将任何资源设为公开，而是会将所有资源都设为私有。

凡是您希望对使用您的库的开发者可见的资源，都应设为公开。

将属性隐式设为私有可防止库用户收到来自内部库资源的代码补全建议，并可让用户重命名或移除私有资源而不破坏库的客户端。系统会从代码补全中过滤掉私有资源，并且 lint 工具会在您尝试引用私有资源时发出警告。

在构建库时，Android Gradle 插件会获取公开资源定义，并将其提取到 public.txt 文件中，然后系统会将此文件打包到 AAR 文件中。

库模块开发注意事项

在开发库模块和相关应用时，请注意以下行为和限制。

Groovy

android {
defaultConfig {
consumerProguardFiles 'lib-proguard-rules.txt'
}
...
}

Kotlin

android {
defaultConfig {
consumerProguardFiles("lib-proguard-rules.txt")
}
...
}
不过，如果库模块是要编译到 APK 中的多模块构建的一部分，并且不会生成 AAR，请只在使用相应库的应用模块上运行代码缩减。如需详细了解 ProGuard 规则及其用法，请参阅缩减、混淆处理和优化应用。

AAR 文件详解

AAR 文件的文件扩展名为 .aar，Maven 工件类型也是 aar。此文件本身是一个 ZIP 文件。唯一的必需条目是 /AndroidManifest.xml。

AAR 文件还可包含以下一个或多个可选条目：