Android 平台说明

本页面包含有关在 Android 上构建和运行 Qt 应用程序的特定信息。有关支持的 Android 版本和 API 级别，请参阅“支持的 Android 版本”。

插件和导入的特殊注意事项

如果应用程序使用的插件依赖于其他模块，则必须将这些模块列在应用程序的依赖项中。有关更多信息，请参阅“依赖项检测”。

Qt GUI 依赖关系

鉴于 Android 应用程序通常包含 GUI 元素，Qt for Android 插件主要旨在提供 GUI 功能，因此它实现了各种 QPA 抽象。因此，部署 Qt for Android 应用程序预计将涉及对 Qt GUI。此外，值得注意的是，Qt Creator 仅支持Gradle构建和部署，这意味着默认情况下不支持命令行或Shell执行。

返回键和返回手势

在 Android 系统中，返回手势（Android 13 及以上）和系统返回键的按下操作属于导航请求，而非窗口关闭操作。如果没有项目处理返回按键，按下返回键会将应用程序移至后台。应用程序会保留其状态并从中断处恢复，而非退出。

自 Qt 6.12 起，按下返回键会通过 `Activity.moveTaskToBack() ` 将应用程序移至后台，且不再触发关闭事件。这意味着当用户按下返回键时，QWidget::closeEvent() 和Window.onClosing 信号不会被触发。如果您的应用程序依赖这些信号来拦截返回键按下事件，则应采用下文所述的 `Shortcut ` 方法。

若要在应用程序内部进行导航（例如从StackView 弹出一个页面），请处理“返回”键并接受该事件。接受该事件可阻止 Qt 将应用程序移至后台。推荐的做法是在窗口级别创建一个绑定到Back 键序列的快捷键，无论哪个项目当前处于焦点状态，该快捷键都会触发：

Shortcut {
    sequences: ["Back"]
    enabled: Qt.platform.os === "android" && stack.depth > 1
    onActivated: stack.pop()
}

在 Android 上，请使用"Back" 序列，而非StandardKey.Back 。该标准按键还绑定了Backspace 和Alt+Left ，这些操作会由硬件键盘触发。

在堆栈根部，enabled 会转换为false ，因此“返回”按键会穿透处理，Qt XML 会将应用程序送入后台。若需先提示用户有关未保存的更改，可在更改待处理时启用该快捷键，并通过onActivated 显示提示。一旦处理完更改，该快捷键即被禁用，随后再次按下“返回”按键将把应用程序送入后台。

处于焦点状态的项目也可以通过Keys.onBackPressed 处理Qt::Key_Back ，但仅限于其保持活动焦点期间。触摸驱动的界面通常不会让任何项目保持焦点，因此“返回”按键事件永远无法触达该项目。而窗口级快捷键不受焦点状态影响，因此是更安全的选择。

OpenGL 的特殊注意事项

现代设备通常除了支持 OpenGL 2.0 之外，还支持 OpenGL ES 3.0 或 3.1。要获取合适的 OpenGL 上下文，请通过QSurfaceFormat::setVersion() 设置所需版本。

已知问题

Qt Creator 调试问题

有关更多信息，请参阅Qt Creator 中的“已知问题”。

文本预测

由于某些设备上的一个错误，当您通过ImhNoPredictiveText 关闭预测文本功能时，该属性会被忽略，预测文本仍会保持启用状态。要解决此问题，请将环境变量QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT 设置为1 。但需要注意的是，此环境变量可能会对 Gboard 等其他键盘造成问题。 如果您使用日语等语言，在 Gboard 中将仅显示 QWERTY 键盘。每次显示键盘时都会查询该环境变量，因此您可以根据需要随时启用或禁用此解决方法。

文本字形缓存

由于某些 OpenGL 驱动程序存在缺陷，Qt OpenGL 用于缓存文本字形的机制在部分 Android 设备上无法按预期工作，导致文本显示混乱。为解决此问题，已实施一项临时解决方案，但该方案可能会增加内存消耗，并可能影响文本渲染性能。目前，该临时解决方案已默认应用于所有设备。

您可以通过将QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND 环境变量设置为1或true来禁用该解决方法。但在执行此操作之前，请务必确认文本在所有目标设备上均显示正确。

限制

某些 Qt 模块或工具可能包含 Android 不支持的功能，或存在功能限制。有关平台限制的详细信息，请参阅具体模块的文档。