Qt

Qt 是一个跨平台应用程序和部件工具包，它使用标准的 C++，但广泛使用特殊的代码生成器（称为元对象编译器，或 moc）以及一些宏来丰富该语言。它的一些更重要的功能包括

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

Qt 框架是 KDE 软件社区以及其他重要的开源和专有应用程序（如 VLC、VirtualBox、Mathematica 等）的基础。

安装

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 软件包中。
Qt 4.x 在 qt4^AUR 软件包中可用，文档在 qt4-doc^AUR 软件包中。
Qt 3.x 在 qt3^AUR 软件包中可用，没有文档软件包。

已知问题

本文或章节正在考虑移除。

原因： 看起来 Qt 只有 2 个已知问题 🤷 (在 Talk:Qt 中讨论)

Qt 应用程序在没有解决方法的情况下，使用变体选择器字符错误地渲染表情符号（在 QTBUG-97401 中跟踪）
如果字符在首选字体中，则 Qt 应用程序错误地渲染多字符表情符号（在 QTBUG-97400 中跟踪）

默认 Qt 工具包

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

配置

本文或章节已过时。

原因： 需要更新 qt6 (在 Talk:Qt 中讨论)

Qt 5 中的样式

本文或章节已过时。

原因： qt5-base 不再使用 QGtkStyle (在 Talk:Qt#Qt5 不再使用 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

Lightly — Lightly 是 breeze 主题风格的一个分支，旨在在视觉上现代且简约。

https://github.com/Luwx/Lightly || lightly-git^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 4 中的样式

Qt 4 应用程序将尝试模仿它们正在运行的桌面环境的行为，除非它们遇到一些问题或硬编码设置。

在 KDE Plasma 中，它使用实际选择的 Qt 样式。可以使用KDE 系统设置 (systemsettings) 进行配置，设置可以在外观 > 应用程序风格 > 部件风格中找到。
在 Cinnamon、GNOME、Xfce 中，它使用 GTK (QGtkStyle)。
在其他桌面环境中，它使用 Windows。

对于那些想要更改 Qt 4 应用程序外观的用户，qt4^AUR 软件包提供了 Qt 配置 (qtconfig-qt4) GUI 工具。它提供了一个简单的界面来配置 Qt 4 应用程序的外观，包括样式、颜色、字体和一些其他选项。

注意： 如果您使用 GTK 样式，则颜色和字体设置将被忽略，并从 GTK 2 继承。

Qt 将其所有配置信息保存在 /etc/xdg/Trolltech.conf (系统范围) 或 ~/.config/Trolltech.conf (用户特定) 中。该文件很难导航，因为它包含大量与外观无关的信息，但对于任何更改，您都可以添加到文件末尾并覆盖任何先前的值（确保将您的修改添加到 [Qt] 标题下）。

例如，要将主题更改为 QtCurve，请添加

~/.config/Trolltech.conf

...
[Qt]
style=QtCurve

以下样式包含在 Qt 4 中： CDE、Cleanlooks、GTK、Motif、Plastique、Windows。其他样式可以单独安装

Adwaita-Qt — 一种使 Qt 应用程序看起来像是属于 GNOME Shell 的样式。

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

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 维基百科文章。

Android

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

首先，您需要来自 AUR 或使用 Android Studio 的 Android SDK 和 NDK。

SDK 也需要 OpenJDK。不同的 Qt 版本有不同的版本要求，请查看此处了解详细信息。

接下来您将需要用于 Android 的 Qt 5。您可以从 AUR 安装它，如下所述，或者自己构建它，您可以在 Qt wiki 页面上找到构建说明。

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

本文或章节已过时。

原因： 以下 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 — 一个 QML 文件的可视化编辑器，支持 WYSIWYG。它允许您从头开始快速设计和构建 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

绑定

本文或章节正在考虑移除。

原因： API 参考页面超出范围。 (在 ArchWiki talk:Maintenance Team#Dealing with API reference pages 中讨论)

Qt 具有所有更流行的语言的绑定，有关完整列表，请参阅 https://wiki.qt.io/Language_Bindings。

以下示例在窗口中显示一条小的“Hello world!”消息。

C++

软件包: qt5-base
网站: https://www.qt.io/developers/
构建: g++ $(pkg-config --cflags --libs Qt5Widgets) -fPIC -o hello hello.cpp
运行: ./hello

hello.cpp

#include <QApplication>
#include <QLabel>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);
    QLabel hello("Hello world!");

    hello.show();
    return app.exec();
}

QML

软件包: qt5-declarative.
网站: https://doc.qt.ac.cn/qt-5/qtquick-qmlscene.html
运行: qmlscene hello.qml

hello.qml

import QtQuick 2.3

Rectangle {
    id: page
    width: 400; height: 100
    color: "lightgray"

    Text {
        id: helloText
        text: "Hello world!"
        anchors.horizontalCenter: page.horizontalCenter
        anchors.verticalCenter: page.verticalCenter
        font.pointSize: 24; font.bold: true
    }
}

Python (PyQt)

软件包: python-pyqt5 - Python 3 绑定

网站: https://riverbankcomputing.com/software/pyqt/intro
运行: python hello-pyqt.py.

hello-pyqt.py

import sys
from PyQt5.QtWidgets import QApplication, QLabel

app = QApplication(sys.argv)
label = QLabel("Hello world!")

label.show()
sys.exit(app.exec_())

Python (PySide2)

软件包: pyside2^AUR
网站: https://wiki.qt.io/Qt_for_Python
运行: python hello-pyside.py

hello-pyside2.py

import sys
from PySide2.QtWidgets import QApplication, QLabel

app = QApplication(sys.argv)
label = QLabel("Hello world!")

label.show()
sys.exit(app.exec_())

C#

参见 QtSharp。

故障排除

禁用/更改 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 应用程序中不起作用

如果您已设置正确的键盘配置，并且死键在 GTK 应用程序（或其他 widget 工具包）中有效，但在 KDE 或任何 Qt 应用程序中无效，那么您可能没有在您的 Xorg 会话中加载正确的 compose 文件。

一种确认方法是

启用 qt.xkb.compose.debug 日志规则启动 Qt 应用程序，例如启动 qtqr：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，那么您可能遇到了这个问题。

要解决此问题，首先确定您的 locale。然后，如果您的 locale 在 /usr/share/X11/locale/ 中没有自己的文件夹，例如 fr_FR.UTF-8，请在 compose.dir 映射文件中查找它以找到相应的 compose 文件（例如 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 以包含此 compose 文件

~/.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

尽管安装了彩色 emoji 字体，但 Emoji 仍以黑白方式渲染

本文或章节正在考虑移除。

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

Qt 不支持自动查找 emoji 的最佳字体，因此用户必须手动添加彩色 emoji 字体作为后备字体。[4]

为此，将此 gist 的内容保存到 /etc/fonts/conf.d/75-noto-color-emoji.conf。这会将 noto-fonts-emoji 添加为后备字体，但如果用户需要，可以将 “Noto Color Emoji” 替换为不同的字体系列。

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

另请参阅