在 Kanzi Android framework (droidfw) 中使用插件¶

本页介绍如何使用添加到 Kanzi Android framework (droidfw) 应用程序中的插件。Kanzi 随附的某些 Kanzi Engine 插件（例如 Lua 插件）是可选插件，由工程的 kanzinative/build.gradle 中的 KANZI_LINK_ 选项控制。请参阅部署 Lua 插件。

使用 Kanzi Engine Java 插件¶

要了解有关创建 Kanzi Engine Java 插件的信息，请参阅创建 Kanzi Engine Java 插件。

要在您的 Android 应用程序中使用插件，可以：

在 Activity 的初始化期间加载插件。

Java

@Override
protected void onCreate(Bundle icicle)
{
    ...

    KanziRuntime.Reference runtimeRef = KanziRuntime.acquire(this);
    runtimeRef.get().getDomain().registerPlugin(new MyPlugin());

    ...
}

Kotlin

override fun onCreate(icicle: Bundle) {
    ...

    val runtimeRef = KanziRuntime.acquire(this)
    runtimeRef.get().domain.registerPlugin(new MyPlugin());

    ...
}

当您的应用程序附加使用该插件的 Kanzi 视图时，加载该插件。

Java

view.addListener(new KanziViewListener() {
   ...

   @Override
   public void onAttachedToWindow(View view, Domain domain)
   {
         domain.registerPlugin(new MyPlugin());

         ...
   }
   ...
}

Kotlin

view.addListener(object : KanziViewListener {
   ...

   override fun onAttachedToWindow(view: View, domain: Domain) {
         domain.registerPlugin(MyPlugin())

         ...
   }
   ...
}

使用 Kanzi Studio 生成的插件¶

Kanzi Studio 自动为某些功能（例如 Code Behind）生成插件，并将这些插件的注册添加到 KanziGenerated.java 文件中。

要使用这些插件，在初始化您的活动或附加您的 Kanzi 视图时，调用 KanziGenerated.registerPlugins(domain)。这类似于在使用 Kanzi Engine Java 插件中注册单个插件。

使用 Kanzi Engine C++ 插件¶

要使用 Kanzi Engine C++ 插件：

导出 Kanzi Engine 插件：
1. 在 Kanzi Studio 中打开包含插件代码的项目。
  
  例如：#. 在 Quick Start 窗口中，点击 Projects 并选择 Tutorials 选项卡。在 Data source 教程旁边，点击。#. 在 Data source 教程旁边，点击 Open 并选择 Completed project。
2. 在 Library > Build Configurations 中选择插件，并在 Properties 中设置：
  - CPU Architecture 以匹配您设备的架构。
  - 将 Build Profile 设置为您要使用的配置。
3. 选择 File > Export > Build Android Package。
  
  Kanzi Studio 在 <ProjectName>/Application/output/cmake/<PluginProjectName>/cmake/release/arm64-v8a/lib<PluginProjectName>.so 中构建 Kanzi Engine 插件。
  
  例如，如果您使用 XML 数据源插件，Kanzi Studio 在 <KanziWorkspace>/Tutorials/Data sources/Completed/Application/output/cmake/XML_data_source/cmake/release/arm64-v8a/libXML_data_source.so 中构建该插件。
将构建的 Kanzi Engine 插件添加到应用程序中：
1. 在 Kanzi Studio 中选择 File > Close All projects，并使用 Android application 模板打开或创建一个 Kanzi Studio 项目。
  
  Android application 模板创建一个包含 Kanzi Android 框架应用程序的 Kanzi Studio 项目。
2. 在 Library 中右键单击 Kanzi Engine Plugin，选择 Import Kanzi Engine Plugin，然后选择已构建插件的 dll。
  
  例如，选择 <KanziWorkspace>/Tutorials/Data sources/Completed/Application/lib/Win64/GL_vs2022_Release_DLL/XML_data_source.dll Kanzi Engine 插件。
  
  这样，您可以将 Kanzi Engine 插件添加到 Kanzi Studio 项目中。
3. 在您要向其添加此 Kanzi Engine 插件的项目的文件资源管理器中，创建此目录结构 <ProjectName>/Application/lib/Android/release/arm64-v8a。
4. 将 Kanzi Engine so 插件文件从 <ProjectName>/Application/output/cmake/<PluginProjectName>/cmake/release/arm64-v8a/lib<PluginProjectName>.so 复制到 <ProjectName>/Application/lib/Android/release/arm64-v8a 目录。
  
  例如，复制 <KanziWorkspace>/Tutorials/Data sources/Completed/Application/output/cmake/XML_data_source/cmake/release/arm64-v8a/libXML_data_source.so 文件。
5. 编辑 <ProjectName>/Application/CMakeLists.txt 文件以添加 Kanzi Engine 插件作为导入的库依赖项：
```
add_library(<PluginProjectName> SHARED IMPORTED)
set_target_properties(<PluginProjectName> PROPERTIES IMPORTED_LOCATION "${PROJECT_SOURCE_DIR}/lib/Android/release/${ANDROID_ABI}/lib<PluginProjectName>.so")
target_link_libraries(<ProjectName> <PluginProjectName>)
```
  例如，要添加 XML data source 插件，使用：
```
add_library(XML_data_source SHARED IMPORTED)
set_target_properties(XML_data_source PROPERTIES IMPORTED_LOCATION "${PROJECT_SOURCE_DIR}/lib/Android/release/${ANDROID_ABI}/libXML_data_source.so")
target_link_libraries(<ProjectName> XML_data_source)
```
  这样就将构建的本机 Kanzi Engine 插件添加到您的 Android 应用程序中。
  
  通过此 CMake 配置，您可以在构建期间将动态链接的 Kanzi Engine 插件链接到您的 Android 应用程序。这样，当您向应用程序添加具有插件依赖项的 kzb 文件时，Kanzi 能够加载该插件。
在 Kanzi Studio 中选择 File > Export > Build Android Package。

Kanzi Studio 构建并将您的应用程序部署到 Android 设备。当应用程序在您的 Android 设备上开始运行时，您可以在 logcat 中看到应用程序何时加载插件。

例如，如果您使用 XML data source 插件，logcat 显示：
```
I/Kanzi: [info:generic] Loading plugin 'libXML_data_source.so'
```
在 Kanzi Android framework (droidfw) 应用程序中使用该插件。

例如，要了解如何使用 Kanzi Engine 数据源插件，请参阅使用数据源。

将 Kanzi Engine C++ 插件代码移动到您的应用程序项目中。¶

您可以将 Kanzi Engine C++ 插件添加到 Kanzi Android framework (droidfw) 应用程序项目中。在此之后，您可以将 C++ 插件代码与应用程序代码合并。这样，您可以在单个源代码构建中同时构建插件和应用程序。

要将 Kanzi Engine C++ 插件代码移动到您的 Kanzi Android framework (droidfw) 应用程序项目中：

（可选）为确保这些说明中给出的相对路径有效，请在 <KanziWorkspace>/Projects 目录中复制您的 Kanzi Android framework (droidfw) 应用程序。
将插件 C++ 代码及其 CMakeLists.txt 复制到 <ProjectName>/Application/src/plugin 目录。

例如，要将 XML Data Source 插件代码添加到项目中，请将 <KanziWorkspace>/Tutorials/Data sources/Completed/Application/src/plugin 目录的内容复制到 <KanziWorkspace>/Projects/MyProject/Application/src/plugin 目录。

XML Data Source 插件允许 Kanzi 应用程序从 XML 文件中获取数据。要了解如何定义 XML 数据源，请参阅教程：从数据源获取应用程序数据。
将您的应用程序的 C++ 代码和 CMakeLists.txt 文件移动到 <ProjectName>/Application/src/executable 目录。

例如：在 <KanziWorkspace>/Projects/MyProject/Application/ 目录中，移动：
- 将 CMakeLists.txt 到 src/executable 目录。
- src/myproject.cpp 到 src/executable/src 目录。

在 <ProjectName>/Application/src/executable/CMakeLists.txt 文件中：

将项目名称的所有出现替换为新名称。

例如，更改
```
project(MyProject)
```
至 (To)
```
project(MyProject_executable)
```

编辑到 Kanzi 构建脚本的路径。更改

include(${CMAKE_CURRENT_LIST_DIR}/cmake/kanzi-locate.cmake)

至 (To)

include(${CMAKE_CURRENT_LIST_DIR}/../../cmake/kanzi-locate.cmake)

更新插件共享对象的路径。

例如：

add_library(XML_data_source SHARED IMPORTED)
set_target_properties(XML_data_source PROPERTIES IMPORTED_LOCATION
   "${CMAKE_CURRENT_LIST_DIR}/../../lib/android/${CMAKE_BUILD_TYPE}/${ANDROID_ABI}/libXML_data_source.so")
target_link_libraries(MyProject_executable XML_data_source)

在 <ProjectName>/Application/ 目录中，创建一个对整个项目通用的 CMakeLists.txt 文件。

例如：

cmake_minimum_required(VERSION 3.25.0)
project(MyProject)

add_subdirectory(src/plugin)
add_subdirectory(src/executable)

在 <ProjectName>/Application/configs/platforms/android_gradle/ 目录中，为插件项目创建一个目录。

例如，将 <KanziWorkspace>/Tutorials/Data sources/Completed/Application/configs/platforms/android_gradle/XML_data_source 目录复制到 <KanziWorkspace>/Projects/MyProject/Application/configs/platforms/android_gradle/ 目录。

在 <ProjectName>/Application/configs/platforms/android_gradle/app/build.gradle 文件中：

更改

externalNativeBuild {
    cmake {
        path file("$rootDir/../../../CMakeLists.txt")
    }
}

至 (To)

externalNativeBuild {
    cmake {
        path file("$rootDir/../../../src/executable/CMakeLists.txt")
    }
}

由于应用程序项目依赖于插件项目，CMake 必须先构建插件代码。要设置构建顺序，请添加 afterEvaluate 块。

例如：

afterEvaluate {
    // Make the CMake configuration task of this app depend on the build results of the
    // plugin project.
    tasks.withType(com.android.build.gradle.tasks.ExternalNativeBuildJsonTask).every { task ->
        // This example dependency assumes that the plugin project and application
        // project have the same build variant types available.
        // For example, :app:Debug -> :XML_data_source:Debug.
        task.dependsOn(":XML_data_source:externalNativeBuild${task.variantName.capitalize()}")
    }
}

在 dependencies 块中，添加对插件项目的依赖。

例如：

dependencies {
   implementation project(':XML_data_source')
   // ...
}

在 <ProjectName>/Application/configs/platforms/android_gradle/settings.gradle 文件中，包含插件项目的名称。

例如：
```
rootProject.name = "myproject"
include ":app"
include ":XML_data_source"
```

现在，您可以在 Android Studio 中同时编辑和构建 Kanzi 应用程序和 C++ 插件代码。

../../../_images/android-studio-project-droidfw-cpp-plugin-code.png

要使用更新的 Kanzi Engine 插件在 Kanzi Studio 中：

构建 Kanzi Engine 插件 DLL。请参阅使用模板创建本机 Kanzi Engine 插件。。
在 Kanzi Studio 中，更新 Kanzi Engine 插件。请参阅在项目中更新 Kanzi Engine 插件。

另请参阅¶

Kanzi Engine 插件

数据源 (Data Sources)

教程：从数据源获取应用程序数据