企业官网建设流程全解析

• 桌面应用
• 跨平台

导读

GlobalColor是 NodeGui 中与 Qt 的Qt::GlobalColor一一对应的枚举，集中定义了 20 个开箱即用的预置颜色（含透明色）。本篇文章将以 website/docs/api/generated/enums/globalcolor.md 为骨架，完整讲解该枚举的全部成员与数值、在QColor、QBrush、QPen、QImage中的实际用法，并结合仓库源码（TypeScript 封装层与 C++ N-API 包装层）与测试用例，帮助你彻底掌握在 NodeGui 跨平台桌面应用中直接使用预定义颜色的正确姿势。

读完本文，你将能够：直接用一行代码创建带预定义颜色的QColor、QBrush、QPen，理解GlobalColor枚举值如何穿越 TypeScript 层抵达 C++ 侧的Qt::GlobalColor，并能在表格单元格着色等真实场景中立即落地。

一、GlobalColor 是什么

GlobalColor是 NodeGui 为开发者提供的一套「预定义颜色」枚举，它的每一个成员都对应 Qt 5 中Qt::GlobalColor的一个标准颜色常量。在 NodeGui 中，这套枚举被放置在src/lib/QtEnums/GlobalColor/index.ts，并通过 src/lib/QtEnums/index.ts 统一导出：

// src/lib/QtEnums/GlobalColor/index.ts（源码实定义，与 API 文档数值完全一致） export enum GlobalColor { white = 3, black = 2, red = 7, darkRed = 13, green = 8, darkGreen = 14, blue = 9, darkBlue = 15, cyan = 10, darkCyan = 16, magenta = 11, darkMagenta = 17, yellow = 12, darkYellow = 18, gray = 5, darkGray = 4, lightGray = 6, transparent = 19, color0 = 0, color1 = 1, }

也就是说，当你从@nodegui/nodegui中导入GlobalColor时，拿到的正是上面这一组带数字值的 TS 枚举。这些数字值并不是随意的编号——它们与 Qt 原生Qt::GlobalColor的枚举值一一对应（例如black = 2、white = 3），从而保证 NodeGui 的 JS/TS 侧与原生 Qt 侧在颜色语义上严格对齐。

二、枚举成员全表（20 个预定义颜色）

官方 API 文档 globalcolor.md 列出了全部 20 个枚举成员及其数值。为便于查阅与记忆，下表将成员按「基础色 / 深色系 / 灰度系 / 特殊色」分组整理：

2.1 基础色系

2.2 深色系（Dark 变体）

2.3 灰度系

2.4 特殊色

上述「对应 Qt 颜色语义」一列遵循 QtQt::GlobalColor的标准定义（如green为 RGB(0,255,0)、transparent为 alpha=0 的透明色等），仓库的 QColor 单元测试 已对GlobalColor.green的取值做了实测验证：其green()通道为 255、red()与blue()为 0、alpha()为 255。

三、如何导入与使用

3.1 导入方式

GlobalColor是 NodeGui 顶层包的一部分，与其它 Qt 枚举一样通过统一的枚举入口导入：

// 单个导入 import { GlobalColor } from '@nodegui/nodegui'; // 或与其他类/枚举一起导入 import { GlobalColor, QColor, QBrush, QPen } from '@nodegui/nodegui';

在 CommonJS 环境下同样可用：

const { GlobalColor, QColor } = require('@nodegui/nodegui');

3.2 三种典型的传参形态

GlobalColor的成员本质上是数字（0–19），因此它可以作为「数字参数」直接传给接受GlobalColor或QColor的 API。在源码中，NodeGui 的包装类对「数字 / QColor 实例 / 字符串」三种入参做了统一兼容（见 QColor.ts）：

// 1. 数字形式：直接传入 GlobalColor 枚举成员 const color = new QColor(GlobalColor.green); // 2. QColor 实例形式 const color2 = new QColor(); // 默认色 color2.setRed(200); // 再逐个通道修改 // 3. 字符串形式 const color3 = new QColor('#00ff00'); const color4 = new QColor('blue');

其中第 1 种形式（单数字入参）在 QColor.ts 中有明确注释：当只传入一个数字参数时，即被当作QGlobalColor枚举处理，而不是 RGBA 分量：

} else if (typeof arg === 'number') { if (arguments.length === 1) { // This is for QGlobalColor enum native = new addon.QColor(arg); } else { native = new addon.QColor(arg, g, b, a); } }

这一点非常关键：new QColor(GlobalColor.green)（单参数，= 8）创建的是「预定义绿色」；而new QColor(8, 8, 8)（三参数）创建的则是 RGB(8,8,8) 的灰色调颜色，二者完全不同。

3.3 各 API 对 GlobalColor 的支持情况

在仓库中检索GlobalColor的引用，可以确认它被以下类/方法接受：

以QBrush为例，它的构造函数与setColor都做了「数字（GlobalColor）与 QColor 实例」的双通道兼容（QBrush.ts）：

export class QBrush extends Component { constructor(nativeOrGlobalColor?: NativeElement | GlobalColor | QColor, style = BrushStyle.SolidPattern) { ... } setColor(color: QColor | GlobalColor): void { if (typeof color === 'number') { this.native.setColor(color); } else { this.native.setColor(color.native); } } }

QPen.setColor与QImage.fill也采用同样的「数字直传」设计（QPen.ts、QImage.ts），这意味着你可以在绘图、填充、描边场景中无缝混用GlobalColor与自定义QColor。

四、底层原理：枚举值如何到达 Qt 侧

要真正理解GlobalColor，值得看一下它在 C++ 侧的处理方式。NodeGui 用 N-API 把 Qt 类包装成原生插件，GlobalColor的数值最终被强转为Qt::GlobalColor枚举。

在 C++ 包装层 qcolor_wrap.cpp 中，QColorWrap构造函数按参数个数分发：

} else if (info.Length() == 1) { if (info[0].IsString()) { // 字符串形式："blue"、"#00ff00" 等 QString color = QString::fromUtf8(info[0].As<Napi::String>().Utf8Value().c_str()); this->instance = std::make_unique<QColor>(color); } else if (info[0].IsNumber()) { // 数字形式：强制转换为 Qt::GlobalColor 枚举 Qt::GlobalColor color = (Qt::GlobalColor)info[0].As<Napi::Number>().Int32Value(); this->instance = std::make_unique<QColor>(color); } ... }

由此可以梳理出完整的调用链：

GlobalColor.green (= 8) │ TypeScript 枚举成员（数字 8） ▼ new QColor(GlobalColor.green) // src/lib/QtGui/QColor.ts │ 单数字入参 → 判定为 QGlobalColor 枚举 ▼ new addon.QColor(8) // N-API 原生调用 │ info.Length() == 1 且为数字 ▼ (Qt::GlobalColor)8 // src/cpp/lib/QtGui/QColor/qcolor_wrap.cpp ▼ std::make_unique<QColor>(Qt::GlobalColor::green) // 构造 Qt QColor

这条链路说明：枚举成员的数字值不是实现细节，而是跨语言边界的关键契约。只要数字值在 0–19 范围内，C++ 侧就能正确映射为对应的Qt::GlobalColor；这也是文档中每个成员都明确标注数值（= 2、= 9等）的原因。

五、实战示例：表格单元格背景着色

仓库自带示例 src/examples/modelview_2_formatting.ts 展示了GlobalColor在 Model/View 表格中的真实用法——为指定单元格设置红色背景：

import { AlignmentFlag, CheckState, GlobalColor, ItemDataRole, QAbstractTableModel, QBrush, QFont, QModelIndex, QTableView, QVariant, } from '..'; class MyModel extends QAbstractTableModel { rowCount(parent = new QModelIndex()): number { return 2; } columnCount(parent = new QModelIndex()): number { return 3; } data(index: QModelIndex, role = ItemDataRole.DisplayRole): QVariant { const row = index.row(); const col = index.column(); switch (role) { // ... DisplayRole / FontRole 等省略 ... case ItemDataRole.BackgroundRole: if (row == 1 && col == 2) { // 只给 (1,2) 单元格设置红色背景 return new QVariant(new QBrush(GlobalColor.red).native); } break; case ItemDataRole.TextAlignmentRole: if (row == 1 && col == 1) { return new QVariant(AlignmentFlag.AlignRight | AlignmentFlag.AlignVCenter); } break; case ItemDataRole.CheckStateRole: if (row == 1 && col == 0) { return new QVariant(CheckState.Checked); } break; } return new QVariant(); } } const tableView = new QTableView(); const model = new MyModel(); tableView.setModel(model); tableView.show();

这里的写法new QBrush(GlobalColor.red)充分利用了 QBrush.ts 对GlobalColor的构造支持：无需先new QColor(GlobalColor.red)再传给QBrush，一步即可完成「红色画刷」的创建。最终QVariant包住QBrush的原生实例，通过BackgroundRole提供给表格渲染。

扩展：画笔与图片填充

同样的思路可扩展到绘图场景。用GlobalColor配置画笔颜色，再配合QPainter绘制：

import { QPen, GlobalColor, PenStyle } from '@nodegui/nodegui'; const pen = new QPen(); pen.setColor(GlobalColor.darkBlue); // 直接传枚举成员 pen.setStyle(PenStyle.DashLine); // 虚线样式

用GlobalColor填充图片背景：

import { QImage, GlobalColor } from '@nodegui/nodegui'; const image = new QImage(100, 100); // 创建一个 100x100 的空白图片 image.fill(GlobalColor.lightGray); // 整图填充浅灰

六、测试验证：行为即证据

仓库中针对QColor的单元测试 QColor.test.ts 直接验证了GlobalColor的行为：

it('initialize with enum GlobalColor', () => { const color = new QColor(GlobalColor.green); expect(color.green()).toBe(255); expect(color.red()).toBe(0); expect(color.blue()).toBe(0); expect(color.alpha()).toBe(255); });

该测试证实了三点关键事实：

1. new QColor(GlobalColor.green)合法且能正确构造；
2. GlobalColor.green映射到 Qt 侧后得到的是标准绿色 RGB(0,255,0)，alpha 为 255（完全不透明）；
3. 通过color.red()/green()/blue()/alpha()可以随时读回各颜色通道值，便于断言与调试。

同一测试文件中还覆盖了QColor的其它构造形态（空构造、RGBA 数值构造、字符串构造、setRed/setGreen/setBlue/setAlpha通道修改、以及QColor.fromQVariant），完整代码见 QColor.test.ts。

七、使用建议与注意事项

7.1 单数字入参的语义陷阱

再次强调：new QColor(5)创建的是GlobalColor.gray对应的灰色，而不是 RGB(5,5,5) 的极暗色。当需要自定义 RGB 颜色时，必须使用 3 或 4 个参数的构造形式（QColor.ts）：

const custom = new QColor(5, 5, 5); // 自定义 RGB const withAlpha = new QColor(5, 5, 5, 128); // 自定义 RGBA

7.2 优先使用枚举成员而非魔法数字

虽然QColor的构造参数在 TS 侧被声明为number（这是 N-API 跨语言边界的产物），但在业务代码中请始终使用GlobalColor.red这类具名成员，而不是裸数字7。这不仅提升可读性，也能在枚举值变更时获得编译期检查。

7.3 透明度相关

GlobalColor.transparent（= 19）是 alpha 为 0 的完全透明色，适合做占位填充；而white/black等其它颜色 alpha 均为 255。若需要「半透明」效果，应改用new QColor(r, g, b, a)显式传入 alpha，或使用QColor.fromRgb / fromHsv / fromHsl系列静态方法（见 QColor.ts）。

7.4 与 QVariant 的组合

在 Model/View 体系（如表格BackgroundRole）中，GlobalColor需要先包装为QBrush（或QColor），再塞进QVariant才能被数据模型返回：

return new QVariant(new QBrush(GlobalColor.red).native);

这与示例 modelview_2_formatting.ts 中的写法一致。

结语

GlobalColor虽然只是一个包含 20 个成员的枚举，但它承载着 NodeGui 与 Qt 原生颜色体系之间的完整契约：从 TypeScript 层的具名常量，到 C++ 侧的Qt::GlobalColor强转，再到QColor/QBrush/QPen/QImage的全面接入。掌握它的成员数值、单数字入参语义与典型调用链，就能在 NodeGui 应用开发中高效地使用预定义颜色，并避免「单参数被误判为 GlobalColor」这类隐蔽陷阱。需要进一步了解颜色对象的更多能力（HSV/HSL/CMYK 转换、字符串解析等），可继续阅读 QColor.ts 源码及其 单元测试。

• 桌面应用
• 跨平台