Qt

Qt 是一个跨平台的应用程序和窗口小部件工具包。它使用标准 C++，但广泛使用了名为元对象编译器 (Meta Object Compiler, moc) 的特殊代码生成器，并结合多种宏来扩展语言功能。其重要特性包括：

可在主流桌面平台及部分移动平台上运行。
广泛的国际化支持。
一个完整的库，提供 SQL 数据库访问、XML 解析、线程管理、网络支持以及用于文件处理的统一跨平台应用程序编程接口 (API)。

Qt 框架是 KDE 软件社区的基础，同时也是许多重要开源和专有应用程序的基石，如 VLC、VirtualBox、Mathematica 等。

安装

注意 Qt 5 之前的版本已达到生命周期终点，不再维护。

Qt 6.x 和 5.x 可从官方仓库获取。旧版本的 Qt (4.x 和 3.x) 可从 AUR 获取。它们可以使用以下软件包进行安装：

Qt 6.x 可在 qt6-base 软件包中找到，文档位于 qt6-doc 软件包中。
Qt 5.x 可在 qt5-base 软件包中找到，文档位于 qt5-doc^AUR 软件包中。
Qt 4.x 可在 qt4^AUR 软件包中找到，文档位于 qt4-doc^AUR 软件包中。
Qt 3.x 可在 qt3^AUR 软件包中找到，没有独立的文档包。

默认 Qt 工具包

要定义默认的 Qt 工具包，您可以创建 QT_SELECT 环境变量。例如，要使用 Qt n，请设置 QT_SELECT=n。

配置

本文或本章节已过时。

原因： 需要更新 qt6 相关内容（在 Talk:Qt 中讨论）

Qt 5 中的样式

本文或本章节已过时。

原因： qt5-base 不再使用 QGtkStyle（在 Talk:Qt#Qt5 no longer uses QGtkStyle 中讨论）

Qt 5 会根据所使用的桌面环境来决定使用哪种样式。

在 KDE Plasma 中，它使用实际选定的 Qt 样式。可以通过“KDE 系统设置”(systemsettings) 进行配置，设置位于 外观 > 应用程序风格 > 窗口部件风格 中。
在 Cinnamon、GNOME、MATE、LXDE、Xfce 中，它使用 GTK (QGtkStyle)。
在其他桌面环境中，它使用 Fusion 样式。

要强制使用特定样式，您可以设置 QT_STYLE_OVERRIDE 环境变量。特别是，如果您希望使用 GTK 主题，请将其设置为 gtk2（注意：您需要安装下文提到的 Qt 样式插件才能获得 GTK 风格）。Qt 5 应用程序也支持 -style 标志，您可以使用它来启动带有特定样式的 Qt 5 应用程序。

Qt 5 中包含以下样式：Fusion, Windows。其他样式可以单独安装：

Breeze — 为 Plasma 桌面提供的 Breeze 视觉风格的艺术资源、样式和资产。

https://invent.kde.org/plasma/breeze || breeze

Oxygen — KDE Oxygen 样式。

https://invent.kde.org/plasma/oxygen || oxygen

Darkly — Darkly 是已废弃的 Lightly 的一个现代分支，这是一种旨在视觉上现代且极简的 Breeze 主题风格。

https://github.com/Bali10050/darkly || darkly^AUR

QtCurve — 一套适用于 KDE 和 Gtk 的可配置窗口部件样式。

https://invent.kde.org/system/qtcurve || qtcurve^AUR

Adwaita-Qt — 一种使 Qt 应用程序看起来像 GNOME Shell 原生应用风格的样式。

https://github.com/MartinBriza/adwaita-qt || adwaita-qt5-git^AUR

Qt style plugins — 用于 Qt 5 的附加样式插件，包括 GTK, Cleanlooks, Motif, Plastique。

https://code.qt.io/cgit/qt/qtstyleplugins.git || qt5-styleplugins^AUR

Kvantum — 一种基于 SVG 的可定制主题引擎，具有多种内置样式，包括模仿流行的 GTK 主题，如 Adapta, Arc, Ambiance。

https://github.com/tsujan/Kvantum/tree/master/Kvantum || kvantum

Qt 样式表

定制 Qt 应用程序外观的一种有趣方式是使用样式表，它们只是简单的 CSS 文件。使用样式表，可以修改应用程序中每个窗口部件的外观。

要使用不同的样式运行应用程序，只需执行：

$ qt_application -stylesheet style.qss

有关 Qt 样式表的更多信息，请参阅官方文档或其他教程。作为一个样式表示例，请参阅此 Dolphin 修改版。

GTK 与 Qt

如果您同时使用 GTK 和 Qt 应用程序，它们的外观可能无法很好地融合。如果您希望使 GTK 样式与 Qt 样式匹配，请参阅 Uniform look for Qt and GTK applications。

在 KDE Plasma 以外的环境中配置 Qt 5/6 应用程序

与 Qt 4 不同，Qt 5 没有提供用于配置字体、图标或样式的 qtconfig 工具。相反，它会尝试使用运行中的桌面环境的设置。在 KDE Plasma 或 GNOME 中这效果很好，但在其他不太流行的桌面环境或窗口管理器中，这可能导致 Qt 5 应用程序缺少图标。解决此问题的一种方法是通过设置 XDG_CURRENT_DESKTOP=KDE 或 GNOME 来伪装正在运行的桌面环境，然后使用相应的配置应用程序来设置所需的图标集。

另一种解决方案由 qt5ct/qt6ct 软件包提供，它们提供了一个独立于桌面环境的 QPA 和一个配置实用程序。安装软件包后，运行 qt5ct/qt6ct 以设置图标主题，并设置环境变量 QT_QPA_PLATFORMTHEME=qt5ct (或 qt6ct)，以便 Qt 应用程序能够读取设置。或者，在启动 Qt 5 应用程序时使用 --platformtheme qt5ct 作为参数。

qt5ct-kde^AUR 和 qt6ct-kde^AUR 提供了打过补丁的 qt5ct/qt6ct，与 KDE 应用程序集成更好，包括 KDE QML 应用程序，并且可以读取和应用 KColorSchemes。

如果收到以下错误，且某些应用程序中仍然不显示某些图标，请安装 oxygen 和 oxygen-icons。

Icon theme "oxygen" not found.
Icon theme "oxygen" not found.
Error: standard icon theme "oxygen" not found!

开发

支持的平台

Qt 支持目前可用的大多数平台，甚至包括一些相对罕见的平台，且新的移植版本不断出现。有关更完整的列表，请参见 Qt 维基百科文章。

Android

注意 Qt Creator 4.12 或更高版本可以自动设置 SDK 工具、NDK 和必要的软件包。有关更多信息，请参阅 Qt Creator: 指定 Android 设备设置。

首先，您需要从 AUR 或通过 Android Studio 获取 Android SDK 和 NDK。

SDK 还需要 OpenJDK。不同的 Qt 版本有不同的版本要求，详情请查看此处。

接下来，您需要 Android 版 Qt 5。您可以按照下述方法从 AUR 安装它，或者自行编译，编译说明可以在 Qt 的维基页面找到。

如果遇到问题，建议访问已知问题页面。

本文或本章节已过时。

原因： 以下 AUR 软件包已停止构建并被维护者删除。建议的替代方案是 QT6 软件包（在 Talk:Qt 中讨论）。

android-armv7a-eabi-qt5^AUR^{[链接失效: 未找到软件包]} - armeabi-v7a
android-aarch64-qt5^AUR^{[链接失效: 未找到软件包]} - aarch64
android-x86-qt5^AUR^{[链接失效: 未找到软件包]} - x86
android-x86-64-qt5^AUR^{[链接失效: 未找到软件包]} - x86_64

或者，您可以使用官方 Qt 安装程序。

工具

以下是官方的 Qt 工具：

Qt Creator — 为 Qt 量身定制的跨平台 IDE，支持其所有功能。

https://doc.qt.ac.cn/qtcreator/ || qtcreator

注意安装相关的可选依赖以使用 Qt Creator 中的其他工具，例如调试器或版本控制。

Qt Linguist — 一套用于加快 Qt 应用程序翻译和国际化进程的工具。

https://doc.qt.ac.cn/qt-6/qtlinguist-index.html || Qt 6: qt6-tools, Qt 5: qt5-tools, Qt 4: qt4^AUR

Qt Assistant — 一个可配置且可重新分发的 Qt qch 文件文档阅读器。

https://doc.qt.ac.cn/qt-6/qtassistant-index.html || Qt 6: qt6-tools, Qt 5: qt5-tools, Qt 4: qt4^AUR

Qt Widgets Designer — 一个强大的跨平台 GUI 布局和表单构建器，适用于 Qt 窗口部件。

https://doc.qt.ac.cn/qt-6/qtdesigner-manual.html || Qt 6: qt6-tools, Qt 5: qt5-tools, Qt 4: qt4^AUR

Qt Quick Designer — 一个支持 WYSIWYG（所见即所得）的 QML 文件可视化编辑器。它允许您快速地从零开始设计和构建 Qt Quick 应用程序和组件。

https://doc.qt.ac.cn/qtcreator/creator-qtquickdesigner-plugin.html || qtcreator

qmlscene — 一个用于加载 QML 文档的工具，使得快速开发和调试 QML 应用程序变得容易。

https://doc.qt.ac.cn/qt-5/qtquick-qmlscene.html || Qt 6: qt6-declarative, Qt 5: qt5-declarative, Qt 4 QML Viewer: qt4^AUR

qmake — 一个帮助简化跨平台开发项目构建过程的工具，类似于 cmake，但选项较少且专为 Qt 应用程序量身定制。

https://doc.qt.ac.cn/qt-6/qmake-manual.html || Qt 6: qt6-base, Qt 5: qt5-base, Qt 4: qt4^AUR

uic — 一个读取 *.ui XML 文件并生成相应 C++ 文件的工具。

https://doc.qt.ac.cn/qt-6/uic.html || Qt 6: qt6-base, Qt 5: qt5-base, Qt 4: qt4^AUR

rcc — 一个在构建过程中用于将资源（如图片）嵌入 Qt 应用程序的工具。它通过生成一个包含 Qt 资源 (.qrc) 文件中指定数据的 C++ 源文件来工作。

https://doc.qt.ac.cn/qt-6/rcc.html || Qt 6: qt6-base, Qt 5: qt5-base, Qt 4: qt4^AUR

moc — 一个处理 Qt 的 C++ 扩展（信号与槽机制、运行时类型信息、动态属性系统等）的工具。

https://doc.qt.ac.cn/qt-6/moc.html || Qt 6: qt6-base, Qt 5: qt5-base, Qt 4: qt4^AUR

故障排除

禁用/更改 Qt 日志记录行为

当使用 KDE 和/或其他 Qt 桌面环境时，调试信息可能会频繁记录在 systemd 日志中。

设置 QT_LOGGING_RULES 作为环境变量来更改此行为，例如，完全禁用日志记录：

/etc/environment

QT_LOGGING_RULES='*=false'

要仅禁用调试日志记录，请使用 QT_LOGGING_RULES="*.debug=false"。

图标主题未应用

自 Qt 5.1 起，SVG 支持已移至一个模块中。由于 qt5-base 不依赖于 qt5-svg，可能会出现安装了 qt5-base 但未安装 qt5-svg 的情况。这会导致图标主题行为异常。由于不支持 SVG，图标会被静默跳过，图标主题看起来似乎未被使用。安装 qt5-svg 可以解决此问题。

主题未应用于 root 用户运行的应用程序

由于其他账户不会读取用户主题文件 ($XDG_CONFIG_HOME/Trolltech.conf)，所选主题将不会应用于以 root 身份运行的 X 应用程序。可能的解决方案包括：

创建符号链接，例如：

# ln -s /home/[username]/.config/Trolltech.conf /etc/xdg/Trolltech.conf

配置系统级主题文件：/etc/xdg/Trolltech.conf
以 root 身份调整主题

Qt 4 样式未生效

如果纯 Qt 4（非 KDE）应用程序没有使用您选定的 Qt 4 样式，那么您可能需要告知 Qt 4 如何找到 KDE 的样式（Oxygen, Phase 等）。您只需要设置环境变量 QT_PLUGIN_PATH。例如：

QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/

此时 qtconfig-qt4 应该能够找到您的 kde 样式，一切应该看起来又正常了！

或者，您可以将 Qt 4 样式目录符号链接到 KDE4 样式目录。

# ln -s /usr/lib/{kde,qt}4/plugins/styles/theme_name

所有基于 Qt 5 的应用程序在 Qt 5 更新后无法运行

如果您收到类似以下的错误：

Qt FATAL: Cannot mix incompatible Qt library (version 0x50900) with this library (version 0x50901)

那么您很可能正在使用一个尚未针对最新版 Qt 5 重新编译的 Qt 5 平台主题或样式插件。这些通常使用 Qt 私有头文件，这意味着它们依赖于 Qt 的确切版本，而不仅仅是匹配的 soname。通过检查 QT_STYLE_OVERRIDE 和 QT_QPA_PLATFORMTHEME 环境变量找出您正在使用的主题/样式，并重新构建提供它的 AUR 软件包。

QXcbConnection: XCB error: 2 (BadValue)

创建一个包含此类内容的文件 [1]

/etc/xdg/QtProject/qtlogging.ini

[Rules]
qt.qpa.xcb.xcberror=false

图形显示错位或缩放不当

请参阅 HiDPI#Qt 5。

Qt 应用程序中死键 (Dead keys) 无效

如果您已经设置了正确的键盘配置，并且死键在 GTK 应用程序（或其他窗口部件工具包）中正常工作，但在 KDE 或任何 Qt 应用程序中无效，那么您可能没有在 Xorg 会话中加载正确的组合键映射文件 (compose file)。

确认这一点的办法是：

在启用 qt.xkb.compose.debug 日志规则的情况下启动一个 Qt 应用程序，例如启动 qtqr^AUR：QT_LOGGING_RULES=qt.xkb.compose.debug=true qtqr
然后尝试使用死键编写一个字符，例如 <dead_circumflex> <e> 得到 ê (拉丁小写字母 E 带抑扬符)
如果您遇到 qt.xkb.compose: failed to create compose table，那么您可能确实遇到了这个问题。

要修复此问题，首先确定您的区域设置 (locale)。然后，如果您的区域设置在 /usr/share/X11/locale/ 中没有自己的文件夹（例如 fr_FR.UTF-8），请在 compose.dir 映射文件中查找它以找到相应的组合键映射文件（例如 en_US.UTF-8/Compose）。

$ grep fr_FR.UTF-8 /usr/share/X11/locale/compose.dir

en_US.UTF-8/Compose             fr_FR.UTF-8
en_US.UTF-8/Compose:            fr_FR.UTF-8

现在创建或编辑 ~/.XCompose 以包含此组合键映射文件：

~/.XCompose

include "%S/en_US.UTF-8/Compose"

最后，重启您的 Qt 应用程序，死键应该可以工作了，并且当您使用 QT_LOGGING_RULES=qt.xkb.compose.debug=true 进行调试时，qt.xkb.compose: failed to create compose table 错误也应该消失了。

文件对话框非常缓慢并导致相关应用程序崩溃

~/.config/QtProject.conf 文件中被填充了垃圾数据并且大小达到了数百 MiB：删除它即可。[2][3]

Wayland 下的 Qt 6.7 有时会忽略输入法

Qt 为 Wayland 平台引入了 text-input-v3。然而，该实现尚不完善，可能会导致严重的问题，阻止输入法的使用。

如果您的 Wayland 合成器支持 text-input-v2，请全局设置以下环境变量：

/etc/environment

QT_WAYLAND_TEXT_INPUT_PROTOCOL=zwp_text_input_v2

尽管安装了彩色表情符号字体，表情符号仍显示为黑白

本文或本节正考虑移除。

原因： 与 Fonts#Emoji and symbols 重复（在 Talk:Qt 中讨论）

Qt 不支持自动查找表情符号的最佳字体，因此用户必须手动添加彩色表情符号字体作为回退方案。[4]

要做到这一点，将此 gist 的内容保存到 /etc/fonts/conf.d/75-noto-color-emoji.conf。这会将 noto-fonts-emoji 添加为回退方案，不过如果用户需要，也可以用其他字体族替换 "Noto Color Emoji"。

之后，重启受影响的 Qt 应用程序以加载新的字体设置。

Wayland 下崩溃或缩放错误

一些 Qt 应用程序（如 keepassxc）在 Wayland 上会导致崩溃 [5] 或出现缩放问题 [6]。

要修复此问题，请按照 Wayland#Qt 中的说明安装 qt5-wayland。

KDE 全局菜单不工作

一些 Qt 5 应用程序（如 keepassxc）无法使用 KDE 的全局菜单 [7]。

要修复它，请按照 KDE#Plasma 6 Global Menu not working with some applications 中的说明安装 plasma5-integration。

Qt 6 应用程序不应出现此问题，因为 plasma-integration 会由 plasma-workspace 拉取。

参见