QPalette Class
QPalette 类包含针对每个控件状态的颜色组。更多内容...
| 头文件: | #include <QPalette> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
- 所有成员的列表,包括继承的成员
- 已弃用的成员
- QPalette 属于隐式共享类。
公共类型
| enum | ColorGroup { Disabled, Active, Inactive, Normal } |
| enum | ColorRole { Window, WindowText, Base, AlternateBase, ToolTipBase, …, NoRole } |
公共函数
| QPalette() | |
| QPalette(Qt::GlobalColor button) | |
| QPalette(const QColor &button) | |
| QPalette(const QColor &button, const QColor &window) | |
| QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window) | |
| QPalette(const QPalette &p) | |
| QPalette(QPalette &&other) | |
| ~QPalette() | |
(since 6.6) const QBrush & | accent() const |
| const QBrush & | alternateBase() const |
| const QBrush & | base() const |
| const QBrush & | brightText() const |
| const QBrush & | brush(QPalette::ColorGroup group, QPalette::ColorRole role) const |
| const QBrush & | brush(QPalette::ColorRole role) const |
| const QBrush & | button() const |
| const QBrush & | buttonText() const |
| qint64 | cacheKey() const |
| const QColor & | color(QPalette::ColorGroup group, QPalette::ColorRole role) const |
| const QColor & | color(QPalette::ColorRole role) const |
| QPalette::ColorGroup | currentColorGroup() const |
| const QBrush & | dark() const |
| const QBrush & | highlight() const |
| const QBrush & | highlightedText() const |
| bool | isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const |
| bool | isCopyOf(const QPalette &p) const |
| bool | isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const |
| const QBrush & | light() const |
| const QBrush & | link() const |
| const QBrush & | linkVisited() const |
| const QBrush & | mid() const |
| const QBrush & | midlight() const |
| const QBrush & | placeholderText() const |
| QPalette | resolve(const QPalette &other) const |
| void | setBrush(QPalette::ColorRole role, const QBrush &brush) |
| void | setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush) |
| void | setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color) |
| void | setColor(QPalette::ColorRole role, const QColor &color) |
| void | setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window) |
| void | setCurrentColorGroup(QPalette::ColorGroup cg) |
| const QBrush & | shadow() const |
| void | swap(QPalette &other) |
| const QBrush & | text() const |
| const QBrush & | toolTipBase() const |
| const QBrush & | toolTipText() const |
| const QBrush & | window() const |
| const QBrush & | windowText() const |
| operator QVariant() const | |
| bool | operator!=(const QPalette &p) const |
| QPalette & | operator=(QPalette &&other) |
| QPalette & | operator=(const QPalette &p) |
(since 6.6) bool | operator==(const QPalette &p) const |
相关的非成员
| QDataStream & | operator<<(QDataStream &s, const QPalette &p) |
| QDataStream & | operator>>(QDataStream &s, QPalette &p) |
详细说明
调色板由三个颜色组组成:活动、禁用和 非活动。Qt Widgets 中的所有小部件都包含一个调色板,并使用该调色板来绘制自身。这使得用户界面易于配置,也更容易保持一致性。
如果您创建一个新的控件,我们强烈建议您使用调色板中的颜色,而不是硬编码特定的颜色。
颜色组:
- “活动”组用于具有键盘焦点的窗口。
- “非活动”组用于其他窗口。
- “禁用”组用于因某种原因被禁用的控件(而非窗口)。
活动窗口和非活动窗口都可能包含被禁用的控件。(被禁用的控件通常被称为“不可用 ”或“灰显”。)
在大多数样式中,“活动”和“非活动”的外观相同。
可以通过 `setColor()` 和 `setBrush()` 为调色板中任何颜色组中的特定角色设置颜色和画笔。一个颜色组包含一组用于控件绘制自身的颜色。 我们建议控件使用调色板中的颜色组角色(如“foreground”和“base”),而非“red”或“turquoise”这类具体颜色名称。这些颜色角色在《ColorRole 》文档中进行了列举和定义。
我们强烈建议您使用当前样式的默认调色板(由QGuiApplication::palette() 返回),并根据需要对其进行修改。Qt Widgets 在绘制时会执行此操作。
要修改颜色组,请根据您需要纯色还是位图图案,调用函数setColor() 和setBrush()。
此外还有相应的color() 和brush() 获取器,以及用于获取当前ColorGroup 的ColorRole 的常用便捷函数:window()、windowText()、base() 等。
您可以使用复制构造函数来复制调色板,并通过isCopyOf()来测试两个调色板是否相同。
QPalette 通过使用隐式共享进行了优化,因此将 QPalette 对象作为参数传递非常高效。
警告:某些 样式并非在所有绘制操作中都使用调色板,例如,当它们使用原生主题引擎时。Windows Vista 和 macOS 样式均属此类情况。
另请参阅 QApplication::setPalette()、QWidget::setPalette() 和QColor 。
成员类型文档
enum QPalette::ColorGroup
| 常数 | 值 | 描述 |
|---|---|---|
QPalette::Disabled | 1 | |
QPalette::Active | 0 | |
QPalette::Inactive | 2 | |
QPalette::Normal | Active | “Active”的同义词 |
enum QPalette::ColorRole

ColorRole 枚举定义了当前图形用户界面(GUI)中使用的各种符号颜色角色。
主要角色包括:
| 常量 | 值 | 描述 |
|---|---|---|
QPalette::Window | 10 | 一种通用的背景色。 |
QPalette::WindowText | 0 | 通用前景色。 |
QPalette::Base | 9 | 主要用作文本输入控件的背景色,但也可用于其他绘制操作——例如组合框下拉列表和工具栏控件的背景。通常为白色或其他浅色。 |
QPalette::AlternateBase | 16 | 在行颜色交替显示的视图中用作备用背景色(参见QAbstractItemView::setAlternatingRowColors())。 |
QPalette::ToolTipBase | 18 | 用作QToolTip 和QWhatsThis 的背景色。工具提示使用QPalette 中的“非活动”颜色组,因为工具提示不是活动窗口。 |
QPalette::ToolTipText | 19 | 用作QToolTip 和QWhatsThis 的前景色。工具提示使用QPalette 中的“非活动”颜色组,因为工具提示不是活动窗口。 |
QPalette::PlaceholderText | 20 | 用作各种文本输入控件的占位符颜色。该枚举值自 Qt 5.12 起引入 |
QPalette::Text | 6 | Base 使用的前景色。该颜色通常与WindowText 相同,此时必须与Window 和Base 形成良好的对比。 |
QPalette::Button | 1 | 按钮的一般背景色。该背景色可能与Window 不同,因为某些样式要求按钮使用不同的背景色。 |
QPalette::ButtonText | 8 | 与Button 颜色搭配使用的前景色。 |
QPalette::BrightText | 7 | 一种与WindowText 截然不同、且与Dark 等颜色形成良好对比的文本颜色。通常用于需要在Text 或WindowText 导致对比度较差的位置显示文本的情况,例如被按下的按钮上。 请注意,文本颜色不仅限于文字;虽然文本颜色通常用于文本,但将文本颜色角色应用于线条、图标等也是相当常见的。 |
还有一些颜色角色主要用于 3D 斜面和阴影效果。这些通常都源自Window ,其使用方式取决于这种关联关系。例如,按钮依赖该关联使斜面效果更美观,而 Motif 滚动条则依赖Mid 使其与Window 略有不同。
| 常量 | 值 | 描述 |
|---|---|---|
QPalette::Light | 2 | 比Button 的颜色更浅。 |
QPalette::Midlight | 3 | 介于Button 和Light 之间。 |
QPalette::Dark | 4 | 比Button 更深。 |
QPalette::Mid | 5 | 介于Button 和Dark 之间。 |
QPalette::Shadow | 11 | 一种非常深的颜色。默认情况下,阴影颜色为Qt::black 。 |
选中(标记)的项目有两种作用:
| 常量 | 值 | 描述 |
|---|---|---|
QPalette::Highlight | 12 | 用于标识已选中项目或当前项目的颜色。默认情况下,高亮色为Qt::darkBlue 。 |
QPalette::Accent (since Qt 6.6) | 21 | 一种通常与“基础”、“窗口”和“按钮”颜色形成对比或互补的颜色。它通常代表用户对桌面个性化的选择。交互式组件的样式设计是一个典型的应用场景。除非显式设置,否则默认为“高亮色”。 |
QPalette::HighlightedText | 13 | 一种与Highlight 形成对比的文本颜色。默认情况下,高亮文本的颜色为Qt::white 。 |
与超链接相关的有两个颜色角色:
| 常量 | 值 | 描述 |
|---|---|---|
QPalette::Link | 14 | 用于未访问超链接的文本颜色。默认情况下,链接颜色为Qt::blue 。 |
QPalette::LinkVisited | 15 | 已访问超链接所用的文本颜色。默认情况下,linkvisited 颜色为Qt::magenta 。 |
请注意,在 Qt XML 中渲染富文本时,我们不使用 `Link ` 和 `LinkVisited ` 角色,建议您使用 CSS 以及 `QTextDocument::setDefaultStyleSheet()` 函数来更改链接的外观。例如:
QTextBrowser browser;
QColor linkColor(Qt::red);
QString sheet = QString::fromLatin1("a { text-decoration: underline; color: %1 }").arg(linkColor.name());
browser.document()->setDefaultStyleSheet(sheet);| 常量 | 值 | 描述 |
|---|---|---|
QPalette::NoRole | 17 | 无角色;此特殊角色通常用于表示未分配任何角色。 |
成员函数文档
QPalette::QPalette()
构建一个未设置任何颜色角色的空调色板对象。
当将其用作QWidget 的调色板时,颜色的解析方式如QWidget::setPalette()中所述。
另请参阅 QApplication::setPalette() 和QApplication::palette()。
QPalette::QPalette(Qt::GlobalColor button)
根据button 中的颜色构建配色方案。其他颜色将根据该颜色自动计算得出。Window 也将作为按钮颜色。
QPalette::QPalette(const QColor &button)
根据button 中的颜色构建调色板。其他颜色将根据该颜色自动计算得出。Window 也将作为按钮颜色。
QPalette::QPalette(const QColor &button, const QColor &window)
根据button 颜色和window 构建一个调色板。其余颜色将根据这两个颜色自动计算得出。
QPalette::QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
构建调色板。对于windowText 、button 、light 、dark 、mid 、text 、bright_text 、base 和window ,您可以传入画笔、位图或纯色。
另请参阅 QBrush 。
QPalette::QPalette(const QPalette &p)
创建p 的副本。
得益于隐式共享,此构造函数运行速度很快。
[noexcept] QPalette::QPalette(QPalette &&other)
通过移动构造创建一个 QPalette 实例,使其指向与other 原本指向的同一对象。
从该对象移动后,您只能对 `other` 进行赋值或销毁操作。任何其他操作都将导致未定义行为。
[noexcept] QPalette::~QPalette()
清除调色板。
[since 6.6] const QBrush &QPalette::accent() const
返回当前颜色组的强调笔刷。
该函数在 Qt 6.6 中引入。
const QBrush &QPalette::alternateBase() const
返回当前颜色组的备用基础笔刷。
const QBrush &QPalette::base() const
返回当前颜色组的基准画笔。
const QBrush &QPalette::brightText() const
返回当前颜色组中用于显示亮色文本的前景画笔。
const QBrush &QPalette::brush(QPalette::ColorGroup group, QPalette::ColorRole role) const
返回指定颜色group 的画笔,该画笔用于给定颜色role 。
另请参阅 color()、setBrush() 以及ColorRole 。
const QBrush &QPalette::brush(QPalette::ColorRole role) const
返回在当前ColorGroup 中为给定颜色role 设置的画笔。
这是一个重载函数。
另请参阅 color()、setBrush() 以及ColorRole 。
const QBrush &QPalette::button() const
返回当前颜色组的按钮画笔。
const QBrush &QPalette::buttonText() const
返回当前颜色组中按钮文本的前景色笔刷。
另请参阅 ` ColorRole ` 和 `brush()`。
qint64 QPalette::cacheKey() const
返回一个用于标识此QPalette 对象内容的数字。如果不同的QPalette 对象指向相同的内容,则它们可以具有相同的键。
当调色板发生更改时,cacheKey() 也会随之改变。
const QColor &QPalette::color(QPalette::ColorGroup group, QPalette::ColorRole role) const
返回指定颜色group 中的颜色,该颜色用于表示给定的颜色role 。
另请参阅 brush()、setColor() 和ColorRole 。
const QColor &QPalette::color(QPalette::ColorRole role) const
返回在当前ColorGroup 中为给定的颜色role 所设置的颜色。
这是一个重载函数。
QPalette::ColorGroup QPalette::currentColorGroup() const
返回调色板的当前颜色组。
另请参阅 setCurrentColorGroup()。
const QBrush &QPalette::dark() const
返回当前颜色组中的深色笔刷。
const QBrush &QPalette::highlight() const
返回当前颜色组的突出显示画笔。
const QBrush &QPalette::highlightedText() const
返回当前颜色组中被高亮显示的文本画笔。
bool QPalette::isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const
如果该调色板此前已设置了ColorGroup (cg )和ColorRole (cr ),则返回true ;否则返回false 。
ColorGroup cg 应小于QPalette::NColorGroups ,但也可以使用QPalette::Current 。在这种情况下,将使用先前设置的当前颜色组。
ColorRole (cr )应小于QPalette::NColorRoles 。
另请参阅 setBrush() 和currentColorGroup()。
bool QPalette::isCopyOf(const QPalette &p) const
如果该调色板与p 是彼此的副本(即其中一个是作为另一个的副本创建的,且随后均未被修改),则返回true ;否则返回false 。这比简单相等性要严格得多。
另请参阅 operator=() 和operator==()。
bool QPalette::isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const
如果颜色组cg1 等于cg2 ,则返回true (通常很快);否则返回false 。
const QBrush &QPalette::light() const
返回当前颜色组中的浅色画笔。
const QBrush &QPalette::link() const
返回当前颜色组中未访问链接的文本笔刷。
const QBrush &QPalette::linkVisited() const
返回当前颜色组中已访问链接的文本笔刷。
const QBrush &QPalette::mid() const
返回当前颜色组的中间色。
另请参阅 ` ColorRole ` 和 `brush()`。
const QBrush &QPalette::midlight() const
返回当前颜色组的中等亮度笔刷。
const QBrush &QPalette::placeholderText() const
返回当前颜色组的占位符文本画笔。
注意:在 Qt 5.12之前, 占位符文本颜色被硬编码为QPalette::text()。color() 并应用了 128 的透明度。在 Qt 6 中,它是一个独立的颜色。
QPalette QPalette::resolve(const QPalette &other) const
返回一个新的QPalette 对象,该对象是本实例与other 的并集。在本实例中设置的颜色角色具有优先级。本实例中未设置的角色将从other 中获取。
另请参阅 isBrushSet 。
void QPalette::setBrush(QPalette::ColorRole role, const QBrush &brush)
将调色板中所有组的指定颜色role 的画笔设置为指定的brush 。
另请参阅 brush()、setColor() 和ColorRole 。
void QPalette::setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush)
将指定颜色group 的画笔(该颜色用于role )设置为brush 。
这是一个重载函数。
另请参阅 brush()、setColor() 和ColorRole 。
void QPalette::setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color)
将指定颜色group (用于给定颜色role )设置为指定的纯色color 。
另请参阅 setBrush()、color() 和ColorRole 。
void QPalette::setColor(QPalette::ColorRole role, const QColor &color)
将所有颜色组中用于指定颜色role 的颜色,设置为指定的纯色color 。
这是一个重载函数。
另请参阅 brush()、setColor() 和ColorRole 。
void QPalette::setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
将组设置为cg 。对于windowText 、button 、light 、dark 、mid 、text 、bright_text 、base 和window ,您可以传入画笔、位图或纯色。
另请参阅 QBrush 。
void QPalette::setCurrentColorGroup(QPalette::ColorGroup cg)
将调色板的当前颜色组设置为cg 。
另请参阅 currentColorGroup()。
const QBrush &QPalette::shadow() const
返回当前颜色组的阴影笔刷。
[noexcept] void QPalette::swap(QPalette &other)
将此调色板实例替换为other 。该操作速度极快,且绝不会失败。
const QBrush &QPalette::text() const
返回当前颜色组的文本前景色画笔。
另请参阅 ` ColorRole ` 和 `brush()`。
const QBrush &QPalette::toolTipBase() const
返回当前颜色组的工具提示基础画笔。该画笔由QToolTip 和QWhatsThis 调用。
注意:工具 提示使用QPalette 中的“非活动”颜色组,因为工具提示不是活动窗口。
const QBrush &QPalette::toolTipText() const
返回当前颜色组的工具提示文本画笔。该画笔由QToolTip 和QWhatsThis 使用。
注意:工具 提示使用QPalette 的“非活动”颜色组,因为工具提示不是活动窗口。
const QBrush &QPalette::window() const
返回当前颜色组的窗口(通用背景)画笔。
const QBrush &QPalette::windowText() const
返回当前颜色组的窗口文本(通用前景色)画笔。
QPalette::operator QVariant() const
将调色板作为QVariant
bool QPalette::operator!=(const QPalette &p) const
如果该调色板与p 不同,则返回true (速度较慢);否则返回false (通常很快)。
注意: 比较调色板时,不会将当前的 ColorGroup 纳入考虑
另请参阅 operator==()。
[noexcept] QPalette &QPalette::operator=(QPalette &&other)
将 `other ` 通过 `move-assign` 赋值给此 `QPalette ` 实例。
QPalette &QPalette::operator=(const QPalette &p)
将p 分配给此调色板,并返回对此调色板的引用。
得益于隐式共享,此操作速度很快。
[since 6.6] bool QPalette::operator==(const QPalette &p) const
如果该调色板与p 相等,则返回true (通常很快);否则返回false (较慢)。
注意: 比较调色板时,以下内容 不予考虑:
currentColorGroup- ColorRole NoRole
该函数在 Qt 6.6 中引入。
另请参阅 operator!=()。
相关非成员
QDataStream &operator<<(QDataStream &s, const QPalette &p)
将调色板 `p ` 写入流 `s `,并返回该流的引用。
另请参阅 QDataStream 运算符的格式。
QDataStream &operator>>(QDataStream &s, QPalette &p)
从流s 中读取调色板,将其写入调色板p ,并返回该流的引用。
另请参阅 QDataStream 运算符的格式。
© 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.