NodeGui CorrectionMode 枚举详解：QAbstractSpinBox 数值纠正策略与 setCorrectionMode 实践

• 桌面应用
• 跨平台

导读

CorrectionMode是 NodeGui 中与 QtQAbstractSpinBox数值输入控件（QSpinBox、QDoubleSpinBox、QDateTimeEdit 等）配套的枚举类型，用于定义当用户输入非法数值时，控件应当以何种策略将其"纠正"到合法区间。本文基于仓库中的 API 文档（correctionmode.md）与 TypeScript 封装源码，系统讲解该枚举的两个成员、底层属性绑定机制，以及在实际控件上的使用方法。读完本文，你将能够在 NodeGui 应用中精确控制旋转框（SpinBox）的输入校正行为，写出输入容错更友好的表单界面。

CorrectionMode 是什么：对应 Qt 的输入校正机制

在 Qt 的QAbstractSpinBox体系中，旋转框不仅允许通过上下箭头步进调整数值，也允许用户直接键入文本。当键入的文本无法被解析为合法值（例如超出minimum/maximum范围、非法字符等）时，控件需要执行一次"校正（correction）"。NodeGui 的CorrectionMode枚举正是为该场景提供可选的两种校正策略，其名称、含义与 Qt 原生枚举QAbstractSpinBox::CorrectionMode一一对应。

NodeGui 官方 API 文档为CorrectionMode收录了如下两个枚举成员：

其中数值0、1的取值可以从 TypeScript 枚举定义的声明顺序推断（见下文源码），与 Qt 原生枚举的声明顺序保持一致。

枚举成员的源码级定义

在仓库中，CorrectionMode的真实定义位于 TypeScript 层的QAbstractSpinBox封装文件 src/lib/QtWidgets/QAbstractSpinBox.ts：

export enum CorrectionMode { CorrectToPreviousValue, CorrectToNearestValue, }

该文件还同时声明了ButtonSymbols（按钮符号）与StepType（步进类型）两个配套枚举，三者共同构成QAbstractSpinBox的常用属性取值集合。

从源码结构看，CorrectionMode属于 NodeGui 对外公开的 API：它被统一汇集导出在包入口 src/index.ts 中，因此使用方可以直接通过以下方式引入：

import { QSpinBox, CorrectionMode } from '@nodegui/nodegui';

此外，API 文档生成目录 website/docs/api/generated/enums/correctionmode.md 以结构化形式记录了这两个成员，供开发者在查阅控件文档时交叉引用。

谁在使用 CorrectionMode：继承体系与适用范围

CorrectionMode的消费方是抽象基类QAbstractSpinBox。在 QAbstractSpinBox.ts 中，NodeGui 为该枚举提供了配套的读写方法：

setCorrectionMode(cm: CorrectionMode): void { this.setProperty('correctionMode', cm); } correctionMode(): CorrectionMode { return this.property('correctionMode').toInt(); }

可以看到，NodeGui 通过统一的"属性（property）"机制将correctionMode传递给底层原生控件：写入时使用setProperty('correctionMode', cm)，读取时使用property('correctionMode').toInt()并将结果按整数映射回枚举。这意味着校正模式的设置本质上是 Qt 原生属性的一次透传，行为与原生QAbstractSpinBox::setCorrectionMode()一致。

从生成文档 qabstractspinbox.md、qspinbox.md 以及 qdoublespinbox.md、qdatetimeedit.md、qtimeedit.md、qdateedit.md 中引用CorrectionMode的情况来看，凡是继承自QAbstractSpinBox的具体控件均继承了setCorrectionMode/correctionMode两个方法，可统一配置校正策略。以 QSpinBox.ts 为例，其类声明为：

export class QSpinBox extends QAbstractSpinBox<QSpinBoxSignals> { ... }

因此，CorrectionMode的实际适用范围覆盖了 NodeGui 中所有基于QAbstractSpinBox的数字/日期时间输入控件。

两个成员的行为差异与选型建议

CorrectToPreviousValue（按步进逐级回退）

CorrectToPreviousValue对应 Qt 语义中的"以单步方式校正"：当用户键入的值非法时，控件会像反复按下箭头键那样，以singleStep为步长逐级回退，直到得到一个合法值。这种策略适合对输入做渐进式修正、希望结果贴近用户原始键入意图的数值场景。

CorrectToNearestValue（就近取合法值）

CorrectToNearestValue对应 Qt 语义中的"校正到最近合法值"：控件会直接找到与非法输入距离最近的合法值并采用。这种策略收敛速度更快，适合区间范围明确、用户输入偏差不大的场景（例如误将50键入为500而最大值仅为100时，直接落回100）。

选型建议

• 若希望用户手误输入后得到"最接近其本意"的结果，优先考虑CorrectToNearestValue；
• 若希望行为与步进式微调保持一致、结果总是落在步长网格上，选择CorrectToPreviousValue；
• 需要说明的是，校正模式只作用于用户直接编辑文本时的容错路径；通过setValue()等编程方式设置数值不受校正策略影响。

完整可运行示例

下面给出一个在 NodeGui 中使用QSpinBox并配置CorrectionMode.CorrectToNearestValue的最小示例（可运行于 NodeGui 项目的入口脚本）：

import { QSpinBox, CorrectionMode, QMainWindow, FlexLayout } from '@nodegui/nodegui'; const win = new QMainWindow(); win.setWindowTitle('CorrectionMode 示例'); win.resize(320, 120); const central = new QWidget(); const layout = new FlexLayout(); central.setLayout(layout); const spinBox = new QSpinBox(); spinBox.setMinimum(0); spinBox.setMaximum(100); spinBox.setSingleStep(5); // 关键：将输入校正策略设置为“纠正到最近的合法值” spinBox.setCorrectionMode(CorrectionMode.CorrectToNearestValue); // 读取当前策略（返回 CorrectionMode 枚举值） const mode = spinBox.correctionMode(); console.log('当前校正模式:', mode === CorrectionMode.CorrectToNearestValue ? 'CorrectToNearestValue' : 'CorrectToPreviousValue'); layout.addWidget(spinBox); central.show(); win.show();

运行前请确保已按仓库 README.md 完成 NodeGui 的安装与构建。上述示例中的setCorrectionMode调用会经由setProperty透传到原生 Qt 控件，因此运行环境需要具备可用的 Qt 运行时。

更多参考资料

• 枚举 API 文档：website/docs/api/generated/enums/correctionmode.md
• 枚举定义源码：src/lib/QtWidgets/QAbstractSpinBox.ts
• 读写方法实现：src/lib/QtWidgets/QAbstractSpinBox.ts
• 包导出入口：src/index.ts
• 继承类文档：qabstractspinbox.md、qspinbox.md、qdoublespinbox.md、qdatetimeedit.md

• 桌面应用
• 跨平台