NodeGui QFontWeight 枚举完全解析：从 100 到 900 的字体字重映射与实战用法

桌面应用跨平台【免费下载链接】nodeguiA library for building cross-platform native desktop applications with Node.js and CSS . React NodeGui : https://react.nodegui.org and Vue NodeGui: https://vue.nodegui.org项目地址https://gitcode.com/gh_mirrors/no/nodegui点击查看免费下载QFontWeight是 NodeGui 封装 QtQFont字体字重时暴露的核心枚举它将字体的粗细程度抽象为 100 到 900 的九个标准档位。本文以官方 API 文档中QFontWeight的枚举定义为主体结合仓库中 TypeScript 层的类型声明、C N-API 封装实现以及QFont、QTextEdit、QFontDatabase等组件的实际用法完整讲清每个枚举成员的含义、取值、跨层传递链路和典型应用场景帮助你在构建 Node.js 原生桌面 UI 时精确控制字体粗细。枚举成员总览九个标准字重档位QFontWeight枚举在 NodeGui 中的官方 API 参考位于 qfontweight.md。该枚举共定义了 9 个成员取值与 QtQFont::Weight及 CSSfont-weight的数值刻度完全对齐从最细的 Thin 到最粗的 Black 依次递增 100枚举成员数值语义说明Thin100极细体HairlineExtraLight200特细体Ultra LightLight300细体Normal400常规体默认字重Medium500中等体DemiBold600半粗体Bold700粗体ExtraBold800特粗体Black900黑体Extra Black / Heavy其中Normal 400是 CSS 与 Qt 体系中的默认字重Bold 700是传统加粗对应的档位。这组数值并非 NodeGui 自定义而是直接沿用 Qt 底层的QFont::Weight常量因此你在 Qt C 文档中查到的字重数值可以直接对照使用。在 NodeGui 源码中该枚举以 TypeScript 原生enum的形式定义在 QFont.ts 文件末尾并随包入口 index.ts 对外导出// src/lib/QtGui/QFont.ts export enum QFontWeight { Thin 100, ExtraLight 200, Light 300, Normal 400, Medium 500, DemiBold 600, Bold 700, ExtraBold 800, Black 900, }这意味着在业务代码中可以直接以import { QFontWeight } from nodegui的形式引用枚举名而不是手写魔法数字从而在 IDE 中获得完整的补全与类型提示。字重如何进入 QFont构造函数与 setWeightQFontWeight不是孤立存在的它的消费入口是 QFont 类。QFont提供了两条设置字重的路径。路径一构造函数一步指定QFont的构造函数支持以(family, pointSize, weight, italic)四个参数直接创建一个带字重的字体声明位于 QFont.tsconstructor(); constructor(font: QFont); constructor(native: NativeElement); constructor(family: string, pointSize?: number, weight?: QFontWeight, italic?: boolean);实际使用中pointSize缺省传-1表示沿用 Qt 默认点大小、weight缺省传-1表示不指定沿用默认字重import { QFont, QFontWeight } from nodegui; // 创建一个 14pt、DemiBold 字重、非斜体的 Helvetica 字体 const titleFont new QFont(Helvetica, 14, QFontWeight.DemiBold); // 只指定家族字重走 Qt 默认Normal const bodyFont new QFont(Helvetica, 12);从源码结构看TypeScript 层把weight以数字形式透传给原生 addon 的构造函数C 侧在 qfont_wrap.cpp 中以 4 参分支直接调用std::make_uniqueQFont(QString, pointSize, weight, italic)因此传入的数值必须落在 Qt 可识别的字重范围内即本文表格中的 9 个档位否则 Qt 会按内部规则就近匹配。路径二setWeight / weight 读写接口对已创建的QFont实例可通过setWeight修改、weight读取当前字重font.setWeight(QFontWeight.Black); const w: QFontWeight font.weight();TypeScript 声明位于 QFont.ts其实现是一层对 native 对象的直通调用setWeight(weight: QFontWeight): void { this.native.setWeight(weight); } weight(): QFontWeight { return this.native.weight(); }值得注意的是在跨 JS/Native 边界时字重被当作整数传输。C 封装 qfont_wrap.cpp 中的实现明确展示了这一过程Napi::Value QFontWrap::setWeight(const Napi::CallbackInfo info) { Napi::Env env info.Env(); int weight info[0].AsNapi::Number().Int32Value(); this-instance-setWeight(static_castQFont::Weight(weight)); return env.Null(); } Napi::Value QFontWrap::weight(const Napi::CallbackInfo info) { Napi::Env env info.Env(); return Napi::Value::From(env, static_castint(this-instance-weight())); }可以看到weight()的返回值同样是static_castint即 TypeScript 侧拿到的就是一个 100~900 之间的整数。这也解释了为什么QTextEdit等组件的字重接口声明为number类型——它们复用的是同一套整数编码。实战场景把字重落到具体组件上QFontWeight的最终价值体现在把带字重的QFont应用到各种控件与绘制上下文上。结合仓库源码典型用法如下。1. 应用到任意 QWidgetQWidget提供了setFont(font: QFont)方法见 QWidget.ts因此可以为标题栏、按钮等任何控件设置粗体字import { QWidget, QLabel, QFont, QFontWeight } from nodegui; const label new QLabel(NodeGui Demo); label.setFont(new QFont(Helvetica, 16, QFontWeight.Bold)); label.setParent(widget);2. 列表与表格项级别的字重控制QListWidgetItem与QTableWidgetItem都暴露了独立的setFont见 QListWidgetItem.ts 和 QTableWidgetItem.ts允许在 Model/View 架构中为单条数据指定差异化字重例如把选中项渲染为Bold、普通项保持Normal。3. 富文本编辑中的字重QTextEditQTextEdit的字重接口与QFontWeight数值体系直接互通见 QTextEdit.tssetTextFontWeight(weight: number): void fontWeight(): number这里的参数类型是number但取值就是本文表格中的 100~900 档位等价于QFontWeight的数值// 等效于 textEdit.setTextFontWeight(QFontWeight.ExtraBold) textEdit.setTextFontWeight(800);此外QTextEdit还配套提供了setFamily、setItalic、setPointSize等针对currentFont()的快捷方法currentFont(): QFont返回的同样是QFont包装对象可继续调用setWeight。4. 查询系统字体的可用字重QFontDatabase设置字重前通常需要先确认目标字体家族在系统中实际具备哪些字重档位。QFontDatabase提供了weight(family, style)查询方法返回该家族某样式对应的字重数值见 QFontDatabase.tsimport { QFontDatabase, QFont, QFontWeight } from nodegui; const db new QFontDatabase(); const styles db.styles(Helvetica); // 该家族可用样式列表 for (const style of styles) { const w db.weight(Helvetica, style); // 查询样式对应的字重值 console.log(style, w); }从源码结构看QFontDatabase.weight返回的也是QFont::Weight整数编码因此可以把它与QFontWeight枚举直接比较用于只在该家族确实存在 Bold 档位时才启用粗体这类防御性布局逻辑。5. 字体对话框联动QFontDialog的currentFont(): QFont返回用户选定的字体见 QFontDialog.ts拿到后可以直接读取weight()得到用户选择的字重档位实现所见即所得的字重配置面板。使用注意事项数值必须落在档位内setWeight与构造函数底层都会把数值强转为QFont::Weight100~900 之间每 100 一档才是规范取值中间值如 450不是QFontWeight定义的成员不建议在 NodeGui 侧直接手写。字体家族可能不具备全部字重字重档位是请求值。从源码结构看setWeight只是把请求写入QFont最终渲染效果由 Qt 根据字体家族实际包含的字面face决定若家族缺少Black字面Qt 会选择近似字重渲染。建议用QFontDatabase.weight/styles先行探测。与 setBold 的关系QFont同时提供setBold(enable: boolean)见 QFont.ts其语义是加粗与否的布尔开关而setWeight提供 9 档精细控制。需要细粒度控制如 DemiBold 与 Black 的区分时应使用QFontWeight仅需要粗/不粗二元状态时用setBold即可。同一文件内的兄弟枚举与QFontWeight同文件定义的还有 QFontStretch50~200 的宽度拉伸档位与 QFontCapitalization大小写形态三者组合使用才能完整描述一个QFont的视觉外观。小结QFontWeight是 NodeGui 字体体系中控制字重的标准化枚举9 个成员覆盖 100Thin到 900Black的全档字重数值与 QtQFont::Weight、CSSfont-weight保持同一刻度。通过QFont的构造函数或setWeight写入、通过QWidget/QListWidgetItem/QTextEdit等组件的字体接口应用、并配合QFontDatabase查询系统实际可用的字重你就可以在 Node.js 原生桌面应用中实现精确、跨平台一致的字体粗细控制。如需进一步查阅完整的QFont方法签名可参考 qfont.md。赞分享桌面应用跨平台【免费下载链接】nodeguiA library for building cross-platform native desktop applications with Node.js and CSS . React NodeGui : https://react.nodegui.org and Vue NodeGui: https://vue.nodegui.org项目地址https://gitcode.com/gh_mirrors/no/nodegui点击查看免费下载相关推荐TypeScript 枚举Enum完全指南数字枚举、常量枚举与反向映射深度解读TypeScript 枚举Enum完全指南数字枚举、常量枚举与反向映射深度解读 本文基于开源仓库 typ/typescript book https://文档教程TypeScript 枚举完全指南数字枚举、标志位、字符串枚举与 const 枚举实战解析TypeScript 枚举完全指南数字枚举、标志位、字符串枚举与 const 枚举实战解析 TypeScript 为 JavaScript 引入了 enum教程TypeScript枚举类型详解数字枚举与字符串枚举的完整用法TypeScript枚举类型详解数字枚举与字符串枚举的完整用法 TypeScript枚举类型是TypeScript中一个强大的特性它允许我们定义一组命名的常文档教程上一篇Ladda与PWA集成离线状态下的加载按钮行为处理下一篇ComfyUI-LTXVideo终极指南如何快速上手AI视频生成插件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考