QLoggingCategory Class
QLoggingCategory 类表示日志记录架构中的一个类别，或称“领域”。更多内容...
| 头文件： | #include <QLoggingCategory> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
注意：该类中的所有函数均是线程安全的。
公共类型
公共函数
| 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 内部类别会得到特殊处理：对于这些类别，默认情况下仅记录类型为QtInfoMsg 、QtWarningMsg 、QtCriticalMsg 和QFatalMsg 的消息。
注意：日志 类别不受您的 C++ 构建配置影响。也就是说，无论代码是使用调试符号（“调试构建”）、优化（“发布构建”）还是其他组合进行编译，消息的输出情况都不会改变。
配置类别
您可以通过设置日志规则或安装自定义过滤器来覆盖类别的默认配置。
日志规则
日志规则允许您以灵活的方式启用或禁用各类别的日志记录。规则以文本形式指定，其中每行必须采用以下格式：
<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 设置的规则所覆盖。
评估顺序如下：
- [QLibraryInfo::DataPath]/qtlogging.ini
- QtProject/qtlogging.ini
- setFilterRules()
QT_LOGGING_CONFQT_LOGGING_RULES
系统会在QStandardPaths::GenericConfigLocation 返回的所有目录中查找QtProject/qtlogging.ini 文件。
请设置QT_LOGGING_DEBUG 环境变量，以确定日志规则的加载位置。
安装自定义过滤器
作为文本规则的低级替代方案，您还可以通过installFilter() 实现自定义过滤器。在这种情况下，所有过滤规则都会被忽略。
打印类别
在默认消息处理程序中使用%{category} 占位符来输出类别：
qSetMessagePattern("%{category} %{message}");成员类型文档
QLoggingCategory::CategoryFilter
这是一个对具有以下签名的函数指针的typedef：
void myCategoryFilter(QLoggingCategory *);具有此签名的函数可通过 `installFilter()` 进行安装。
成员函数文档
[explicit] QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel = QtDebugMsg)
创建一个 QLoggingCategory 对象，其名称为提供的category ，并启用所有详细程度至少达到enableForLevel 的消息，其默认值为QtDebugMsg （这将启用所有类别）。
如果category 为nullptr ，则使用类别名称"default" 。
注意： 在该对象的生命周期内，category 必须保持有效。通常使用字符串字面量来实现这一点。
[noexcept] QLoggingCategory::~QLoggingCategory()
销毁一个QLoggingCategory 对象。
const char *QLoggingCategory::categoryName() const
返回类别的名称。
[static] QLoggingCategory *QLoggingCategory::defaultCategory()
返回指向全局类别"default" 的指针，该类别例如被qDebug()、qInfo()、qWarning()、qCritical()或qFatal()所使用。
注意： 在静态对象销毁期间，返回的指针 可能为空。此外，请勿对该指针进行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()()
返回该对象本身。这使得QLoggingCategory 变量和返回QLoggingCategory 的工厂方法均可用于qCDebug()、qCWarning()、qCCritical()或qCFatal()宏中。
const QLoggingCategory &QLoggingCategory::operator()() const
返回该对象本身。这使得以下两种情况均可使用：QLoggingCategory 变量，以及返回QLoggingCategory 的工厂方法，这些都可在qCDebug()、qCWarning()、qCCritical()或qCFatal()宏中使用。
宏文档
[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";注意：如果 某个特定类别的“critical”输出未启用，则不会处理这些参数，因此请勿依赖任何副作用。
另请参阅 QDebug::qCritical()。
qCCritical(category, const char *message, ...)
在日志类别category 中记录一条关键级消息message 。message 中可能包含占位符，这些占位符将被额外参数替换，类似于C语言中的printf()函数。
示例：
QLoggingCategory category("driver.usb");
qCCritical(category, "a critical message logged into category %s", category.categoryName());注意：如果 某个特定类别的关键级输出未启用，则不会处理参数，因此请勿依赖任何副作用。
另请参阅 qCritical(const char *, ...)。
qCDebug(category)
返回用于“category ”日志类别中调试消息的输出流。
该宏展开后生成的代码会检查 `QLoggingCategory::isDebugEnabled()` 是否计算结果为 `true`。如果是，则处理流参数并将其发送给消息处理程序。
示例：
QLoggingCategory category("driver.usb");
qCDebug(category) << "a debug message";注意： 如果该category 的调试输出未启用，则不会处理参数， 因此请勿依赖任何副作用。
另请参阅 QDebug::qDebug()。
qCDebug(category, const char *message, ...)
在日志类别category 中记录一条调试消息message 。message 中可能包含占位符，这些占位符将被附加参数替换，类似于 C 语言中的 printf() 函数。
示例：
QLoggingCategory category("driver.usb");
qCDebug(category, "a debug message logged into category %s", category.categoryName());注意： 如果该category 的调试输出未启用，则不会处理参数 ，因此请勿依赖任何副作用。
另请参阅 qDebug(const char *, ...)。
[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 中引入。
另请参阅 QDebug::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(const char *, ...)。
qCInfo(category)
返回一个用于“category ”日志类别中信息类消息的输出流。
该宏展开后生成一段代码，用于检查 `QLoggingCategory::isInfoEnabled()` 是否计算结果为 `true`。如果是，则处理流参数并将其发送给消息处理程序。
示例：
QLoggingCategory category("driver.usb");
qCInfo(category) << "an informational message";注意：如果 某个类别的调试输出未启用，则不会处理参数，因此请勿依赖任何副作用。
另请参阅 QDebug::qInfo()。
qCInfo(category, const char *message, ...)
在日志类别category 中记录一条信息级消息：message 。message 中可能包含占位符，这些占位符将被其他参数替换，类似于 C 语言中的 printf() 函数。
示例：
QLoggingCategory category("driver.usb");
qCInfo(category, "an informational message logged into category %s", category.categoryName());注意：如果 某个特定类别的调试输出未启用，则不会处理参数，因此请勿依赖任何副作用。
另请参阅 qInfo(const char *, ...)。
qCWarning(category)
返回用于“category ”日志类别中警告消息的输出流。
该宏展开后生成的代码会检查 `QLoggingCategory::isWarningEnabled()` 是否计算结果为 `true`。如果是，则处理流参数并将其发送给消息处理程序。
示例：
QLoggingCategory category("driver.usb");
qCWarning(category) << "a warning message";注意：如果 某个特定类别的警告输出未启用，则参数将不会被处理，因此请勿依赖任何副作用。
另请参阅 QDebug::qWarning()。
qCWarning(category, const char *message, ...)
在日志类别category 中记录一条警告消息：message 。message 中可能包含占位符，这些占位符将被附加参数替换，类似于 C 语言中的 printf() 函数。
示例：
QLoggingCategory category("driver.usb");
qCWarning(category, "a warning message logged into category %s", category.categoryName());注意：如果 未启用特定类别的警告输出，则不会处理参数，因此请勿依赖任何副作用。
另请参阅 qWarning(const char *, ...)。
© 2026 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.
