Android

Slint 支持用 Rust 和 C++ 构建 Android 应用程序。 另请参见 Rust API 文档中的 android 模块。

项目设置

Rust

Slint 使用 android-activity crate 作为与 操作系统交互的接口，它以 slint::android::android_activity 的形式重新导出。

要开始，请遵循以下步骤：

首先，你的项目需要是一个 library crate。将以下内容添加到你的 Cargo.toml：

[lib]
crate_type = ["cdylib"]

toml

选择你想使用的 android-activity 版本：

[dependencies]
slint = { version = "1.18.0", features = ["backend-android-activity-06"] }

toml

无条件启用这个 feature 是安全的。

然后，在你的 lib.rs 中添加这个函数：

#[cfg(target_os = "android")]
#[unsafe(no_mangle)]
fn android_main(app: slint::android::AndroidApp) {
    slint::android::init(app).unwrap();
    let main_window = ...; // window generated by the Slint macros
    main_window.run().unwrap();
}

rs

你还可以通过把对 slint::android::init 的调用替换为 slint::android::init_with_event_listener， 来添加一个 Android 事件 （android_activity::PollEvent） 监听器。

接下来，我们将设置用于构建项目的环境。

C++

一个 Slint C++ Android 应用程序是一个标准 CMake 项目（参见 入门教程），外加一个 Android 专用的 Gradle wrapper。 C++ 代码位于项目根目录，同时适用于桌面和 Android 构建。 CMake 中唯一 Android 特有的区别是构建共享库而不是可执行文件：

if(ANDROID)
    add_library(app SHARED main.cpp)
else()
    add_executable(app main.cpp)
endif()

cmake

当使用 Android NDK 工具链配置 Slint 时，它的 CMakeLists.txt 会自动：

• 检测 Android 目标，并将 ABI 映射到正确的 Rust 目标。
• 选择 Slint 的 Android 后端和合适的渲染器。
• 将 Material 风格设为默认。

android/ 子目录包含包装 CMake 构建的 Gradle 项目：

my-app/
├── CMakeLists.txt                # Builds your app (desktop & Android)
├── main.cpp                      # Your application code
├── main.slint                    # Your Slint UI
├── android/
│   ├── build.gradle.kts          # Gradle config: SDK versions, CMake path
│   ├── settings.gradle.kts
│   ├── gradle.properties
│   └── src/main/
│       └── AndroidManifest.xml

plaintext

android/build.gradle.kts

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

android {
    namespace = "com.myproject.app"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.myproject.app"
        // API 26 (Android 8.0) is the minimum supported by the Slint Android backend.
        minSdk = 26
        targetSdk = 35

        ndk {
            // Add other ABIs as needed: "armeabi-v7a", "x86_64", "x86"
            abiFilters += "arm64-v8a"
        }
    }

    externalNativeBuild {
        cmake {
            path = file("../CMakeLists.txt")
            version = "3.22.1"
        }
    }
}

kotlin

android/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:label="My Slint App"
        android:hasCode="false">
        <activity
            android:name="android.app.NativeActivity"
            android:exported="true"
            android:configChanges="orientation|screenSize|keyboardHidden">
            <meta-data
                android:name="android.app.lib_name"
                android:value="app" />
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

xml

Note

android:value="app" 必须与 add_library(app SHARED ...) 中的 CMake 库名匹配。 不匹配会导致应用在启动时崩溃，并提示 couldn't find "libapp.so"。

Android 环境搭建

Android 开发工作流以 adb 命令行工具为中心。用它连接到 Android 设备和模拟器以上传并运行应用程序。

安装 Android 开发环境最简单的方式是下载并安装 Android Studio。在设置面板中，导航到 Android SDK 页面并安装你需要的所有 SDK 版本。我们建议使用可用的最新版本， 因为它可以配置为向后兼容更早版本的 Android。SDK Manager 可在设置的“Languages & Frameworks” > “Android SDK”中找到。

还要注意顶部的 SDK 位置；如果构建工具无法自动检测到，可能必须将此路径用于 ANDROID_HOME 环境 变量。

在 SDK Manager 中，还要安装：

• Android NDK（在“SDK Tools”选项卡下）
• CMake（在“SDK Tools”选项卡下）

设置这些环境变量，以便构建能够找到 NDK：

export ANDROID_HOME=$HOME/Android/Sdk
export ANDROID_NDK_ROOT=$ANDROID_HOME/ndk/<version>

bash

Rust 工具链

Slint 是用 Rust 编写的，因此需要 Rust 工具链才能为 Android 编译。 通过 Rust 入门指南安装 Rust，然后添加 Android 目标：

rustup target add aarch64-linux-android

bash

如果你需要支持其他 ABI，请添加其他目标：

rustup target add armv7-linux-androideabi  # armeabi-v7a
rustup target add x86_64-linux-android     # x86_64 (emulator)
rustup target add i686-linux-android       # x86 (emulator)

bash

将 platform-tools 目录添加到你的 PATH，以便 adb 工具能在命令行 中使用。

要获取当前连接到你的机器的 Android 设备、模拟器和仿真器列表，请运行

adb devices

bash

你可以通过以下方式连接到网络上的物理设备

adb connect <host>

bash

host 是设备的 IP 地址；该设备必须已启用开发模式。

虚拟设备设置

我们建议先使用虚拟设备进行开发，因为它能加快开发周期。 不过，最终你还必须在真实设备上测试，以确保界面在触摸屏上可用， 并验证外观和手感。

要创建并运行虚拟设备，请使用 Android Studio 中提供的 Virtual Device Manager。你 可以从其主界面的“More Actions”下打开它：

你可以在这里创建任意数量、配置各不相同的设备：

一个好的做法是准备一台使用你的应用所支持的最低 API 级别的设备，以及 另一台使用最新版本的设备，以确保它能在两者上运行。

运行中的虚拟设备会自动连接到 adb。

虚拟键盘

根据你选择的设备模板，这里创建的虚拟设备默认可能使用 硬件键盘，这不利于测试你的应用程序。

要解决这个问题，请点击管理器中设备旁边的三个竖点打开菜单， 选择“Show on disk”。在显示的目录中，用文本编辑器打开文件 config.ini。 找到 hw.keyboard=yes 这一行，将其改为 hw.keyboard=no，然后 保存文件。

接下来我们选择触控笔：

在键盘设置中禁用触控笔输入：

在列表中选择“Write in textfields”，然后禁用该功能。这会启用 常规的虚拟键盘。

编写你的应用程序

Rust

在你的 lib.rs 中定义主函数和 UI：

#[cfg(target_os = "android")]
#[unsafe(no_mangle)]
fn android_main(app: slint::android::AndroidApp) {
    slint::android::init(app).unwrap();
    let main_window = MainWindow::new().unwrap();
    main_window.run().unwrap();
}

rs

你还可以通过把对 slint::android::init 的调用替换为 slint::android::init_with_event_listener， 来添加一个 Android 事件 （android_activity::PollEvent） 监听器。

C++

在 Android 上，入口点是 slint_main 而不是 main。 Slint 在内部提供了实际的 android_main 入口点， 并在平台初始化后调用你的 slint_main。

要在桌面和 Android 构建之间共享一个 main.cpp，请使用预处理器守卫：

#ifdef __ANDROID__
extern "C" void slint_main()
#else
int main()
#endif
{
    auto window = MainWindow::create();
    window->run();
}

C++

构建与运行

Rust

Slint 不要求特定的工具来构建、上传和运行用 Rust 编写的 Android 应用。 应用的 activity 必须是 android.app.NativeActivity 或其子类， 因为那是 Slint 的 Android 后端所支持的 activity 类型。 本节介绍一些可以打包此类应用的常用工具。 它们都不需要 Android Studio。

cargo-apk2

cargo-apk2 会从你的 Cargo.toml 构建、签名并安装 APK， 还可以将 Java 和 Kotlin 源代码编译进去。 安装它，并在已连接的设备上运行你的应用：

cargo install cargo-apk2
cargo apk2 run --target aarch64-linux-android --lib

bash

在你的 Cargo.toml 中声明 NativeActivity：

[[package.metadata.android.application.activity]]
name = "android.app.NativeActivity"

[[package.metadata.android.application.activity.meta_data]]
name = "android.app.lib_name"

[[package.metadata.android.application.activity.intent_filter]]
actions = ["android.intent.action.VIEW", "android.intent.action.MAIN"]
categories = ["android.intent.category.LAUNCHER"]

toml

在你 Cargo.toml 的 [package.metadata.android] 表中设置额外的清单值。 可用的键请参见 cargo-apk2 README。

要构建 release APK，请运行 cargo apk2 build --target aarch64-linux-android --lib --release。 APK 随后位于 target/release/apk/。

cargo-apk

cargo-apk 会根据你的 Cargo.toml 生成 Android 清单， 包括 NativeActivity。 安装它，并在已连接的设备上运行你的应用：

cargo install cargo-apk
cargo apk run --target aarch64-linux-android --lib

bash

在你 Cargo.toml 的 [package.metadata.android] 表中设置额外的清单值。 可用的键请参见 cargo-apk README。

要构建 release APK，请运行 cargo apk build --target aarch64-linux-android --lib --release。 APK 随后位于 target/release/apk/。

cargo-ndk 与 Gradle

cargo-ndk 只构建原生库。 然后由 Gradle 或 Android Studio 像打包任何其他 Android 应用一样打包它。 使用这个方案来添加 Java 或 Kotlin 代码，或为 Google Play 构建 Android App Bundle（AAB）。

将该库构建到你的 Gradle 项目的 jniLibs 目录中：

cargo install cargo-ndk
cargo ndk -t arm64-v8a -o app/src/main/jniLibs build --release --lib

bash

在 AndroidManifest.xml 中声明一个 NativeActivity，并把 android.app.lib_name 设置为你的库名。 本页的 C++ 选项卡展示了这样一个清单， 而 Slint Viewer 是一个完整的示例。

xbuild

xbuild 可以构建 Android 和 iOS。 crates.io 上的发布版本（0.2.0）已经过时，因此请安装 git 版本：

cargo install --git https://github.com/rust-mobile/xbuild.git

bash

命令行工具名为 x。 用 x devices 列出已连接的设备。 对于 Android 设备，它会与 adb 通信，因此你用 adb 连接的设备也会出现在这里。

要构建你的项目，请导航到包含 Cargo.toml 的目录并运行

x run --device <id>

bash

其中 <id> 在 x devices 中显示为最左列，对于虚拟 Android 设备来说类似于 adb:emulator-1234。 要重新编译并测试更改，请按 ctrl-c 并再次运行相同的命令。

如果 x run 不起作用，请运行 x doctor 检查 xbuild 是否找到了它需要的所有工具。

要构建用于分发的 APK，请使用类似这样的命令

x build --platform android --arch arm64 --format apk --release

bash

APK 随后位于 target/x/release/android/<name>.apk。 运行 x build --help 查看其他格式。

C++

连接设备或启动模拟器，然后：

./gradlew installDebug

bash

这会构建原生库（Rust + C++）， 将其打包进 APK， 并安装到已连接的设备上。

Note

首次构建耗时更长，因为它会从源代码编译 Slint 和 Skia 渲染器。 得益于 Cargo 的增量编译，后续构建会更快。

查看日志

adb logcat -s "slint"

bash

Release 构建

./gradlew assembleRelease

bash

APK 位于 app/build/outputs/apk/release/。

多个 ABI

要为多个 ABI 构建，请把它们添加到 build.gradle.kts 中的 abiFilters：

ndk {
    abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64")
}

kotlin

每个 ABI 都需要安装对应的 Rust 目标， 并会触发一次单独的 Rust 编译，从而增加构建时间。

故障排除

Rust target not installed

运行 rustup target add aarch64-linux-android（或与你的 ABI 匹配的目标）。

ANDROID_NDK_ROOT not set

NDK 路径必须对 Rust 构建可用。 将其设置为环境变量，或确保已通过 Android Studio 的 SDK Manager 安装 NDK。

构建因 Skia 错误而失败

Skia 渲染器要求你的主机系统上有可用的 clang。 使用你的系统包管理器安装它。

应用在启动时崩溃

检查 adb logcat 中的错误。 常见原因：

• AndroidManifest.xml 中的库名与 CMake 目标名不匹配。
• 缺少 slint_main 函数（它必须是 extern "C"）。
• API 级别低于 26。