NodeGui ColorGroup 枚举全解析:Qt 调色板色彩组取值与 QPalette 实战指南
NodeGui ColorGroup 枚举全解析:Qt 调色板色彩组取值与 QPalette 实战指南
ColorGroup(色彩组)是 NodeGui 中用于区分控件在不同界面状态下取色维度的一组枚举值,它直接对应 Qt QPalette::ColorGroup 的定义,是使用 QPalette.color() 读取调色板颜色时必传的第一参数。读完本文你将掌握 Active、Disabled、Inactive、Normal 四个成员的取值含义、与 ColorRole 的配合方式,以及如何在 NodeGui 项目中通过 QPalette 与 QColor 完成实际的取色编程。
ColorGroup 是什么:Qt 调色板里的“取色维度”
Qt 中每个 QPalette(调色板)并不是只保存一组颜色,而是按色彩组(ColorGroup) 与颜色角色(ColorRole) 两个维度组织颜色表。ColorGroup 描述的是“控件当前处于什么状态”,ColorRole 描述的是“取的是控件哪一部分的颜色(文字、背景、边框等)”。
NodeGui 在 src/lib/QtGui/QPalette.ts 中定义了与 Qt 对齐的 TypeScript 枚举:
export enum ColorGroup {
Disabled = 1,
Active = 0,
Inactive = 2,
Normal = 0,
}
这份枚举由 src/index.ts 通过 export { QPalette, ColorGroup, ColorRole } from './lib/QtGui/QPalette'; 从包入口统一导出,因此在项目中可以直接通过以下方式引入:
import { ColorGroup, ColorRole, QPalette } from '@nodegui/nodegui';
本仓库自动生成的 API 文档 colorgroup.md 即为该枚举的官方索引页,本文以其为核心展开。
枚举成员逐一解读:取值、语义与使用场景
| 成员 | 枚举值 | Qt 对应常量 | 语义 | 典型场景 |
|---|---|---|---|---|
Active |
0 |
QPalette::Active |
窗口处于激活状态 | 当前聚焦窗口中的控件 |
Normal |
0 |
QPalette::Normal |
普通/正常状态 | 与 Active 同值,绝大多数常规取色 |
Disabled |
1 |
QPalette::Disabled |
控件被禁用 | setEnabled(false) 的控件取色 |
Inactive |
2 |
QPalette::Inactive |
窗口处于非激活状态 | 后台窗口中的控件 |
Active 与 Normal 的同值关系
Active = 0 与 Normal = 0 数值相同,这是从 Qt 继承而来的设计:Qt 文档明确说明 Active 与 Normal 是同一值的别名。对绝大多数桌面应用而言,当前激活窗口内的控件取色用 Normal(或 Active)即可,二者等价。真正需要注意区分的是 Disabled 与 Inactive:
- Disabled(1):控件本身被禁用(不可交互),Qt 会自动为这类控件分配一套灰化配色;
- Inactive(2):窗口本身失焦(例如用户切到了别的应用),但控件仍然可用,配色通常会比 Active 稍淡。
这一同值细节直接决定了调色板取色代码的正确性:若你想读“禁用态”颜色却传入了 Normal,拿到的将是正常态颜色,二者 RGB 分量往往不同。
在源码中的真实调用链:QPalette.color() 如何消费 ColorGroup
枚举本身不产生作用,它的消费入口是 QPalette.color(group, role)。在 TypeScript 侧,QPalette.ts 声明了该方法:
export class QPalette extends Component {
color(group: ColorGroup, role: ColorRole): QColor {
return new QColor(this.native.color(group, role));
}
}
调用 QPalette.color() 会进入 C++ 侧的 N-API 绑定 qpalette_wrap.cpp。核心实现为:
Napi::Value QPaletteWrap::color(const Napi::CallbackInfo& info) {
Napi::Env env = info.Env();
QPalette::ColorGroup colorGroup = static_cast<QPalette::ColorGroup>(
info[0].As<Napi::Number>().Int32Value());
QPalette::ColorRole colorRole =
static_cast<QPalette::ColorRole>(info[1].As<Napi::Number>().Int32Value());
QColor color = this->instance->color(colorGroup, colorRole);
auto instance = QColorWrap::constructor.New(
{Napi::External<QColor>::New(env, new QColor(color))});
return instance;
}
这条调用链揭示了三层事实,可作为工程决策依据:
- 枚举以整数跨越 JS/C++ 边界:JS 侧传入的
ColorGroup值经Int32Value()取整后,被static_cast为QPalette::ColorGroup,因此枚举数值必须与 Qt 原生定义严格一致(0/1/2),本文表格中的取值即为官方值; - 返回值是全新的 QColor 包装对象:C++ 侧通过
QColorWrap::constructor.New(...)构造出一个新的 QColor 实例返回 JS 侧,因此QPalette.color()每次返回的都是独立可用的 QColor 对象; - 该绑定通过
InstanceMethod("color", ...)注册(见 qpalette_wrap.cpp),是 QPalette 暴露给 JS 的核心实例方法。
如何获取 QPalette 实例:QApplication.palette()
要实际使用 ColorGroup 取色,首先需要一个 QPalette 实例。当前仓库中,应用级调色板可通过 QApplication.ts 获取:
import { QApplication } from '@nodegui/nodegui';
const app = new QApplication([]);
const palette = app.palette(); // 返回 QPalette 实例
值得说明的是,本仓库的 QPalette 绑定目前仅暴露 color() 一个实例方法(见 qpalette_wrap.cpp),QWidget.palette()、QWidget.setPalette() 等接口在 QWidget.ts 中仍标注为 TODO,尚未实现。因此当前可用的典型路径是:从 QApplication 拿到系统默认调色板 → 用 ColorGroup + ColorRole 读取其中颜色 → 得到 QColor 用于自定义绘制或样式计算。
实战:用 ColorGroup 读取不同状态下的控件颜色
下面的示例展示如何读取普通状态与禁用状态下“文本色”的差异,并输出其 RGB 分量:
import { QApplication, QPalette, ColorGroup, ColorRole } from '@nodegui/nodegui';
const app = new QApplication([]);
const palette = app.palette();
// 普通状态下读取窗口文本颜色(Active/Normal 同值,传 0)
const normalText = palette.color(ColorGroup.Normal, ColorRole.WindowText);
console.log('Normal 文本色:', normalText.red(), normalText.green(), normalText.blue());
// 禁用状态下读取窗口文本颜色
const disabledText = palette.color(ColorGroup.Disabled, ColorRole.WindowText);
console.log('Disabled 文本色:', disabledText.red(), disabledText.green(), disabledText.blue());
// 后台窗口(Inactive)下的文本颜色
const inactiveText = palette.color(ColorGroup.Inactive, ColorRole.WindowText);
console.log('Inactive 文本色:', inactiveText.red(), inactiveText.green(), inactiveText.blue());
这里用到的 ColorRole 同样是 NodeGui 导出的枚举,定义于 QPalette.ts,包含从 WindowText = 0、Button = 1 到 PlaceholderText = 20 的 21 个角色,完整列表可查阅自动生成的 colorrole.md。
返回的 QColor 对象来自 QColor.ts,支持 red()、green()、blue()、alpha() 分量读取以及 rgb()、rgba()(ARGB32 数值)输出(见 QColor.ts),还可通过字符串、GlobalColor 或 RGBA 数值构造新的颜色实例(见 QColor.ts),足以支撑取色后的二次加工。
常见陷阱与使用建议
- 不要混淆 Active 与 Disabled:
Active/Normal都是 0,Disabled是 1,Inactive是 2。传错数值不会报错,但会静默返回错误状态的颜色; - 枚举值直接对应 Qt 常量:因为 C++ 侧是
static_cast强转(qpalette_wrap.cpp),任何非 0/1/2 的整数值都会产生未定义行为,务必只使用本枚举成员; - 结合 ColorRole 使用:ColorGroup 只是第一个维度,必须与 ColorRole 成对传入
QPalette.color(),两个参数缺一不可; - 系统主题差异:
QApplication.palette()返回的是当前平台/系统主题下的默认调色板,不同操作系统下同一ColorGroup + ColorRole组合的 RGB 值会不同,这正是取色时要显式指定色彩组的价值所在。
参考资源
- 枚举官方索引:colorgroup.md
- 枚举 TS 定义:QPalette.ts
- C++ 绑定实现:qpalette_wrap.cpp
- 出口统一导出:index.ts
- QPalette API 文档:qpalette.md
- 颜色角色枚举:colorrole.md