适用于 iOS 的 Qt

Qt for iOS 支持为 Apple 的iPhone和iPad设备以及Apple Vision Pro 构建应用程序。

若要使用 Qt for iOS 进行开发，请按照入门指南操作；随后可探索iOS 示例 及相关主题。

支持的配置

Qt 6.12 支持以下版本的构建环境和运行时目标平台。

构建环境

iOS 的构建环境由 Apple 的Xcode应用程序提供，其中既包含工具链（编译器、链接器及其他工具），也包含用于构建和链接的 iOS 平台 SDK（头文件和库）。这些组件共同决定了应用程序的构建方式。

Apple 通常建议（对于 App Store 应用，则要求）应用程序必须基于最新的 SDK 进行构建，因此您应始终使用 Apple 提供的最新版 Xcode。这可能需要升级系统的 macOS 版本，因为新版 Xcode 可能无法在旧版 macOS 上运行。

选择不采用行为变更

使用最新版本的 Xcode 和 SDK 构建应用程序时需要注意的一点是，iOS 系统框架有时会根据您构建应用程序时所基于的 SDK 来决定是否启用行为变更。

这种做法使苹果能够确保基于旧版 SDK 构建的二进制文件，在新版 iOS 系统上仍能正常运行，且不会出现功能退化。

例如，当 macOS 10.14 Mojave 引入深色模式时，macOS 只会将基于 10.14 SDK 构建的应用程序视为支持深色模式，而基于较早 SDK 构建的应用程序则会保持默认的浅色模式外观。

使用较旧版本的 Xcode 并基于较旧的 SDK 进行构建，是规避此类行为变化的方法之一，但这仅应作为最后手段，且仅当您的应用程序没有其他方法来解决此问题时才应采用。

目标平台

针对 iOS 进行构建时会使用一种称为“弱链接”的技术，该技术允许您使用最新平台 SDK 的头文件和库来构建应用程序，同时仍允许将应用程序部署到低于该 SDK 版本的 iOS 系统上。 当二进制文件在低于其构建所用 SDK 版本的 iOS 版本上运行时，Qt 会在运行时检查平台功能是否可用，然后才使用该功能。

理论上，这使得您的应用程序可以在已发布的每个 iOS 版本上运行，但出于实际（和技术）原因，该范围存在一个下限，即应用程序的“部署目标”。如果二进制文件在低于部署目标的 iOS 版本上启动，Qt 将显示错误信息，且应用程序无法运行。

Qt 通过 CMAKE_OSX_DEPLOYMENT_TARGET 或QMAKE_MACOSX_DEPLOYMENT_TARGET 变量来表示，其默认值设置为Qt支持的最低部署目标。

只有当您的代码使用了在高于 Qt 默认版本的 iOS 版本中新增的 API，且您未使用 `@available ` 检查来在运行时限制这些 API 的使用时，才需要提高部署目标。

若要通过 CMake 提高部署目标：

set(CMAKE_OSX_DEPLOYMENT_TARGET "42.0")

或使用 qmake：

QMAKE_MACOSX_DEPLOYMENT_TARGET = 42.0

有关在 Apple 平台上基于 SDK 进行开发的更多信息，请参阅 Apple 的开发者文档。

入门指南

安装 Xcode

Xcode 是使用 Qt 开发 iOS 应用的必备工具。您可以从App Store 安装，或从 Apple开发者网站下载。

安装完成后，请运行一次 Xcode，以便其安装所需的依赖项。

然后，请使用xcode-select 工具验证系统是否正在使用正确的Xcode安装版本。

$ xcode-select -print-path
/Applications/Xcode.app/Contents/Developer

如果输出结果与预期不符，请手动选择相应的 Xcode 安装。

$ sudo xcode-select --switch /Applications/Xcode.app

Qt for iOS 模拟器库的架构为x86_64 ，这意味着在 Apple Silicon 版 Mac 上，iOS 模拟器必须在 Rosetta 环境下运行。在 Xcode 26 及更高版本中，这需要先在 Xcode 设置中删除默认安装的 iOS 平台组件，然后手动安装通用 iOS 平台组件：

xcodebuild -downloadPlatform iOS -architectureVariant universal

若要在 Xcode 自带的模拟器中测试 Qt 应用程序，仅需执行上述操作即可。但是，若要在实体设备上运行应用程序和/或在 App Store 中发布应用程序，则必须加入Apple 开发者计划，并配置开发者证书和配置文件。

在构建任何 Qt 应用程序之前，您应测试 Xcode 是否配置正确，例如在设备上运行一个标准的 Xcode 应用程序模板。

安装或构建 Qt

要安装或构建 Qt，请按照Qt 入门指南中的通用步骤操作。

从命令行构建应用程序

使用 CMake 或 qmake 来定义 iOS 应用程序的构建方式。CMake 和 qmake 均可生成xcodeproj 文件，该文件随后可在命令行中加载并用于构建。

使用 CMake

位于<Qt-dir>/<version>/ios/bin/ 目录下的qt-cmake 便捷脚本将为您自动配置工具链和正确的架构。

使用qt-cmake 便捷脚本：

<Qt-dir>/<version>/ios/bin/qt-cmake <source-dir>

利用生成的xcodeproj 文件，您可以使用 Xcode 构建应用程序，或者在命令行中运行xcodebuild 。要查看应用程序可用的目标和方案列表，请运行以下命令：

xcodebuild -list -project <your-app>.xcodeproj

然后，运行xcodebuild build 并传入您的应用程序详细信息：

xcodebuild build -allowProvisioningUpdates -project <your-app>.xcodeproj -scheme <your-scheme> -configuration Debug -destination "generic/platform=iOS" -destination-timeout 1 ENABLE_ONLY_ACTIVE_RESOURCES=NO

使用 qmake

首先，使用 qmake 定义应用程序的构建方式。然后，使用生成的xcodeproj 文件在 Xcode 中或通过命令行构建应用程序。

qmake <your-app>.pro

qmake 会生成一个封装的 Makefile，该文件会调用xcodebuild ，因此您可以运行 `make ` 来构建应用程序：

make -j8

请注意，如果项目配置发生变化（例如添加或删除了源文件），您必须重新导入该项目。

自定义 Xcode 项目设置

可以使用 qmake 变量 `QMAKE_MAC_XCODE_SETTINGS ` 来自定义 Xcode 设置，例如：

development_team.name = DEVELOPMENT_TEAM
development_team.value = <your-team-id>
QMAKE_MAC_XCODE_SETTINGS += development_team

其他 qmake 变量也很有用：

QMAKE_TARGET_BUNDLE_PREFIX = com.<your-company>
QMAKE_BUNDLE = <your-app>

在 Xcode 中运行应用程序

由 qmake 和 CMake 生成的 Xcode 项目支持在 iOS 设备和 iOS 模拟器上运行应用程序。

使用Qt Creator

有关如何设置和运行 Qt for iOS 应用程序的信息，请参阅Qt Creator 文档：

• Qt Creator：连接 iOS 设备。

请注意，这仍然需要一个可正常运行的 Xcode 安装。

iOS 示例

在Qt Creator 中，可以查阅已在 iOS 上经过测试的示例。在Qt Creator 的“欢迎”模式下，使用关键词ios 搜索示例。请注意，部分示例的功能可能有限。

如需查看已知可在 iOS 设备上正常运行的示例列表，请访问Qt for iOS 示例。

相关主题

以下主题提供了有关 Qt for iOS 的更多详细信息：

• 平台说明
• Qt for iOS - 从源代码构建

在 Qt 应用程序中使用 Objective-C 代码

Clang（Apple 平台应用程序所使用的编译器）支持混合使用 C++ 和 Objective-C 代码。要启用此模式，请为相关源文件添加.mm 扩展名，并按常规方式将其添加到项目中。

使用 CMake 时：

target_sources(myapp PRIVATE objc_code.mm)

使用 qmake：

SOURCES += objc_code.mm

这样，您就可以在 Qt 应用程序中使用 Apple 开发者库中的 Objective-C 框架了。

若要将功能暴露给应用程序的其他部分，同时无需重命名所有源文件，请在头文件中声明辅助函数，并在 Objective-C++ 源文件中实现该功能：

// objc_code.h
QString localizedHostName();

// objc_code.mm
#include <Foundation/NSHost.h>
QString localizedHostName()
{
    return QString::fromNSString(NSHost.currentHost.localizedName);
}