Back to Qt.io
Contact Us Blog Download Qt

QLoggingCategory Class

QLoggingCategory 类代表日志基础设施中的一个类别或 "区域"。更多

头文件： #include <QLoggingCategory>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core

注意：该类中的所有函数都是线程安全的。

公共类型

CategoryFilter

公共函数

QLoggingCategory(const char *category, QtMsgType enableForLevel = QtDebugMsg)
~QLoggingCategory()
const char *categoryName() const
bool isCriticalEnabled() const
bool isDebugEnabled() const
bool isEnabled(QtMsgType msgtype) const
bool isInfoEnabled() const
bool isWarningEnabled() const
void setEnabled(QtMsgType type, bool enable)
QLoggingCategory &operator()()
const QLoggingCategory &operator()() const

静态公共成员

QLoggingCategory *defaultCategory()
QLoggingCategory::CategoryFilter installFilter(QLoggingCategory::CategoryFilter filter)
void setFilterRules(const QString &rules)

宏

(since 6.5) Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)
Q_DECLARE_LOGGING_CATEGORY(name)
Q_LOGGING_CATEGORY(name, string)
Q_LOGGING_CATEGORY(name, string, msgType)
(since 6.9) Q_STATIC_LOGGING_CATEGORY(name, string)
(since 6.9) Q_STATIC_LOGGING_CATEGORY(name, string, msgType)
qCCritical(category)
qCCritical(category, const char *message, ...)
qCDebug(category)
qCDebug(category, const char *message, ...)
(since 6.5) qCFatal(category)
(since 6.5) qCFatal(category, const char *message, ...)
qCInfo(category)
qCInfo(category, const char *message, ...)
qCWarning(category)
qCWarning(category, const char *message, ...)

详细说明

QLoggingCategory 表示运行时的某个日志记录类别（由字符串标识）。可以对类别进行配置，以启用或禁用每种消息类型的消息日志记录。致命消息是个例外，它始终处于启用状态。

要检查消息类型是否启用，请使用以下方法之一：isDebugEnabled(),isInfoEnabled(),isWarningEnabled(), 和isCriticalEnabled() 。

如Configuring Categories 所述，所有对象都应通过通用注册表进行配置。不同的对象也可以代表同一类别。因此，不建议跨模块导出对象、直接操作对象或继承 QLoggingCategory。

创建类别对象

Q_DECLARE_LOGGING_CATEGORY() 和Q_LOGGING_CATEGORY() 宏可以方便地声明和创建 QLoggingCategory 对象：

// in a header
Q_DECLARE_LOGGING_CATEGORY(driverUsb)

// in one source file
Q_LOGGING_CATEGORY(driverUsb, "driver.usb")

还有Q_DECLARE_EXPORTED_LOGGING_CATEGORY() 宏，用于跨库使用日志类别。

类别名称是自由文本；要使用Logging Rules 配置类别，其名称应遵循此约定：

  • 只能使用字母和数字。
  • 使用圆点将类别进一步结构化为共同区域。
  • 避免使用类别名称：debug,info,warning, 和critical 。
  • 带有qt 前缀的类别名称仅供 Qt 模块使用。

由Q_LOGGING_CATEGORY() 隐式定义的 QLoggingCategory 对象会在首次使用时以线程安全的方式创建。

检查类别配置

QLoggingCategory 提供了isDebugEnabled(),isInfoEnabled(),isWarningEnabled(),isCriticalEnabled() 和isEnabled() 来检查是否应记录给定消息类型的消息。

如果类别未启用相应的消息类型，qCDebug() 、qCWarning() 和qCCritical() 宏会阻止参数被评估，因此不需要进行显式检查：

    // usbEntries() will only be called if driverUsb category is enabled
    qCDebug(driverUsb) << "devices: " << usbEntries();

默认类别配置

QLoggingCategory 构造函数和Q_LOGGING_CATEGORY() 宏都接受一个可选的QtMsgType 参数，该参数会禁用所有严重程度较低的消息类型。也就是说，用

Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)

声明的类别会记录QtWarningMsg,QtCriticalMsg,QtFatalMsg 类型的消息，但忽略QtDebugMsg 和QtInfoMsg 类型的消息。

如果没有传递参数，则记录所有消息。只有以qt 开头的 Qt XML 内部类别会以不同方式处理：对于这些类别，默认情况下只记录QtInfoMsg,QtWarningMsg,QtCriticalMsg, 和QFatalMsg 类型的消息。

注意： 记录类别不受 C++ 生成配置的影响。也就是说，是否打印消息不会因代码是使用调试符号（"Debug Build"）、优化（"Release Build"）还是其他组合编译而改变。

配置类别

你可以通过设置日志记录规则或安装自定义过滤器来覆盖默认的类别配置。

日志记录规则

通过日志记录规则，可以灵活地启用或禁用类别日志记录。规则以文本形式指定，每行必须具有以下格式：

    <category>[.<type>] = true|false

<category> 是类别名称，第一个或最后一个字符可能使用 作为通配符号；或在两个位置都使用。可选的 必须是 , , 或 。不符合这一方案的行将被忽略。* <type> debug info warning critical

规则按文本顺序评估，从第一条到最后一条。也就是说，如果有两条规则适用于一个类别/类型，则应用后面的规则。

可通过setFilterRules() 设置规则：

    QLoggingCategory::setFilterRules("*.debug=false\n"
                                     "driver.usb.debug=true");

日志规则自动从日志配置文件[Rules] 部分加载。这些配置文件可在 QtProject 配置目录中查找，或在QT_LOGGING_CONF 环境变量中明确设置：

    [Rules]
    *.debug=false
    driver.usb.debug=true

日志记录规则也可以在QT_LOGGING_RULES 环境变量中指定；多个规则也可以用分号分隔：

    QT_LOGGING_RULES=*.debug=false;driver.usb.debug=true

setFilterRules() 设置的规则优先于 QtProject 配置目录中指定的规则。反过来，这些规则可以被QT_LOGGING_CONF 指定的配置文件中的规则和QT_LOGGING_RULES 设置的规则覆盖。

评估顺序如下：

  1. [QLibraryInfo::DataPath]/qtlogging.ini
  2. QtProject/qtlogging.ini
  3. setFilterRules()
  4. QT_LOGGING_CONF
  5. QT_LOGGING_RULES

QtProject/qtlogging.ini 文件会在QStandardPaths::GenericConfigLocation 返回的所有目录中查找。

设置QT_LOGGING_DEBUG 环境变量，以了解日志记录规则的加载位置。

安装自定义过滤器

作为文本规则的低级替代方案，您还可以通过installFilter() 实现自定义过滤器。在这种情况下，所有过滤规则都会被忽略。

打印类别

使用%{category} 占位符在默认消息处理程序中打印类别：

    qSetMessagePattern("%{category} %{message}");

成员类型文档

QLoggingCategory::CategoryFilter

这是指向具有以下签名的函数指针的类型定义：

void myCategoryFilter(QLoggingCategory *);

具有此签名的函数可通过installFilter() 安装。

成员函数文档

[explicit] QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel = QtDebugMsg)

用提供的category 名称构造一个 QLoggingCategory 对象，并启用所有类型至少与enableForLevel 一样冗长的信息，默认为QtDebugMsg （启用所有类别）。

如果category 是nullptr ，则使用类别名称"default" 。

注意： 在此对象的生命周期内，category 必须保持有效。使用字符串字面意义是实现这一目的的常用方法。

[noexcept] QLoggingCategory::~QLoggingCategory()

销毁QLoggingCategory 对象。

const char *QLoggingCategory::categoryName() const

返回类别的名称。

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

返回qDebug(),qInfo(),qWarning(),qCritical() 或qFatal() 等使用的全局类别"default" 的指针。

注意： 在销毁静态对象时，返回的指针可能为空。此外，不要使用delete 这个指针，因为类别的所有权不会转移。

[static] QLoggingCategory::CategoryFilter QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)

控制日志类别的配置方式。

安装一个函数filter ，用于确定应启用哪些类别和信息类型。如果filter 是nullptr ，则恢复默认的消息过滤器。返回指向先前安装的过滤器的指针。

在installFilter() 返回之前，每个已存在的QLoggingCategory 对象都会传给过滤器，过滤器可通过setEnabled() 自由更改每个类别的配置。任何没有更改的类别都将保留先前过滤器给定的配置，因此新过滤器在对现有类别进行初始传递时无需委托先前过滤器。

随后添加的任何新类别都将传递给新的过滤器；如果过滤器只想调整少数几个类别的配置，而不是完全覆盖日志记录策略，那么可以先将新类别传递给先前的过滤器，使其获得标准配置，然后再根据需要进行调整（如果它是过滤器特别感兴趣的类别之一的话）。安装新过滤器的代码可以记录installFilter() 的返回值，以便过滤器在以后的调用中使用。

在定义过滤器时，请注意可以从不同线程调用过滤器，但绝不能同时调用。该过滤器不能调用QLoggingCategory 中的任何静态函数。

例如

static QLoggingCategory::CategoryFilter oldCategoryFilter = nullptr;

void myCategoryFilter(QLoggingCategory *category)
{
    // For a category set up after this filter is installed, we first set it up
    // with the old filter. This ensures that any driver.usb logging configured
    // by the user is kept, aside from the one level we override; and any new
    // categories we're not interested in get configured by the old filter.
    if (oldCategoryFilter)
        oldCategoryFilter(category);

    // Tweak driver.usb's logging, over-riding the default filter:
    if (qstrcmp(category->categoryName(), "driver.usb") == 0)
        category->setEnabled(QtDebugMsg, true);
}

安装（例如在main() 中）：

oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);

另外，您也可以通过setFilterRules() 配置默认过滤器。

bool QLoggingCategory::isCriticalEnabled() const

如果应显示该类别的关键信息，则返回true ；否则返回false 。

注意： 在执行任何代码之前，qCCritical() 宏已经进行了这种检查。不过，调用该方法可能有助于避免生成仅用于调试输出的昂贵数据。

bool QLoggingCategory::isDebugEnabled() const

如果应显示该类别的调试信息，则返回true ；否则返回false 。

注意： 在运行任何代码之前，qCDebug() 宏已经进行了这种检查。不过，调用此方法可能有助于避免生成仅用于调试输出的昂贵数据。

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

如果应显示类别类型为msgtype 的信息，则返回true ；否则返回false 。

bool QLoggingCategory::isInfoEnabled() const

如果该类别应显示信息消息，则返回true ；否则返回false 。

注意： 在执行任何代码之前，qCInfo() 宏已经进行了这种检查。不过，调用该方法可能有助于避免生成仅用于调试输出的昂贵数据。

bool QLoggingCategory::isWarningEnabled() const

如果该类别应显示警告信息，则返回true ；否则返回false 。

注意： 在执行任何代码之前，qCWarning() 宏已经进行了这种检查。不过，调用该方法可能有助于避免生成仅用于调试输出的昂贵数据。

void QLoggingCategory::setEnabled(QtMsgType type, bool enable)

将类别的邮件类型type 更改为enable 。

此方法仅适用于安装了installFilter() 的过滤器。有关如何全局配置类别的概述，请参阅Configuring Categories 。

注意： QtFatalMsg 不可更改；它将始终保持true 。

另请参阅 isEnabled() 。

[static] void QLoggingCategory::setFilterRules(const QString &rules)

通过一组rules 配置应启用的类别和信息类型。

示例：

    QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));

注意： 如果使用installFilter() 安装了自定义类别过滤器，或者用户定义了QT_LOGGING_CONF 或QT_LOGGING_RULES 环境变量，则这些规则可能会被忽略。

QLoggingCategory &QLoggingCategory::operator()()

返回对象本身。这样就可以在qCDebug(),qCWarning(),qCCritical() 或qCFatal() 宏中同时使用QLoggingCategory 变量和返回QLoggingCategory 的工厂方法。

const QLoggingCategory &QLoggingCategory::operator()() const

返回对象本身。这样就可以在qCDebug(),qCWarning(),qCCritical() 或qCFatal() 宏中同时使用QLoggingCategory 变量和返回QLoggingCategory 的工厂方法。

宏文档

[since 6.5] Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)

声明日志记录类别name 。该宏可用于声明程序不同部分共享的通用日志类别。

其作用与Q_DECLARE_LOGGING_CATEGORY() 完全相同。不过，使用该宏声明的日志记录类别还需要使用EXPORT_MACRO 加以限定。如果需要从动态库中导出日志类别，这个宏就非常有用。

例如

Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcCore, LIB_EXPORT_MACRO)

该宏必须在类或函数之外使用。

此宏在 Qt 6.5 中引入。

另请参阅 Q_LOGGING_CATEGORY() 和Q_DECLARE_LOGGING_CATEGORY()。

Q_DECLARE_LOGGING_CATEGORY(name)

声明日志记录类别name 。该宏可用于声明程序不同部分共享的通用日志记录类别。

该宏必须在类或方法之外使用。

另请参阅 Q_LOGGING_CATEGORY() 和Q_DECLARE_EXPORTED_LOGGING_CATEGORY()。

Q_LOGGING_CATEGORY(name, string)

定义日志记录类别name ，并在string 标识符下进行配置。默认情况下，所有消息类型都已启用。

一个库或可执行文件中只有一个翻译单元可以定义一个具有特定名称的类别。隐式定义的QLoggingCategory 对象在首次使用时以线程安全的方式创建。

该宏必须在类或方法之外使用。

另请参见 Q_DECLARE_LOGGING_CATEGORY() 和Q_DECLARE_EXPORTED_LOGGING_CATEGORY()。

Q_LOGGING_CATEGORY(name, string, msgType)

定义日志记录类别name ，并可在string 标识符下进行配置。默认情况下，启用QtMsgType msgType 及更严重的信息，禁用严重程度较低的类型。

一个库或可执行文件中只有一个翻译单元可以定义具有特定名称的类别。隐式定义的QLoggingCategory 对象在首次使用时以线程安全的方式创建。

该宏必须在类或方法之外使用。

另请参见 Q_DECLARE_LOGGING_CATEGORY()。

[since 6.9] Q_STATIC_LOGGING_CATEGORY(name, string)

定义静态日志类别name ，并可在string 标识符下进行配置。默认情况下，所有消息类型都已启用。

日志类别使用static 限定符创建，因此只能在同一翻译单元中访问。这样可以避免意外的符号冲突。

隐式定义的QLoggingCategory 对象在首次使用时以线程安全的方式创建。

该宏必须在类或方法之外使用。

该宏在 Qt 6.9 中引入。

另请参阅 Q_LOGGING_CATEGORY().

[since 6.9] Q_STATIC_LOGGING_CATEGORY(name, string, msgType)

定义静态日志类别name ，并可在string 标识符下进行配置。默认情况下，启用QtMsgType msgType 和更严重的消息，禁用严重程度较低的类型。

日志类别使用static 限定符创建，因此只能在同一翻译单元中访问。这样可以避免意外的符号冲突。

隐式定义的QLoggingCategory 对象在首次使用时以线程安全的方式创建。

该宏必须在类或方法之外使用。

该宏在 Qt 6.9 中引入。

另请参阅 Q_LOGGING_CATEGORY().

qCCritical(category)

返回日志类别中关键信息的输出流，category 。

宏扩展为代码，用于检查QLoggingCategory::isCriticalEnabled() 是否求值为true 。如果是，则处理流参数并将其发送到消息处理程序。

示例

    QLoggingCategory category("driver.usb");
    qCCritical(category) << "a critical message";

注意： 如果未启用特定类别的关键输出，则不会处理参数，因此不要依赖任何副作用。

另请参阅 qCritical().

qCCritical(category, const char *message, ...)

将关键信息message 记录在日志类别category 中。message 可包含由附加参数替换的占位符，类似于 C 语言的 printf() 函数。

示例

    QLoggingCategory category("driver.usb");
    qCCritical(category, "a critical message logged into category %s", category.categoryName());

注意： 如果未启用特定类别的临界输出，参数将不会被处理，因此不要依赖任何副作用。

另请参见 qCritical()。

qCDebug(category)

返回日志类调试信息的输出流，category 。

宏扩展为检查QLoggingCategory::isDebugEnabled() 是否求值为true 的代码。如果求值为 ，则处理流参数并将其发送到消息处理程序。

示例

    QLoggingCategory category("driver.usb");
    qCDebug(category) << "a debug message";

注意： 如果category 的调试输出未启用，则不会处理参数，因此不要依赖任何副作用。

另请参阅 qDebug().

qCDebug(category, const char *message, ...)

将调试信息message 记录在日志类别category 中。message 可包含由附加参数替换的占位符，类似于 C 语言的 printf() 函数。

例如

    QLoggingCategory category("driver.usb");
    qCDebug(category, "a debug message logged into category %s", category.categoryName());

注意： 如果未启用category 的调试输出，则不会处理参数，因此不要依赖任何副作用。

另请参见 qDebug()。

[since 6.5] qCFatal(category)

返回日志类别中致命消息的输出流，category 。

如果您使用的是默认消息处理程序，返回的流将终止以创建核心转储。在 Windows 上，对于调试构建，该函数将报告_CRT_ERROR ，以便将调试器连接到应用程序。

举例说明：

    QLoggingCategory category("driver.usb");
    qCFatal(category) << "a fatal message. Program will be terminated!";

此宏在 Qt 6.5 中引入。

另请参见 qFatal()。

[since 6.5] qCFatal(category, const char *message, ...)

在日志类别category 中记录一条致命信息message 。message 可包含由附加参数替换的占位符，类似于 C 语言的 printf() 函数。

举例说明

    QLoggingCategory category("driver.usb");
    qCFatal(category, "a fatal message. Program will be terminated!");

如果使用默认消息处理程序，该函数将终止创建核心转储。在 Windows 上，对于调试构建，该函数将报告_CRT_ERROR ，以便将调试器连接到应用程序。

此宏在 Qt 6.5 中引入。

另请参见 qFatal()。

qCInfo(category)

返回日志类信息的输出流，category 。

该宏扩展为检查QLoggingCategory::isInfoEnabled() 是否求值为true 的代码。如果求值为 ，则处理流参数并将其发送至消息处理程序。

示例

    QLoggingCategory category("driver.usb");
    qCInfo(category) << "an informational message";

注意： 如果未启用特定类别的调试输出，则不会处理参数，因此不要依赖任何副作用。

另请参阅 qInfo().

qCInfo(category, const char *message, ...)

将信息消息message 记录在日志类别category 中。message 可能包含由附加参数替换的占位符，类似于 C 语言的 printf() 函数。

举例说明

    QLoggingCategory category("driver.usb");
    qCInfo(category, "an informational message logged into category %s", category.categoryName());

注意： 如果未启用特定类别的调试输出，则不会处理参数，因此不要依赖任何副作用。

另请参见 qInfo()。

qCWarning(category)

返回日志类别中警告信息的输出流，category 。

宏扩展为检查QLoggingCategory::isWarningEnabled() 是否求值为true 的代码。如果求值为 ，则处理流参数并将其发送至消息处理程序。

示例

    QLoggingCategory category("driver.usb");
    qCWarning(category) << "a warning message";

注意： 如果未启用特定类别的警告输出，则不会处理参数，因此不要依赖任何副作用。

另请参阅 qWarning().

qCWarning(category, const char *message, ...)

将警告信息message 记录在日志类别category 中。message 可能包含由附加参数替换的占位符，类似于 C 语言的 printf() 函数。

示例

    QLoggingCategory category("driver.usb");
    qCWarning(category, "a warning message logged into category %s", category.categoryName());

注意： 如果未启用特定类别的警告输出，则不会处理参数，因此不要依赖任何副作用。

另请参见 qWarning()。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.