Qt 6.12 的新功能

Qt 6.12 中的新增和恢复模块

Qt 6.12 新增了以下模块和工具：

• Qt Qml 设计支持模块，包含用于在QML中注册和引用对象的一组类型。该模块旨在为未来的Qt Quick 设计工具提供支持。

Qt 6.12 的新功能

ActiveQt 模块

无显著变更。

Qt Bluetooth 模块

• Android 后端现在在启动 BTLE 广播时，会遵循通过QLowEnergyAdvertisingParameters 提供的广告最小间隔和最大间隔参数。

Qt Canvas Painter 模块

• Qt Canvas Painter模块已脱离“技术预览”阶段，现已获得全面维护（支持）。
• 该模块新增了QtCanvas2D ，这是一个由 Qt Canvas Painter 支持的新 QML API。该 API 仍处于技术预览阶段。
• QCanvasPath 新增了addPath() 的重载方法，用于直接解析 SVG 路径字符串。
• QCanvasPainter 新增了QCanvasPainter::FillRule 和QCanvasPainter::setFillRule()，以支持路径填充的EvenOdd填充规则。
• QCanvasGradient 新增了setImage() 方法，可直接从图像创建渐变。
• QCanvasRadialGradient 新增了构造函数以及setInnerCenterPosition() /setOuterCenterPosition()，以支持非对称（双中心）径向渐变。

Qt CoAP 模块

无值得注意的变化。

Qt Core 模块

• QRangeModel的RowOptions 和ItemAccess 自定义点已扩展，以支持headerData() 以及按行和按项的flags() 。QRangeModel 增加了对drag'n'drop handling 的支持，这两个自定义点都提供了自定义且类型安全的 MIME 类型处理，并具有supportedDragActions 和supportedDropActions 属性。QRangeModel 现在还实现了sort()，支持用于根据区域设置进行排序的sortCollator ，以及用于快速内容匹配的match()。
• 新增了qSharedPointerStaticCast 作为QSharedPointer 的静态转换新免费函数。
• QSortFilterProxyModel 新增了DataChangeRelevanceFlag 枚举和虚拟方法dataChangeRelevanceFlags()，允许子类控制源dataChanged 信号是否触发重新过滤或重新排序。
• 新的QAbstractItemModel::compareData() 是一个新的受保护 API，用于比较两个 QVariant，其设计专门针对项目视图用例。
• qfloat16 新增了递增和递减运算符以及一元operator+ 。
• QVariant 新增了来自右值引用（rvalue references）的构造函数。
• QMap 和QMultiMap 现在实现了全部六个关系运算符。
• QVarLengthArray 新增了 `removeAt()` 方法，与 `QList ` API 保持一致。
• QDateTime 、QDate 和QTime 的fromString() 方法，以及QLocale 的toDateTime()、toDate() 和toTime() 方法，现在使用了一个新的解析器，在许多格式上速度更快。
• QTimeZone 现在在其构造函数以及isTimeZoneIdAvailable() 中接受 CLDR-canonical IANA 别名 ID。QTimeZone::availableTimeZoneIds() 现已包含这些别名。
• QFile::copy() 现在接受一个可选的QFileDevice::Permissions 参数。QSaveFile 现在将所请求权限的应用推迟到commit() 调用时。
• Qt::compareThreeWay() 增加了针对std::pair 的重载。
• QCalendarPermission 新增了WriteOnly 访问模式。
• QFileSystemWatcher 现在可以在 FreeBSD 15 及更高版本上使用inotify 。
• QStandardPaths 在 macOS 上，standardLocations() 现在包含了系统范围的/Library/Preferences 目录。在 iOS 上，PublicShareLocation 返回正确的路径，并且TemplatesLocation 被正确地报告为不支持。
• QEasingCurve 新增了fromCubicBezier()，这是一个用于创建三次贝塞尔缓动曲线的便捷辅助函数。
• QJsonObject 新增了cbegin() 和cend() 这两个 STL 风格的 const 迭代器。QJsonDocument 新增了来自QJsonArray 和QJsonObject 的右值构造函数。

Qt D-Bus 模块

无值得注意的变更。

Qt Graphs 模块

• Qt Canvas Painter 现在可作为 2D 图表的渲染后端。可在配置时使用-feature-graphs-2d-high-performance-backend 配置标志启用该功能。
• 新增了QLogValueAxis （在 QML 中为LogValueAxis ），这是一种用于 2D 图表的新对数轴类型。
• QXYSeries 新增了values 、valueMapping 、valueMin 和stepSize 属性，用于从 QML 进行声明式数据输入。
• QPieSeries 新增了sliceData 和sliceLabels 属性，用于从 QML 进行声明式数据输入。
• QValueAxis 此外，QLogValueAxis 还新增了labelPostFormat 属性，用于自定义坐标轴标签文本。
• Q3DGraphsWidgetItem 新增了panEnabled 和dragMode 属性，用于在 3D 图表中启用和配置平移功能。
• QDateTimeAxis 新增了tickCount 属性。

Qt GRPC 模块

• 添加了客户端请求压缩功能。可通过QGrpcChannelOptions::setRequestCompression() 和QGrpcCallOptions::setRequestCompression() 选择新的QtGrpc::CompressionAlgorithm 枚举来压缩传出消息。
• 在QGrpcChannelOptions 中添加了supportedCompressionAlgorithms()、acceptedCompressionAlgorithms() 和setAcceptedCompressionAlgorithms()，用于控制客户端在grpc-accept-encoding 请求头中声明的压缩算法，以及在服务器响应中愿意接受的压缩算法。
• 在QGrpcChannelOptions 和QGrpcCallOptions 中添加了maximumReceiveMessageSize() 和setMaximumReceiveMessageSize()，用于限制传入消息的大小。

Qt GUI 模块

• 为QRhi 添加了间接渲染支持。现在可以创建IndirectDrawBuffer 类型的缓冲区，并通过QRhiCommandBuffer 发出间接绘制调用。
• QRhi 新增了ShaderDrawParameters 功能标志，用于查询对着色器绘制参数内置值（例如gl_DrawID ）的支持情况。
• QRhi Vulkan 后端现在使用 `VK_EXT_device_fault ` 来报告有关设备丢失的更多详细信息。
• QAccessibilityHints 新增了用于“减少运动”无障碍偏好的motionPreference 属性。
• QStyleHints 新增了toolTipWakeUpDelay ，允许应用程序查询或调整工具提示出现前的延迟时间。
• QImageReader 新增了effectiveSize()，该方法会返回符合autoTransform() 要求的图像尺寸。
• QTextCursor::deletePreviousChar()（退格键）现在可以正确处理多代码单元表情符号序列。
• 新增了Qt::InputMethodHint::ImhNoFullscreen ，用于要求输入法不要占据整个屏幕。
• 添加了Qt::InputMethodHint::ImhDecimalNumbersOnly ，用于将输入限制为包含小数的数字，但不包括负数。

Qt HTTP Server 模块

• QHttpServerConfiguration 新增了setMaximumConnections() 来限制同时连接的总数，以及setMaximumConnectionsPerHost() 来限制每个 IP 地址的连接数。

Qt Image Formats 模块

没有值得注意的变化。

Qt Lottie Animation 模块

• 新增了对 Lottie文本图层的支持，包括字形路径渲染。
• 新增了对 Lottie椭圆、矩形和 多边形形状元素中动画尺寸的支持，以及渐变笔触、图层蒙版和图层“自动方向”功能。
• 新增对 Lottie时间重映射和时间拉伸功能的支持。
• 引入了LottieVectorImageController ，用于在VectorImage 中控制Lottie动画的播放。该类型提供了currentFrame 、frameRate 、startFrame 和endFrame 属性，以及play()、pause()和gotoAndPlay()等播放方法。

Qt MQTT 模块

没有值得注意的变化。

Qt Multimedia 模块

• QScreenCapture 和QWindowCapture 增加了maximumFrameRate 属性，用于限制捕获帧率。ScreenCapture 和WindowCapture QML 类型也提供了该属性。
• QAudioSource QAudioSink 增加了 () 和 () 方法，用于查询和控制本机音频缓冲区周期大小。nativePeriodFrameCount setNativePeriodFrameCount
• 新增了QMediaCaptureSession::setNativeVideoSource() 方法以及GStreamerVideoSource QML 元素，支持自定义 GStreamer 管道将视频帧输入到QMediaCaptureSession 中。
• QMediaMetaData::ThumbnailImage 已弃用；后端将不再为其赋值。请改用CoverArtImage 。
• QSoundEffect 现在，即使 URL 未发生变化，在调用setSource() 之后，也会始终输出sourceChanged 。

Qt Network 模块

• 引入了QSslKeyingMaterial 以及 QSslConfiguration::keyingMaterial() /setKeyingMaterial()，以暴露 TLS 密钥材料导出器（RFC 5705）。
• QHostInfo 新增了clearCache()，用于通过编程方式清空 DNS 结果缓存。
• QHttpHeaders 新增了QDataStream 流运算符、用于解析Range 头部的rangeValues()，以及用于设置该头部的setRangeValues()。新的 QHttpHeaderRange 类表示该头部内的单字节范围。
• OpenSSL TLS 后端现支持基于 OpenSSL 4 进行构建。

Qt Network 授权模块

没有值得注意的变化。

Qt OPC UA 模块

没有值得注意的变化。

Qt OpenAPI 模块

• qt_add_openapi_client()新增了GENERATE_DOCUMENTATION 、DOCUMENTATION_OUTPUT_DIRECTORY 选项，用于在生成客户端代码的同时生成基于 Doxygen 的文档。
• 增加了对oneOf模式特性的支持。
• 重命名了生成的模型属性获取器。Q_PROPERTY 现在公开的属性名称与 YAML 文件中使用的名称一致。
• 生成的客户端 API 方法不再是虚拟方法。

Qt Positioning 模块

• QGeoSatelliteInfo::SatelliteSystem 中增加了 IRNSS 和 SBAS 卫星系统的条目。

Qt Print Support 模块

无值得注意的更改。

Qt Protobuf 模块

• 生成的消息类中的 Qt 属性现在默认标有FINAL 修饰符。这使得 QML 工具能够应用性能优化并生成更高效的代码。若要恢复旧行为，请使用qt_add_protobuf()的新选项GENERATE_NON_FINAL_PROPERTIES 。

Qt Qml 模块

• QQmlEngine 新增了setExternalSingletonInstance() 方法，用于将外部创建的 C++ 对象注册为 QML 单例。QML_UNCREATABLE 现可与QML_SINGLETON 结合使用。
• string.arg() 在 QML 中，该函数现在支持多个参数，这与 JavaScript 的惯例一致。
• 添加了全局函数Qt.escapeHtml()，用于在 QML 中转义 HTML 特殊字符。
• 当实例化一个缺少必填属性的组件时，引擎现在会报告错误，而不是默默地构建一个不完整的对象。
• QQmlProperty 是一种名为 qmlProperty 。您可以在 QML 中将其用作属性类型、函数参数或返回类型。
• QtQml.Models import：SortFilterProxyModel 增加了RangeFilter 、RegExpFilter 、AllOfFilter 和AnyOfFilter 复合过滤器类型，并改进了FunctionFilter ，使其能够将角色名称作为单独的参数接受。
• Qt.labs.qmlmodels import：TreeModel 新增了insertRow() 和moveRows() 方法。
• Qt Qml 编译器：移除了QQmlSA::FixSuggestion::hint() 和QQmlSA::FixSuggestion::setHint() 。QQmlSA::FixSuggestion::fixDescription() 已重命名为QQmlSA::FixSuggestion::description()。

Qt Quick 模块

• 添加了Color QML 单例，提供用于颜色操作的实用函数。
• AnimatedImage 该类型新增了loops 、finishBehavior 属性，以及finished() 信号。
• Text 类型现在可以正确渲染所有QTextCharFormat::UnderlineStyle 值（例如DashUnderline 、WaveUnderline 和SpellCheckUnderline ），这些值可以通过 HTML 标记在RichText 模式下应用，或者通过 C++ API 中的QTextCharFormat 应用。此前，所有下划线样式均被渲染为实线。
• 在ShapePath 类型中添加了strokeGradient 属性。
• Rectangle::color 现在可以通过在 QML 中将该属性赋值为undefined 来将其重置为默认值（白色）。
• Qt.labs.folderlistmodel 中的FolderListModel 类型新增了showDot 和showDotDot 属性。
• QtQuick.VectorImage 中的VectorImage 类型新增了asynchronous 、status 、retainWhileLoading 和generatedItem 属性。

Qt Quick Controls 模块

• 添加了QtQuick.Controls.Native 样式。import QtQuick.Controls.Native 会在编译时为目标平台选择最合适的样式。因此，它既结合了编译时样式选择的优势，又使应用程序能够呈现出特定于平台的外观和感觉。
• ToolTip 新增了policy 属性，用于控制自动工具提示的可见性。
• ComboBox 新增了highlightOnHover 属性。
• RangeSlider 新增了 `crossingEnabled ` 属性，用于允许或禁止两个控件相互交叉。
• Menu 新增了separatorsCollapsible 属性。
• MenuItem 现在会显示来自关联的Action 的键盘快捷键。
• SearchField 现在，如果其TextInput 为空，则允许使用键盘进行导航。
• 为了方便起见，SearchField 中添加了现有TextField API的一部分：selectTextByMouse、selectedText、selectionStart、selectionEnd、cursorPosition、select()、selectWord()和deselect()。

Qt Quick Dialogs 模块

没有值得注意的更改。

Qt Quick Effects 模块

没有值得注意的变化。

Qt Quick Test 模块

• TestCase的optional 属性在 Qt Quick Test中已弃用。请改用skip()。

Qt Quick 3D 模块

• 新增了SkyMaterial QML类型，用于渲染过程化天空并生成基于图像的照明数据。
• 在QtQuick3D.Helpers 导入中添加了QuadTextureProvider 。这是一种用于通过自定义片段着色器渲染四边形纹理的QML类型。
• Model 新增了instancingLodFactor 属性，用于在使用 GPU 实例化时手动控制细节级别。
• ExtendedSceneEnvironment 新增了ssrThickness 和ssrMaxSteps 属性，用于更精细地控制屏幕空间反射。
• RuntimeLoader 新增了query()和queryAll()方法，用于在动态加载的场景中按名称或类型查找对象。

Qt Quick 3D XR 模块

• 新增了对单视图配置的支持（XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO ），使Qt Quick 3D XR 应用程序能够在 AR 眼镜等 2D XR 设备上运行。

Qt Quick 3D 物理模块

• 新增了五种用于约束物理体的关节类型：DistanceJoint 、FixedJoint 、PrismaticJoint 、RevoluteJoint 以及SphericalJoint 。它们均继承自共同的基类PhysicsJoint 。

Qt Remote Objects 模块

• registryUrl 和persistedStore 属性现在具有变更通知信号。

Qt SCXML 模块

无值得注意的更改。

Qt Sensors 模块

没有值得注意的更改。

Qt Serial Port 模块

无显著变更。

Qt Spatial Audio 模块

无显著变更。

Qt Serial Bus 模块

无显著变更。

Qt SQL 模块

无显著变更。

Qt SVG 模块

• QMovie 和AnimatedImage 现已支持动画 SVG 文件。

Qt Labs StyleKit 模块

• 引入了QStyleKitStyle ，这是一个QStyle 的子类，用于为QWidget 应用程序应用基于 StyleKit 的样式。
• 该样式现已为RoundButton 和MenuSeparator 这两种Qt Quick Controls 类型提供了实现，取代了通用的备用方案。

Qt TaskTree 模块

• QtTaskTree::For 新增了一个重载方法，该方法接受 `qsizetype ` 作为迭代计数。可将其作为 `For(RepeatInterator(n))` 的快捷方式使用。
• QtTaskTree::Forever 现在可隐式转换为QtTaskTree::Group 。
• QtTaskTree::ListIterator 新增了一个重载，该重载接受一个返回QList 的获取函数。

Qt Test 模块

• 基准测试结果现在包含不同测量后端（时间、CPU 时钟周期、事件、Valgrind）之间的方差和标准差。
• 为了保持一致性，纯文本基准测试记录器现在使用科学记数法对浮点结果进行格式化。
• 当命令行中同时指定了有效的测试函数和不存在的测试函数时，系统仍会执行有效的测试。

Qt Virtual Keyboard 模块

无显著变更。

Qt WebEngine 模块

• QWebEngineNavigationRequest 新增了 userInitiated 属性，用于区分用户主动发起的导航与程序化导航。
• QWebEngineProfile 新增了 setCryptoModulePasswordFunction() 方法，用于提供解锁 PKCS#11 硬件令牌的回调函数。

Qt WebSockets Module

无值得注意的变更。

Qt PDF 模块

• QPdfSearchModel 新增了 status 属性及 Status 枚举，用于跟踪搜索是否正在进行、处于空闲状态或已完成。
• QPdfView 现在支持按住 Control 键并滚动鼠标滚轮，以光标位置为中心进行缩放。
• render() 增加了可选参数，用于指定图像格式和背景颜色。

Qt WebView 模块

• WebView 现可在 Android、iOS、macOS 和 Windows 系统上从 Qt 资源系统（qrc:/ URL）加载内容。

Qt Widgets 模块

• QTreeView 新增了QTreeView::itemDecorationRect() 方法，该方法返回给定索引对应的装饰（图标）的边界矩形。
• QStyle::StandardPixmap 新增了用于标签栏滚动按钮的QStyle::SP_TabScrollLeftButton 、QStyle::SP_TabScrollRightButton 、QStyle::SP_TabScrollUpButton 和QStyle::SP_TabScrollDownButton 。
• QDialogButtonBox 新增了QDialogButtonBox::standardButtonText() 和QDialogButtonBox::standardButtonShortcut()，它们分别返回QDialogButtonBox::StandardButton 的文本和快捷键。
• 在 macOS 上，QMainWindow 的统一标题和工具栏模式已进行现代化改造，改用效果视图来设置背景样式。

Qt XML 模块

无显著变更。

工具

Qt Assistant

• Qt Assistant 现在，当启用深色配色方案时，可正确渲染浅色/深色主题的 Qt SVG 图表，其行为与在线 Qt 文档保持一致。

QML 命令行工具

• 在qmllint中添加了--only-explicit-categories 选项，用于抑制所有默认警告。
• 在已注册类型的属性和方法中使用的未注册类型，现已在 qmltypes 中作为“opaque”类型进行记录。这避免了工具中的警告，使qmlls 中的自动完成和“转到定义”功能能够正常工作，并使更多地方能够进行与 C++ 的绑定编译。
• 已将qmllint和qmlls修改为对未知类型仅发出一次警告，而非针对该未知类型的每次绑定和使用都生成警告。
• 在qmllint和qmlls中新增了以下警告：
  • 被遮蔽的 QML 类型成员。
  • 文件选定变体不兼容（可选功能）。
  • 递归实例化的 QML 类型。
  • 通过文件名而非 qmldir 或QT_QML_SOURCE_TYPENAME 名称引用的 QML 类型。
  • JavaScript 中使用了接受超过 1 个参数的new Array() 重载方法。
• 在QML Language Server 中新增了以下功能：
  • 通过代码操作将组件封装到加载器中。
  • 查找通过QML_FOREIGN 声明的类型的 C++ 定义。
  • 在后台重建 QML 类型信息时显示进度。

QDoc 文档生成器

• C++20 概念：新的 \concept topic 命令会为 C++20 概念生成一个专门的参考页面，其中包含受该概念约束的已文档化类型和函数列表。 C++ 语法概要中的概念参考在 HTML 和 DocBook 输出中均会链接至这些页面，而直接受概念约束的模板参数（如template <Integral T> ）将显示概念名称，而非 `typename ` 关键字。通过 `.index ` 文件，概念链接可在模块之间生效。
• enable_if基于 SFINAE 的约束会渲染为易于阅读的 `requires ` 子句，而非晦涩的无名布尔模板参数，这扩展了Qt 6.11 中引入的 C++20 `requires` 子句支持。当函数同时具有显式的 `requires ` 子句时，两者将合并显示。
• 显式默认化和已删除的函数在其定义摘要中带有[default] 和[delete] 标签，而编译器生成的特殊成员函数则标记为[implicit] 。这些标签会链接到 cppreference.com。对于没有 \fn 代码块，QDoc 会自动生成文档且不发出警告。显式文档将覆盖生成的文本，若将配置变量showautogenerateddocs设置为false ，则会将其从输出中省略。
• QDoc 会区分“隐藏的朋友函数”（即仅能通过参数依赖查找获得的朋友函数）与仅授予访问权限的朋友声明。请使用其自然的自由函数语法（例如\fn operator==(const MyClass &, const MyClass &) ）来文档化隐藏的朋友函数（包括行外定义的），而非使用类限定名。
• 一个统一的表格取代了由 \compares 和 \compareswith 命令生成的零散比较文档段落，通过统一的表格，一目了然地展示类与哪些类型进行比较，以及每种关系适用哪种比较类别。
• ` \a 命令现可对模板参数名称进行验证。QDoc 会针对类和类型别名中未记录的模板参数，以及函数中未记录的非类型或模板-模板参数发出警告。
• 通过在 \preliminary生成的状态描述符和消息，允许使用“技术预览”等术语代替默认值。状态命令的优先级保持一致：\preliminary 会覆盖\modulestate ，而\internal 则同时覆盖这两者。
• 在\module 或\qmlmodule 主题上设置的状态（例如\preliminary 或\deprecated ）会传播到模块的成员，除非某个成员设置了自己的状态。
• 新的 \qmluncreatabletype topic 命令用于记录已在 QML 类型系统中注册但无法实例化的 QML 类型。QDoc 还会自动检测带有QML_UNCREATABLE 宏注释的类型。
• 关联属性、信号和方法不仅在“所有成员”页面中，还在主要的 QML 参考页面中进行了标注。
• “ \qmlmethod 该命令需要完整的签名；当返回类型缺失或参数列表无法解析时，QDoc 会发出警告。
• 类文档中的#include语句反映了Clang报告的实际头文件名称。使用Qt风格便捷头文件（如<QString> ）的项目仍可自动运行。
• 每个项目在基础输出目录中都会获得一个.index 文件，以取代特定格式子目录中的各格式副本。索引配置变量中的相对路径会根据.qdocconf 文件的位置进行解析，这与其他路径变量保持一致。
• 生成的 HTML 文件会根据页面类型（类、QML 类型、模块、示例等）自动包含<meta name="keywords"> 条目，从而简化后处理和站点地图的生成。代码块带有与 highlight.js 语法高亮兼容的标签。
• 文档编写方面的细微改进：使用 \metaqdoc-suppress-inheritance 来隐藏仅出于文档目的而继承基类的类型的“Inherits:”行； \list 支持零及以下起始值；在\l 链接目标中，\# 表示字面量字符# ；以及 \details 强制执行其文档中所述的大括号分隔的摘要参数。
• 新增了对 LLVM/Clang 22 的兼容性。

Qt Linguist

• lupdate 现可保留.ts 文件中的现有行结束符。在 Windows 上，行结束符为 CRLF 的文件将就地更新为 CRLF；行结束符为 LF 的文件以及新文件则保留 LF。
• Qt Linguist 新增了 -web-help 选项，可根据需要使用在线 Web 文档。

Resource Compiler (rcc)

• rcc现采用基于内容的 SHA256 哈希算法对资源数据进行去重处理。嵌入在 Qt 资源集合中的相同文件仅存储一次，从而在不更改应用程序源代码的情况下，减小了编译后资源的大小。

平台变更

构建系统变更

构建 Qt

• 现在构建 Qt 需要 CMake 3.25 或更高版本。
• 新增了static_compiler_runtime CMake 功能，用于静态链接 C++ 运行时库。在 Windows（MSVC）上，该功能采用混合 CRT 方法，从而消除了对 Visual C++ 再分发包的依赖。
• 为 Android 构建 Qt 时，现在使用 Gradle 代替直接调用javac 来处理 Qt JAR 目标。

CMake API

• 使用 Qt 现需 CMake 3.25 或更高版本。
• 以下 CMake API 已退出技术预览阶段，现已获得全面支持：qt_finalize_project()、qt_extract_metatypes()、qt_deploy_translations()、QT_TARGETS_FOLDER、QT_RESOURCE_PREFIX、QT_DEPLOY_SUPPORT 以及QT_ENABLE_VERBOSE_DEPLOYMENT。
• 目标属性qt_no_entrypoint 已重命名为QT_NO_ENTRYPOINT。出于向后兼容性考虑，旧名称仍被识别。
• 新增了 CMake 策略QTP0006 。当该策略设置为NEW 时，qt_generate_wayland_protocol_client_sources()和qt_generate_wayland_protocol_server_sources()将默认使用PRIVATE_CODE 而不是PUBLIC_CODE 。
• qt_add_shaders()的进度消息现在以DEBUG 级别记录，而非NOTICE ，从而将其从默认构建输出中屏蔽。若要恢复先前行为，请向 CMake 传递--log-level=NOTICE 。
• qt_add_qml_module()新增了NO_GENERATE_QTCONF 选项，用于抑制在构建目录中自动生成qt.conf 文件。
• 构建系统现在为每个包含 QML 模块的可执行文件提供了一个 <exe>_qmlpreview 目标。当您“构建”该目标时，构建系统会使用正确的参数启动qmlpreview实用程序，并允许您预览可执行文件的 QML 效果。特别是，它会自动解析 .qrc 文件的路径。
• 现在提供了两个新的目标值：QT_WINDOWS_APP_PROJECT_IDENTIFIER和QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL。另请参阅下文的“Windows”部分。

桌面平台

Windows

• CMake 项目现在会自动生成并嵌入应用程序清单，用于通过qt_add_executable() 构建的 Windows 可执行文件。该清单声明了 Windows 10/11 兼容性，启用了长路径支持，并配置了 UAC 执行级别。 有两个新的 CMake 目标属性用于控制生成的清单：QT_WINDOWS_APP_PROJECT_IDENTIFIER用于设置程序集标识名，QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL用于设置执行级别。详情请参阅《Qt for Windows - 部署》。
• windeployqt新增了--appx 和--appx-certificate 选项，用于生成适合打包为Windows Store appx包的AppxManifest.xml 。
• QOperatingSystemVersion::Windows11_25H2 (10.0.26200) 已作为命名操作系统版本常量添加。
• 在 Windows 上，平台插件现在通过ColorProfileGetDisplayDefault 从每个屏幕的 ICC 配置文件中推导出其色彩空间，而不是始终报告 sRGB。
• DirectWrite 字体后端现在会读取每种字体的 GASP 表，根据字体和点大小选择适当的抗锯齿策略，从而更贴近字体设计者的初衷。
• 针对当前的英特尔 GPU 驱动程序，重新启用了着色器磁盘缓存。此前数年间，该功能在 Windows 系统的英特尔显卡上一直被无条件禁用；现在改用驱动程序版本检查，从而提升了现代英特尔硬件上Qt Quick 3D 的性能。
• QWizard 当系统处于深色模式时，不再应用 Aero 向导样式，因为该样式在深色模式下无法正确渲染。
• Visual Studio 2026 现已全面支持ARM64EC。该版本不提供安装程序包。部分模块（如Qt WebEngine 、QtWebView 以及Qt Quick 3D Physics）暂不支持。

Linux

• QDesktopServices::openUrl() 现在会优先使用org.freedesktop.portal.OpenURI 的 XDG 桌面门户服务（如果可用），而非xdg-open 及其他备用方案。该门户的行为可能与之前使用的应用程序有所不同。
• 当没有门户可用时使用的备用方案已更新：现在可识别 Plasma 6 的kde-open ，而对 KDE 3 时代的kfmclient 的支持已被取消。
• 新的motionPreference 属性由桌面设置提供数据：org.freedesktop.appearance 门户命名空间中的reduced-motion 键，以及 GNOME 的org.gnome.desktop.interface enable-animations 设置。
• 原生 GTK3 字体对话框现支持QFontDialog 中的字体筛选选项，包括可缩放与不可缩放字体，以及等宽与比例字体。
• AT-SPI 辅助功能桥现可向辅助技术通知展开状态和可展开状态的变化。
• 在 fontconfig 2.17.1 或更高版本上运行时，从 Qt 资源中添加的字体再次被正确注册。
• 在 X11 上，工具提示窗口不再在每次显示时都被重新创建。
• QNetworkProxy 在使用 libproxy 后端时，现已支持*_PROXY 环境变量中的socks5h 方案。

macOS

• QScreen::grabWindow() 现在使用 ScreenCaptureKit 代替已弃用的CGDisplayCreateImageForRect 。首次使用该 API 时，将显示权限提示。
• QWindows 嵌套在未翻转的NSView中的子视图，在父视图调整大小时，会保持相对于父视图左上角的相对位置。
• QCocoaNativeInterface::setEmbeddedInForeignView() 将 Qt 视图层次结构嵌入外部NSView 已不再必要，也不再受支持。Qt 现已自动管理此过程。
• 基于静态 Qt 构建的沙箱应用，在 Apple 平台上现在默认可重定位。
• QMainWindow统一的标题和工具栏模式现在通过Qt::ExpandedClientAreaHint 和Qt::NoTitleBarBackgroundHint 实现，而不是已弃用的带纹理的NSWindow 样式。
• QStandardPaths::standardLocations() 现为ConfigLocation 、GenericConfigLocation 和AppConfigLocation 包含全局/Library/Preferences 目录。

Linux 上的 Wayland 客户端

• 新增对用于会话恢复的XdgSessionManager Wayland 协议扩展的支持。
• bradient 客户端装饰主题现可显示最小化、最大化及关闭按钮的提示。

Wayland 合成器

• 新增对linux-dmabuf-v1 稳定协议（版本4）的支持。若要使用该协议，请选择“linux-dmabuf-v1”作为客户端缓冲区集成方案。出于兼容性考虑，之前的（版本3）实现仍可通过“linux-dmabuf-unstable-v1”继续使用。

HarmonyOS

Qt 6.12 作为技术预览版引入了对HarmonyOS（OpenHarmony API 级别 23，HarmonyOS 6.1.0）的支持。目前支持 Vulkan，但辅助功能和EmbeddedUIExtensionAbility 尚未提供。

为帮助在HarmonyOS上构建和部署Qt应用程序，提供了以下工具和CMake函数：

• harmonydeployqt可将 Qt 应用程序打包为 HarmonyOS 应用程序包 (HAP)，复制所需的 Qt 库和插件，生成build-profile.json5 和module.json5 元数据，并支持嵌入 HAP 签名配置。
• harmonyostestrunner 通过hdc 在已连接的 HarmonyOS 设备或模拟器上运行 Qt 自动测试，该操作由ctest 触发。
• qt_add_harmonyos_permission()用于声明应用程序所需的 HarmonyOS 权限。

HarmonyOS 部署的关键 CMake 目标属性包括：

• QT_HARMONYOS_EXTRA_LIBS— 需打包到 HAP 中的附加共享库。
• QT_HARMONYOS_EXTRA_PLUGINS— 需部署的额外 Qt 插件。
• QT_HARMONYOS_PACKAGE_SOURCE_DIR— 该目录中的内容将在构建 HAP 之前合并到生成的 HarmonyOS 项目模板中。

有关已知平台限制的完整列表，请参阅Qt for HarmonyOS 平台限制维基页面。

移动平台

Android

适用于 Android 的 Qt

• 将 Gradle 更新至 9.5.1，并将 Android Gradle 插件更新至 9.2.1。
• 将默认目标 SDK 版本更新为 Android 17（API 级别 37）。
• 新增对 Android 13 及更高版本中预测性返回手势的支持。Qt 通过 `OnBackInvokedCallback` 传递返回事件，并默认启用 `android:enableOnBackInvokedCallback ` 清单属性。
• 新增对 Gradle 多模块构建的支持，通过QT_ANDROID_GRADLE_MULTI_MODULE 启用。这是Play Feature Delivery 的基础。CMake 无需androiddeployqt或第三方工具即可处理整个部署流程，使构建过程更快、更简单。
• 已弃用QT_USE_ANDROID_MODERN_BUNDLE CMake 变量，转而使用QT_ANDROID_GRADLE_MULTI_MODULE。为保持向后兼容性，旧名称仍被识别。
• 新增了对Qt::InputMethodHint::ImhNoFullscreen 、ImhDecimalNumbersOnly 和ImhNoEditMenu 输入法提示的支持。
• 按下返回键现在会将应用置于后台，而非退出应用，详见“返回键和返回手势”。
• 针对 TalkBack 的辅助功能改进：
  • Qt XML 现可响应 `ACTION_SHOW_ON_SCREEN ` 操作。
  • Qt 现会报告视口滚动和滚动位置的变化。
  • Qt 现支持可展开和已展开状态。
  • 当辅助功能焦点移至文本输入框时，软键盘将不再弹出。
  • motionPreference 提示现已反映系统“Remove animations ”设置。
• androidtestrunner现可识别 `--serial ` 和 `--output ` 选项，能在测试运行期间检测到设备断开连接，并输出更完善的崩溃和“应用程序无响应”（ANR）诊断信息。
• 当捆绑的 FFmpeg 构建需要 OpenSSL 库时，Qt 现可自动部署这些库，并通过OPENSSL_ROOT_DIR 或 vcpkg 定位它们。
• Gradle 模板不再强制使用resConfig "en" 。

Qt Quick 适用于 Android

iOS

• QStandardPaths::PublicShareLocation 现在返回的是<APPROOT>/Public （与NSSharedPublicDirectory 匹配），而不是之前在“Documents”目录内生成的路径。
• standardLocations(PicturesLocation) 中不再包含可写入的 Documents/Pictures 路径的重复条目。
• QStandardPaths::TemplatesLocation 现在会正确地报告该功能在 iOS 上不支持，这与现有文档一致。

嵌入式平台

Boot to Qt 和 Qt Onboard

• 从 Qt 6.12 LTS 开始，预编译的Boot to Qt 镜像将不再可通过Qt Online Installer 或您的 Qt 账户下载。

  取代二进制文件，现推出两种基于容器的发布版本：

  • 构建容器：一个开箱即用的环境，预装了所有必要的构建工具，可快速为您的目标硬件构建基于 Yocto 的 Linux 镜像。
  • 演示容器：包含 Qt 演示启动器，其中收录了一组精心挑选的预选演示项目，可立即展示 Qt 的各项功能。

  这些容器将在 Qt 6.12 LTS 补丁发布周期内分阶段推出，并在 Qt 6.12.4 正式发布前全面实现基于容器的交付模式。

• 新平台：
  • Orange Pi 2
  • NXP i.MX95
  • 高通 Dragonwing IQ6
  • 高通 Dragonwing IQ9
  • Renesas RZ/G3E

实时操作系统

QNX

• 在 QNX 上增加了对 Vulkan 的支持。
• Qt Multimedia 现可在 QNX 8.0 上构建。由于尚未为 QNX SDP 8.0 实现音频后端，因此尚不支持音频播放和录制。

VxWorks

• 已添加对 VxWorks 26.03 的支持。

WebAssembly

• QAudioSource 和QAudioSink 现在使用 Web Audio API AudioWorklets 后端代替 OpenAL，从而支持浏览器原生的低延迟音频采集。
• texImage2D 现在，当使用 Qt Quick。
• 已添加对QCameraFormat 的支持。

API 变更列表

这些页面概述了 Qt 6.12 中的 API 变更：

• Qt 6.12 中的新类和函数
• 已弃用的类

已知问题

有关 Qt 6.12 中已知问题的信息，请参阅Qt Wiki。