使用 Kanzi Android framework (droidfw) 项目进行工作¶

将 Kanzi Android framework (droidfw) 添加到 Android 应用程序¶

要将 Kanzi Android framework (droidfw) 添加到使用 Android Studio 模板创建的 Android 应用程序，可以采用以下任一方式：

将 Kanzi 作为库子项目集成。这是在 Android 上开始使用 Kanzi 的推荐方法。请参阅将 Kanzi 作为库子项目集成。
将 Kanzi 作为预构建库集成。如果这种分离方式符合您工作流程的要求，请使用此方法。例如，如果您能从无需安装 Kanzi 或所需工具中获益。请参阅将 Kanzi 作为预构建库 (AAR) 集成。

将 Kanzi 作为库子项目集成¶

小技巧

这是在 Android 上开始使用 Kanzi 的推荐方法。

将 Kanzi 作为库子项目集成时，您需要将 Kanzi CMake 集成作为 Android 库子项目添加到应用程序中。

要将 Kanzi 作为库子项目集成：

从 <KanziWorkspace>/Templates/Android_library 目录将以下内容复制到您的 Android 工程的根目录：
- getkanzi.gradle 文件
- kanzinative 目录
在您的工程的 settings.gradle 或 settings.gradle.kts 文件中添加：
Groovy
dependencyResolutionManagement { repositories { flatDir { apply from: 'getkanzi.gradle' dirs getKanziAndroidLibrariesPath() } } }
Kotlin-DSL
dependencyResolutionManagement { repositories { flatDir { apply(from ="getkanzi.gradle") dirs(extra.get("getKanziAndroidLibrariesPath")) } } }
此实用工具可帮助您的工程从本地 Kanzi 安装或平台包中查找 Kanzi 库。

您可以选择：
- 将您的工程保存在 Kanzi 工作区目录中
- 将 KANZI_HOME 环境变量指向您的 Kanzi 工作区
- 在您的工程的 local.properties 中，将 kanzi.home 属性设置为您的 Kanzi 工作区或平台包
- 从您自己的位置或存储库包含 Kanzi 库
要将 kanzinative 作为子工程包含，请在您的工程的 settings.gradle 或 settings.gradle.kts 文件中添加：
Groovy
include ':kanzinative'
Kotlin-DSL
include(":kanzinative")

要使应用程序依赖于预构建的 Kanzi Android 库和 kanzinative 子项目，请在项目的 app/build.gradle 或 app/build.gradle.kts 文件中添加：

Groovy

dependencies {
  implementation 'com.rightware.kanzi:kanziruntime-droidfw@aar'
  implementation 'com.rightware.kanzi:kzjava@aar'
  implementation project(':kanzinative')
}

Kotlin-DSL

dependencies {
  implementation("com.rightware.kanzi:kanziruntime-droidfw@aar")
  implementation("com.rightware.kanzi:kzjava@aar")
  implementation(project(":kanzinative"))
}

在项目的 app/build.gradle 或 app/build.gradle.kts 文件中，确保将 Java 语言版本设置为 11 或更高版本：

Groovy

android {
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_11
       targetCompatibility JavaVersion.VERSION_11
    }
}

Kotlin-DSL

android {
    compileOptions {
       sourceCompatibility = JavaVersion.VERSION_11
       targetCompatibility = JavaVersion.VERSION_11
    }
}

将 Kanzi 作为预构建库 (AAR) 集成¶

在此模式下，您只需将 C++ 库（包括所需的 C++ 插件）链接到 AAR 中一次，然后即可在各个应用程序项目中重复使用该 AAR。

这意味着：

只要能够从包管理系统或版本控制中获取预构建的 Kanzi AAR，构建应用程序项目时就无需访问 Kanzi 工作区或平台包。
构建应用程序项目时不执行 C++ 构建，因此不需要 NDK 或 CMake。这可以加快应用程序的构建速度。

如果这种分离方式符合您工作流程的要求，请使用此方法。例如，如果您在构建应用程序项目时能从无需安装 Kanzi 或所需工具中获益。

实例化库项目¶

将 <KanziWorkspace>/Templates/Android_library 目录复制到您要使用的位置。

从库构建 AAR¶

要为所有构建配置构建并安装 AAR 库，请运行：

gradlew installNativeAARs

要为某一个构建配置构建并安装 AAR，请使用 install<Configuration>NativeAAR 任务。例如，要构建 AAR 的调试版本，请运行：

gradlew installDebugNativeAAR

默认情况下，生成的 AAR 包含适用于所有可用架构的 Kanzi C++ 库。所有 install 任务都支持 arch 属性，您可以使用该属性指定以逗号分隔的 ABI 列表。例如，要为 x86_64 架构构建并安装调试 AAR 库，请运行：

gradlew installDebugNativeAAR -Parch=x86_64

这些任务的默认定义会将名为 kanzinative-<configuration>.aar 的 AAR 安装到 Kanzi Android 库目录。

要更改 AAR 的名称，您可以采用以下任一方式：

在项目的 local.properties 中设置 kanzi.aar.name 属性。
在执行安装 task 时设置 aarName 属性。

例如，要构建并安装名为 my-kanzi-aar 的 AAR 库，请运行：
```
gradlew installNativeAARa -PaarName=my-kanzi-aar
```

要更改 install 任务存放 AAR 库的位置，您可以采用以下任一方式：

在项目的 local.properties 中设置 kanzi.aar.destination 属性。
在执行安装 task 时设置 aarDest 属性。

例如，要将 AAR 库构建并安装到 C:/MyKanziWorkspace，请运行：
```
gradlew installNativeAARa -PaarDest=C:/MyKanziWorkspace
```

将 Kanzi 导入应用程序项目¶

要将 Kanzi 导入应用程序项目：

使用您所用的包管理系统，使 Android 项目能够获取 Kanzi 预构建 AAR 库和原生 AAR 库。

例如，要从默认的 Kanzi 工作区和原生 AAR 库的默认安装位置导入 Kanzi：
1. 从 <KanziWorkspace>/Templates/Android_library 目录中，将 getkanzi.gradle 文件复制到 Android 工程的根目录。
2. 在您的工程的 settings.gradle 或 settings.gradle.kts 文件中添加：
  Groovy
  dependencyResolutionManagement { repositories { flatDir { apply from: 'getkanzi.gradle' dirs getKanziAndroidLibrariesPath() } } }
  Kotlin-DSL
  dependencyResolutionManagement { repositories { flatDir { apply(from ="getkanzi.gradle") dirs(extra.get("getKanziAndroidLibrariesPath")) } } }
此实用工具可帮助您的工程从本地 Kanzi 安装或平台包中查找 Kanzi 库。

您可以选择：
- 将您的工程保存在 Kanzi 工作区目录中
- 将 KANZI_HOME 环境变量指向您的 Kanzi 工作区
- 在您的工程的 local.properties 中，将 kanzi.home 属性设置为您的 Kanzi 工作区或平台包
- 从您自己的位置或存储库包含 Kanzi 库

将 Kanzi 预构建 AAR 以及您从 library 工程构建的原生 AAR 导入到工程的 app/build.gradle 或 app/build.gradle.kts 文件中。

Groovy

dependencies {
  implementation 'com.rightware.kanzi:kanziruntime-droidfw@aar'
  implementation 'com.rightware.kanzi:kzjava@aar'

  debugImplementation 'com.rightware.kanzi:kanzinative-debug@aar'
  releaseImplementation 'com.rightware.kanzi:kanzinative-release@aar'
  "profilingImplementation"('com.rightware.kanzi:kanzinative-profiling@aar')
}

Kotlin-DSL

dependencies {
  implementation("com.rightware.kanzi:kanziruntime-droidfw@aar")
  implementation("com.rightware.kanzi:kzjava@aar")

  debugImplementation("com.rightware.kanzi:kanzinative-debug@aar")
  releaseImplementation("com.rightware.kanzi:kanzinative-release@aar")
  "profilingImplementation("com.rightware.kanzi:kanzinative-profiling@aar")
}

在项目的 app/build.gradle 或 app/build.gradle.kts 文件中，确保将 Java 语言版本设置为 11 或更高版本：

Groovy

android {
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_11
       targetCompatibility JavaVersion.VERSION_11
    }
}

Kotlin-DSL

android {
    compileOptions {
       sourceCompatibility = JavaVersion.VERSION_11
       targetCompatibility = JavaVersion.VERSION_11
    }
}

将 Kanzi Studio 工程资产添加到您的应用程序¶

要将 Kanzi Studio 资产添加到您的 Android 应用程序：

使用以下方式之一，将 Kanzi Studio 工程资产（例如 kzb 和 cfg 文件）导入到您的 Android Studio 工程中：
- 在您的 Android Studio 工程的 app/build.gradle 或 app/build.gradle.kts 中，设置指向您的 Kanzi Studio 工程的 <ProjectName>/Application/bin 目录的路径：
  Groovy
  android { defaultConfig { sourceSets { main { assets.srcDirs = "<ProjectName>/Application/bin" } } } }
  Kotlin-DSL
  android { defaultConfig { sourceSets.named("main") { assets.srcDirs("<ProjectName>/Application/bin") } } }
- 将 Kanzi Studio 工程的 <ProjectName>/Application/bin 目录中的内容复制到 Android Studio 工程的 app/src/main/assets 目录中。
- 在 Kanzi Studio 中，在 Project > Properties 中将 Kanzi Studio 工程的 Binary Export Directory 属性设置为 Android Studio 工程的 app/src/main/assets 目录。
  
  这样即可告知 Kanzi Studio 将工程的 kzb 文件导出到何处。
  
  备注
  
  Kanzi Studio 不会导出 application.cfg 文件。请手动将该文件复制到 Android Studio 工程的 app/src/main/assets 目录中。

禁用对所导入资产文件的压缩，以便 Kanzi Engine 能够加载这些文件。在工程的 app/build.gradle 或 app/build.gradle.kts 文件中添加：

Groovy

android {
  aaptOptions {
    noCompress "kzb", "cfg", "json"
  }
}

Kotlin-DSL

android {
  androidResources {
    noCompress += listOf("kzb", "cfg", "json")
  }
}

在 Kanzi Studio 中创建一个 Android 应用程序。¶

要在 Kanzi Studio 中创建 Android 应用程序，请在 Quick Start 窗口的 New 选项卡中：

选择要用于 Android 应用程序的工程模板：
- Android application 模板创建一个包含 Kanzi Android 框架应用程序的 Kanzi Studio 项目。
- Android application with Java plugin 模板创建一个 Kanzi Studio 工程，其中包含一个基于 Kanzi Android 框架、带有 Kanzi Engine Java 插件的应用程序。
  
  请参阅使用模板创建一个 Java Kanzi Engine 插件。和使用 Java 和 Kotlin。
（可选）将 Android Package Name 设置为项目的 Android 包名称。
单击 Create。

Kanzi Studio 会在您于 Quick Start 窗口的 New 选项卡中的 Location 所设置的工程目录中创建工程，并在 <ProjectName>/Application/configs/platforms/android_gradle 目录中创建 Android 应用程序工程。

要了解如何构建和部署您的应用程序，请参阅将 Kanzi 应用程序部署到 Android。

从自定义位置加载 kzb 文件¶

默认情况下，Kanzi 从 APK 的 assets 目录中读取 kzb 文件。

要设置不同的位置，请调用 KanziRuntime.setResourceDirectory。

在此调用之后，Kanzi 从应用程序的所有视图中指定的位置读取 kzb 文件。

例如，要从外部存储目录加载 kzb 文件：

mRuntimeRef.get().setResourceDirectory(Environment.getExternalStorageDirectory().toPath());

要恢复到默认位置，请使用空字符串调用接口。