HarmonyOS 版 Qt CMake API

注意： HarmonyOS CMake API 目前处于技术预览阶段，未来版本中可能会发生变更。

本页面列出了用于配置 Qt 应用程序如何打包为 HarmonyOS 能力包（HAP）的 CMake 命令、目标属性及变量。

当您使用qt_add_executable()创建以 HarmonyOS 为目标的 Qt 可执行文件时，Qt 会自动生成一个名为<target>_make_hap 的构建目标，该目标用于生成 HAP。下面的命令、属性和变量用于控制该 HAP 的内容以及写入 HarmonyOS 清单文件的元数据。

HarmonyOS 应用程序包由两种清单文件描述：应用级app.json5 ，其中包含适用于整个包的元数据；以及模块级module.json5 ，用于描述该包内的单个 HAP 模块。下面的目标属性反映了这种划分：QT_HARMONYOS_APP_* 属性用于设置应用级元数据（如供应商、版本、标签和图标），而QT_HARMONYOS_MODULE_DESCRIPTION和QT_HARMONYOS_ABILITY_ORIENTATION等属性则用于设置模块级元数据。完整列表请参见下文的“目标属性”部分。

命令

qt_add_harmonyos_permission()向应用程序添加一个 HarmonyOS 权限。

目标属性

以下目标属性会影响 HAP 的构建方式：

QT_HARMONYOS_ABILITY_ORIENTATION	HarmonyOS 能力的屏幕方向策略。
QT_HARMONYOS_APP_BUNDLE_NAME	HarmonyOS 应用程序的包名。
QT_HARMONYOS_APP_ICON	HarmonyOS 应用的图标。
QT_HARMONYOS_APP_LABEL	HarmonyOS 应用的标签。
QT_HARMONYOS_APP_NAME	HarmonyOS 应用的名称。
QT_HARMONYOS_APP_VENDOR	HarmonyOS 应用的供应商。
QT_HARMONYOS_APP_VERSION_CODE	HarmonyOS 应用的版本代码。
QT_HARMONYOS_APP_VERSION_NAME	HarmonyOS 应用的版本名称。
QT_HARMONYOS_COMPATIBLE_SDK_VERSION	HarmonyOS 应用的兼容 SDK 版本。
QT_HARMONYOS_COMPILE_SDK_VERSION	HarmonyOS 应用的编译 SDK 版本。
QT_HARMONYOS_EXTRA_LIBS	需随 HarmonyOS 目标一起部署的额外库。
QT_HARMONYOS_EXTRA_PLUGINS	需随 HarmonyOS 目标一起部署的额外 Qt 插件。
QT_HARMONYOS_MODULE_DESCRIPTION	HarmonyOS 模块的描述。
QT_HARMONYOS_MODULE_DEVICE_TYPES	HarmonyOS 模块支持的设备类型。
QT_HARMONYOS_PACKAGE_SOURCE_DIR	自定义 HarmonyOS 包模板的路径。
QT_HARMONYOS_TARGET_ARCHS	HarmonyOS 应用的目标架构。
QT_HARMONYOS_TARGET_SDK_VERSION	HarmonyOS 应用的目标 SDK 版本。

变量

以下变量会影响 HAP 的构建方式：

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.