Qt

Qt 是一个跨平台的应用程序和窗口小部件工具包，它使用标准的 C++，但广泛使用一个特殊的代码生成器（称为元对象编译器，或 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 Desktop 的 Breeze 可视化风格提供艺术作品、样式和资源。

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

Oxygen — KDE Oxygen 风格。

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

Darkly — Darkly 是过时的 Lightly 的现代分支，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 样式插件 — 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 样式匹配，请阅读 Qt 和 GTK 应用程序的统一外观。

在 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 应用程序能够读取设置。或者，将 --platformtheme qt5ct 作为参数传递给 Qt 5 应用程序。

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 Wikipedia 文章。

Android

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

首先，您需要一个 Android SDK 和 NDK，可以从 AUR 获取，或者使用 Android Studio。

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

接下来，您需要 Qt 5 for Android。您可以按照下文所述从 AUR 安装它，或者自行构建。您可以在 Qt wiki 页面上找到构建说明。

如果遇到问题，您可能需要访问已知问题。

本文或本章节已过时。

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

android-armv7a-eabi-qt5^AUR^{[broken link: package not found]} - armeabi-v7a
android-aarch64-qt5^AUR^{[broken link: package not found]} - aarch64
android-x86-qt5^AUR^{[broken link: package not found]} - x86
android-x86-64-qt5^AUR^{[broken link: package not found]} - 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 — 一个用于 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 应用程序的工具。它通过生成一个 C++ 源文件来实现，该文件包含 Qt 资源 (.qrc) 文件中指定的数据。

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 journal 中。

将 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 错误: 2 (BadValue)

创建一个包含以下内容的文件 [1]

/etc/xdg/QtProject/qtlogging.ini

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

图形错位或缩放不正确

请参阅 HiDPI#Qt 5。

Qt 应用程序中的死键不起作用

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

确认此问题的一种方法是：

使用启用了 qt.xkb.compose.debug 日志记录规则的 Qt 应用程序启动，例如启动 qtqr^AUR：QT_LOGGING_RULES=qt.xkb.compose.debug=true qtqr
然后尝试使用死键输入一个字符，例如 <dead_circumflex> <e> 来输入 ê（LATIN SMALL LETTER E WITH CIRCUMFLEX）。
如果您遇到 qt.xkb.compose: failed to create compose table 错误，那么您很可能遇到了此问题。

要解决此问题，首先确定您的区域设置。然后，如果您的区域设置在 /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 或 qt6-wayland。

KDE 全局菜单不起作用

一些 Qt 5 应用程序，例如 keepassxc，未能使用 KDE 的全局菜单 [7]。

要解决此问题，请按照 KDE 页面的故障排除部分中的说明安装 plasma5-integration。

Qt 6 应用程序不应有问题，因为 plasma-integration 是由 plasma-workspace 拉取的。

参见