绑定 Java 库

Android 社区提供很多你可能需要在应用中使用的 Java 库。 这些 Java 库通常以 .JAR（Java 存档）或 .AAR（Android 存档）格式打包，但你可以将 .JAR 或 .AAR 打包在 Java 绑定库 中，以便其功能可用于 .NET for Android 应用程序。 Java 绑定库的目的是通过自动生成的代码包装器，使 .JAR/.AAR 文件中的 API 可以被 C# 代码使用。

操作指南

在本演练中，我们将绑定 CircleImageView 的版本 3.1.0 ，该库在圆形画布中显示图像。

从Maven 存储库下载并绑定到本地存储。

创建绑定库

首先，新建一个 Bindings Library 项目。 这可以通过 Visual Studio dotnet 中提供的“Android Java 绑定库”项目模板或通过命令行完成：

dotnet new android-bindinglib

将 circleimageview-3.1.0.aar 文件复制到项目目录中。

与 .NET SDK 样式项目类似，.NET for Android 绑定项目会自动将项目目录中的任何 .JAR/.AAR 文件作为 AndroidLibrary 类型文件包含在内，因此不需要额外的配置。

现在，使用 Visual Studio 的“生成”命令或从命令行生成项目：

dotnet build

此 Java 库现已绑定，可供 .NET for Android 应用程序项目引用或发布到 NuGet 以供公共使用。

其他选项

跳过托管绑定

默认情况下，任何放置在项目中的 .JAR/.AAR 文件都会生成 C# 绑定。 但是，创建 C# 绑定可能很棘手，如果您不打算从 C# 调用 Java API，则没有必要这样做。

尤其是当 Java 库只是另一个 Java 库的依赖项，不需要直接从 C# 调用时，这种情况尤其如此。 在这种情况下， Bind="false" 该属性只能包含 Java 依赖项，但不能绑定它。

<ItemGroup>
  <AndroidLibrary Update="circleimageview-3.1.0.aar" Bind="false" />
</ItemGroup>

请注意，如果使用自动导入，您需要使用Update更改自动导入的文件，而不是通过Include添加额外的副本。

Java 依赖项

Java 库可能依赖于其他 Java 库，这些库需要与应用程序打包才能使应用程序正常工作。 这个信息传统上是在 .POM 文件中提供的，您有责任确保任何所需的依赖项被正确引用，通常通过 NuGet 包或者在项目中捆绑所需的 .JAR/.AAR 文件来实现。

在 .NET 9 中，添加了 Java 依赖项验证功能。 通过提供 .POM 文件，绑定工具可帮助确保满足所有必需的 Java 依赖项。

若要为我们的演练启用 Java 依赖项验证，请确保使用的是 .NET 9+ 且项目目标是 net9.0-android 或更高。

从 Maven 存储库本地下载circleimageview-3.1.0.pom，并将其放置在项目文件夹中。 请注意，.POM 文件不会自动被检测到，因为它们需要与正确的 .JAR/.AAR 文件关联。

更新自动导入的 AndroidLibrary，以通过 Manifest 属性指定 .POM 文件的位置。 此外，指定 Java 库的 JavaArtifact 和 JavaVersion：

<!-- JavaArtifact format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidLibrary
    Update="circleimageview-3.1.0.aar"
    Manifest="circleimageview-3.1.0.pom"
    JavaArtifact="de.hdodenhof:circleimageview"
    JavaVersion="3.1.0" />
</ItemGroup>

此库是微不足道的，没有任何 Java 依赖项，但如果这样做且未满足，则会发出如下所示的错误：

error XA4241: Java dependency 'androidx.collection:collection:1.0.0' is not satisfied.
error XA4242: Java dependency 'org.jetbrains.kotlin:kotlin-stdlib:1.9.0' is not satisfied. Microsoft maintains the NuGet package 'Xamarin.Kotlin.StdLib' that could fulfill this dependency.

有关配置 Java 依赖项验证以及如何满足依赖项的其他信息，请参阅本文档。

后续步骤

• 使用元数据自定义绑定 - 演练中绑定的 Java 库非常简单，绑定工具能够自动将其完整转换为 C# API。 遗憾的是，情况往往不是这样，通常会出现编译错误。 必须使用“元数据”来修复这些错误，以手动指示绑定工具如何解决 Java 和 C# 语言之间的差异。

• 更改命名空间 - 演练中的类型最终出现在 .NET 命名空间 DE.Hdodenhof.Circleimageview中。 Java 包名称往往比 .NET 命名空间更冗长，通常更适合更改，例如 CircleImageViewLibrary 使用 AndroidNamespaceReplacement：

<ItemGroup>
  <AndroidNamespaceReplacement Include='DE.Hdodenhof.Circleimageview' Replacement='CircleImageViewLibrary' />
</ItemGroup>