NodeGui 中 NavigationMode 枚举完整参考:成员取值、定义位置与键盘导航模式语义
NodeGui 中 NavigationMode 枚举完整参考:成员取值、定义位置与键盘导航模式语义
NavigationMode 是 NodeGui 在 QtEnums 模块中导出的一组键盘导航模式枚举,用于描述控件(在 Qt 中主要服务于 QCalendarWidget 一类组件)在键入/方向键导航时的工作方式。本文基于 NodeGui 仓库自动生成的 API 参考页 website/docs/api/generated/enums/navigationmode.md 与仓库源码,完整列出其全部 5 个成员及数值、在源码中的定义与导出链路,并说明在当前仓库版本中该枚举的实际接入状态。
NavigationMode 枚举成员与取值
仓库 API 参考页中完整记录了该枚举的 5 个成员,取值连续且从 0 开始:
| 枚举成员 | 数值 |
|---|---|
NavigationModeNone |
0 |
NavigationModeKeypadTabOrder |
1 |
NavigationModeKeypadDirectional |
2 |
NavigationModeCursorAuto |
3 |
NavigationModeCursorForceVisible |
4 |
对应的 TypeScript 定义位于 src/lib/QtEnums/NavigationMode/index.ts:
export enum NavigationMode {
NavigationModeNone = 0,
NavigationModeKeypadTabOrder = 1,
NavigationModeKeypadDirectional = 2,
NavigationModeCursorAuto = 3,
NavigationModeCursorForceVisible = 4,
}
可以确认文档中记录的成员名与数值和源码定义完全一致,即自动生成文档与仓库当前实现是同步的。
各成员对应的导航语义
从枚举命名与取值看,该枚举对应 Qt 中 QCalendarWidget::NavigationMode 一类的导航模式定义,五个成员分别覆盖“关闭 / 按 Tab 顺序 / 方向键 / 自动光标 / 强制光标可见”五种行为:
- NavigationModeNone (0):关闭键盘导航模式,控件不响应导航键带来的焦点/选中项移动。
- NavigationModeKeypadTabOrder (1):键盘导航遵循控件的 Tab 顺序(tab order),按键在可聚焦项之间按既定顺序移动。
- NavigationModeKeypadDirectional (2):键盘导航采用方向键语义,按方向(上/下/左/右)在网格状或列表状结构中移动选中项,适合日历、表格等二维布局。
- NavigationModeCursorAuto (3):光标模式由系统自动决定,在需要文本编辑的场景下才会呈现光标行为。
- NavigationModeCursorForceVisible (4):强制光标可见,即使当前交互并不需要输入也保持光标显示。
其中 None 取值为 0 与 Qt 枚举“第一个成员为 0”的惯例一致;由于 NodeGui 通过 QVariant 以整数方式在 JS 与 C++ 之间传递枚举值,数值本身是跨语言契约的一部分,这也是为什么 TS 端显式写死数值而不依赖隐式自增。
在 NodeGui 源码中的导出与调用链
NavigationMode 通过 QtEnums 的桶文件统一导出,见 src/lib/QtEnums/index.ts:
export { NavigationMode } from './NavigationMode';
因此业务代码中可直接从 nodegui 的枚举入口按需引入。需要注意,NodeGui 的枚举通常以整数值经 QVariant 通道传给 C++ 侧,读取属性值时采用 this.property('xxx').toInt() 这类模式(可参考 src/lib/QtWidgets/QAbstractItemView.ts 中 defaultDropAction(): DropAction 的实现方式)。也就是说,当某个属性包装层暴露 navigationMode 读取/设置方法时,其底层实现就是按整数解析该枚举。
当前仓库版本中的接入状态
对源码结构进行搜索后可以确认:在当前仓库版本中,NavigationMode 仅出现在 src/lib/QtEnums/NavigationMode/index.ts 与 src/lib/QtEnums/index.ts 两处,尚未在 TS 包装层中被任何具体属性的 setProperty/property 调用引用;C++ 侧(src/cpp 目录)也没有出现 navigationMode 相关的绑定。
从源码结构看,与“导航”相关的既有封装是 QCalendarWidget 包装类中的导航条可见性属性,见 src/lib/QtWidgets/QCalendarWidget.ts:
setNavigationBarVisible(visible: boolean): void {
this.setProperty('navigationBarVisible', visible);
}
其底层 C++ 绑定位于 src/cpp/lib/QtWidgets/QCalendarWidget/qcalendarwidget_wrap.cpp。因此可以推断:NavigationMode 目前是仓库中“已定义并导出、等待具体属性包装接入”的 Qt 枚举之一——如果你在使用中需要设置日历控件的键盘导航模式,当前版本可能需要通过 Qt 属性机制以整数值方式传入,或关注后续版本对 navigationMode 属性的包装进度。
小结与相关文件
- 枚举成员与数值(5 个,0–4):与文档 website/docs/api/generated/enums/navigationmode.md 及源码 src/lib/QtEnums/NavigationMode/index.ts 一致,成员名与数值构成跨 JS/C++ 的稳定契约;
- 导出链路:经 src/lib/QtEnums/index.ts 统一对外导出;
- 相关组件封装:src/lib/QtWidgets/QCalendarWidget.ts 提供了导航条可见性的属性封装,是该枚举最接近的落点;
- 适用前提:本文结论基于当前仓库快照,枚举的数值定义与导出关系可直接作为事实引用,而“属性包装尚未接入”属于对当前源码结构的观察,后续版本可能新增
navigationMode的属性包装方法。