NodeGui 中 FillRule 枚举详解：OddEvenFill 与 WindingFill 填充规则的实战应用

桌面应用跨平台【免费下载链接】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点击查看免费下载导读本文深入解析 NodeGui基于 Qt 与 Node.js 的跨平台原生桌面应用框架中FillRule枚举的完整语义与用法。FillRule对应 Qt 中Qt::FillRule枚举用于决定 QPainterPath 这类自相交或嵌套路径的哪些区域应被填充是进行复杂图形绘制的关键开关。读完本文你将掌握两个枚举值的数学判定原理、在 QPainterPath 上的读写方法以及通过 QPainter.drawPath 绘制复杂形状的完整调用链。FillRule 枚举的定义与位置在 NodeGui 中FillRule定义于 TypeScript 侧的 QtEnums 模块源文件为 src/lib/QtEnums/FillRule/index.tsexport enum FillRule { OddEvenFill 0, WindingFill 1, }它由 src/lib/QtEnums/index.ts 统一导出export { FillRule } from ./FillRule;FillRule是对 Qt 原生枚举Qt::FillRule的一一映射封装包含两个成员枚举成员数值Qt 对应枚举填充判定规则FillRule.OddEvenFill0Qt::OddEvenFill奇偶规则Odd-Even RuleFillRule.WindingFill1Qt::WindingFill非零环绕规则Non-Zero Winding Rule在自动生成的 API 文档 website/docs/api/generated/enums/fillrule.md 中同样只记录了这两个枚举成员且数值分别为0与1与 TypeScript 源码完全一致。由于 TypeScript 枚举默认按声明顺序从 0 自增这两个数值也可视为隐式约定的稳定标识——它们会被直接透传到原生层。两种填充规则的数学原理FillRule解决的核心问题是当一条路径存在自相交或包含嵌套子路径时哪些区域属于内部应被填充。两种规则基于不同的判定算法OddEvenFill奇偶规则数值 0从待判定点向任意方向引一条射线统计它与路径线段子路径边界的交点个数交点个数为奇数→ 该点在路径内部被填充交点个数为偶数→ 该点在路径外部不填充。这条规则的显著特征是不关心路径的绘制方向顺时针或逆时针。对于五角星这类自相交图形采用 OddEvenFill 时中央的五边形区域因射线会穿越偶数条线段而保持镂空绘制结果是一个带空心中心的五角星轮廓。重叠区域遵循异或式的交替逻辑。WindingFill非零环绕规则数值 1同样从待判定点引射线但会统计路径与射线的方向环绕方向每穿过一条线段根据线段相对射线的走向将环绕数winding number加 1 或减 1若最终环绕数非零→ 该点位于路径内部被填充若最终环绕数为零→ 该点位于路径外部不填充。这条规则的显著特征是依赖子路径的绘制方向。仍以五角星为例若外轮廓与内部凹入部分按同一方向绘制WindingFill 会把整颗星包括中央五边形全部填充为实心若内圈反向绘制则中央区域会被挖空。实践中WindingFill常用于绘制环形、回字形等需要依靠方向区分内外边界的形状。一句话对比OddEvenFill 只看穿越次数的奇偶WindingFill 还额外统计穿越方向的净环绕数。在 QPainterPath 中的读写接口FillRule在 NodeGui 中的主要消费方是QPainterPath封装文件为 src/lib/QtWidgets/QPainterPath.ts其中提供了两个相关方法fillRule(): FillRule { return this.native.fillRule(); } setFillRule(fillRule: FillRule): void { return this.native.setFillRule(fillRule); }path.fillRule()返回当前路径的填充规则FillRule.OddEvenFill或FillRule.WindingFill。新建的QPainterPath默认采用Qt::OddEvenFillpath.setFillRule(fillRule)设置路径的填充规则在向路径添加子路径之前调用效果最佳。原生调用链验证从源码结构看这两个方法最终通过 N-API 落到 Qt 原生对象上完整的调用链是TypeScript 侧调用this.native.fillRule()/this.native.setFillRule(fillRule)见 QPainterPath.ts原生封装类QPainterPathWrap在 qpainterpath_wrap.cpp 与 qpainterpath_wrap.cpp 中实现桥接Napi::Value QPainterPathWrap::fillRule(const Napi::CallbackInfo info) { Napi::Env env info.Env(); int v static_castint(this-instance-fillRule()); return Napi::Number::From(env, v); } Napi::Value QPainterPathWrap::setFillRule(const Napi::CallbackInfo info) { Napi::Env env info.Env(); int v info[0].AsNapi::Number().Int32Value(); this-instance-setFillRule(static_castQt::FillRule(v)); return env.Null(); }可以看到枚举值在边界处以int形式传递并在原生侧强转回Qt::FillRule这正是OddEvenFill 0、WindingFill 1这两个数值约定被定义在 TypeScript 枚举中的根本原因。对应的原生方法声明位于 qpainterpath_wrap.h。绘制时的完整消费链QPainter.drawPath设置好填充规则的QPainterPath最终要交给QPainter绘制。NodeGui 的QPainter在 src/lib/QtWidgets/QPainter.ts 中暴露了drawPathdrawPath(path: QPainterPath): void { return this.native.drawPath(path.native); }因此一条完整的绘制链路是创建QPainterPath实例用moveTo、lineTo、cubicTo、quadTo、closeSubpath等构建子路径调用setFillRule(FillRule.WindingFill | FillRule.OddEvenFill)选择填充规则在 QPainter例如窗口或控件的paintEvent中获取上调用drawPath(path)完成绘制。值得说明的是QPainter.ts 中还留有drawPolygon(..., Qt::FillRule fillRule Qt::OddEvenFill)的 TODO 注释表明 Qt 的drawPolygon本身也接受填充规则参数但当前 NodeGui 封装尚未实现该方法——因此现阶段在 NodeGui 中操作填充规则统一走QPainterPath.setFillRule这一途径。实战示例用两种规则绘制五角星结合QPainterPath已有的公开 APImoveTo、lineTo、closeSubpath、setFillRule与QPainter.drawPath可以编写一个展示两种填充规则差异的最小示例。五角星属于典型的自相交路径外轮廓的五个顶点与内凹的五个顶点交替连线后中央会形成一个闭合小五边形。import { QPainterPath } from nodegui/nodegui; import { FillRule } from nodegui/nodegui; function createStarPath(cx: number, cy: number, outerRadius: number, innerRadius: number): QPainterPath { const path new QPainterPath(); path.moveTo(cx, cy - outerRadius); for (let i 1; i 5; i) { const outerAngle -Math.PI / 2 (i * 2 * Math.PI) / 5; const innerAngle -Math.PI / 2 ((i - 0.5) * 2 * Math.PI) / 5; path.lineTo(cx outerRadius * Math.cos(outerAngle), cy outerRadius * Math.sin(outerAngle)); path.lineTo(cx innerRadius * Math.cos(innerAngle), cy innerRadius * Math.sin(innerAngle)); } path.closeSubpath(); return path; } // 奇偶规则中央小五边形镂空 const hollowStar createStarPath(60, 60, 50, 20); hollowStar.setFillRule(FillRule.OddEvenFill); // 非零环绕规则整颗星实心填充各线段按同一方向绘制 const solidStar createStarPath(180, 60, 50, 20); solidStar.setFillRule(FillRule.WindingFill);将这两个 path 分别经painter.drawPath(hollowStar)与painter.drawPath(solidStar)绘制到画布即可直观看到同一几何路径在两种规则下的填充差异左侧星中央镂空右侧星整体实心。选择建议与注意事项默认值新建的QPainterPath默认使用OddEvenFill。若你的形状不含自相交或方向性嵌套两种规则的结果一致无需显式设置何时用 OddEvenFill绘制五角星、爆炸符号等自相交图形时希望重叠区域交替镂空或子路径方向不可控如从外部数据导入的路径时用它可获得与方向无关的稳定结果何时用 WindingFill绘制环形、回字形等需要靠方向区分内外的形状或希望重叠区域取并集而非镂空时注意它依赖子路径的绘制方向顺时针/逆时针构建路径时需保持一致设置时机setFillRule应在路径构建完成或构建相关子路径之前调用对同一QPainterPath反复切换规则是允许的绘制时会按当前规则生效。小结FillRule虽只是两个数值的简单枚举却是理解 NodeGui 复杂图形绘制的一把钥匙OddEvenFill 0与WindingFill 1分别对应 Qt 的奇偶规则与非零环绕规则二者通过QPainterPath.setFillRule/fillRule读写最终由QPainter.drawPath消费。相关实现可分别在 QPainterPath.ts、qpainterpath_wrap.cpp 与 QPainter.ts 中继续查阅QPainterPath的完整 API 清单见 website/docs/api/generated/classes/qpainterpath.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点击查看免费下载相关推荐NodeGui BrushStyle 枚举完全指南QBrush 填充样式与数值对照NodeGui BrushStyle 枚举完全指南QBrush 填充样式与数值对照 本指南以 NodeGui 官方 API 文档中的 BrushStyle 枚桌面应用跨平台NodeGui 中的 ApplicationAttribute 枚举详解从 Qt 应用级属性到 Node.js 桌面应用实践NodeGui 中的 ApplicationAttribute 枚举详解从 Qt 应用级属性到 Node.js 桌面应用实践 导读 ApplicationAt桌面应用跨平台NodeGui 中 SequenceMatch 枚举详解QKeySequence 按键序列匹配的原理与实战NodeGui 中 SequenceMatch 枚举详解QKeySequence 按键序列匹配的原理与实战 SequenceMatch 是 Node.js 跨桌面应用跨平台上一篇Immich 数据库迁移实战schema 变更、ORDER 清单与迁移回滚的完整闭环下一篇ASP.NET Core微服务架构基于框架构建分布式系统的最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考