桌面应用跨平台【免费下载链接】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 仓库中自动生成的 QDateTime 类参考文档website/docs/api/generated/classes/qdatetime.md系统梳理该类在 NodeGui 中的完整 API 面——构造函数、27 个实例方法与 6 个静态方法的签名、参数与返回值并结合仓库中 TypeScript 封装层 与 N-API 原生封装实现 的源码深入讲解其构造分发、可变与不可变方法的区分、时区/格式枚举以及跨层数据传递机制。读完本文你不仅能直接使用 QDateTime 完成时间计算、解析与格式化还能理解每个方法在 JS 层与 C 层之间的完整调用链。类定位与继承关系QDateTime 是 NodeGui 对 Qt 同名类的绑定属于 QtCore 模块在仓库中由以下文件共同构成层次文件职责TypeScript 封装src/lib/QtCore/QDateTime.ts对外暴露的QDateTime类参数校验与包装N-API 绑定实现src/cpp/lib/QtCore/QDateTime/qdatetime_wrap.cpp将QDateTimeC 对象方法注册为 JS 可调用方法N-API 绑定声明src/cpp/include/nodegui/QtCore/QDateTime/qdatetime_wrap.hQDateTimeWrap类与方法声明API 参考文档website/docs/api/generated/classes/qdatetime.md本文所依据的生成式 API 文档从参考文档的 Hierarchy 一节和 TS 源码可以确认QDateTime继承自 Component 基类并对外暴露一个继承来的native属性类型为 NativeElement | null用于持有底层 C 对象。类通过 src/index.ts 中的export { QDateTime } from ./lib/QtCore/QDateTime从包入口导出。在 C 侧QDateTimeWrap继承Napi::ObjectWrapQDateTimeWrap以std::unique_ptrQDateTime持有内部 Qt 实例见 qdatetime_wrap.h并在构造时调用extrautils::configureComponent配置组件元数据。当 JS 侧包装对象被垃圾回收时析构函数释放该QDateTime实例即内存生命周期由 JS GC 管理。构造 QDateTime参考文档给出的构造函数签名为new QDateTime(arg?: NativeElement, time?: NativeElement): QDateTimeTypeScript 实现 实际上支持三种调用形态按以下优先级分发两参数arg与time同时存在native new addon.QDateTime(arg.native, time.native)即用一对日期与时间的原生对象构造。传入的通常是 QDate 与 QTime 实例它们各自携带native属性单参数且为 NativeElement通过checkIfNativeElement判断直接复用传入的原生对象不做转换其他情况无参数或参数不合法new addon.QDateTime()构造一个默认的空QDateTime。C 侧构造函数qdatetime_wrap.cpp对参数个数有更严格的校验这一行为值得注意if (info.Length() 2) { Napi::Object dateObject info[0].AsNapi::Object(); Napi::Object timeObject info[1].AsNapi::Object(); QDateWrap* dateWrap Napi::ObjectWrapQDateWrap::Unwrap(dateObject); QTimeWrap* timeWrap Napi::ObjectWrapQTimeWrap::Unwrap(timeObject); this-instance std::make_uniqueQDateTime( *dateWrap-getInternalInstance(), *timeWrap-getInternalInstance()); } else if (info.Length() 1) { this-instance std::unique_ptrQDateTime( info[0].AsNapi::ExternalQDateTime().Data()); } else if (info.Length() 0) { this-instance std::make_uniqueQDateTime(); } else { Napi::TypeError::New(env, Wrong number of arguments) .ThrowAsJavaScriptException(); }即两参数时从两个包装对象中解出内部QDate/QTime实例构造单参数时从Napi::ExternalQDateTime指针接管已有实例0 参数默认构造其余情况抛出TypeError: Wrong number of arguments。这也意味着new QDateTime()得到的是一个无效的QDateTimeQt 中空构造的对象isValid()为false、isNull()为true使用时应先用状态查询方法确认有效性。基础用法示例const { QDate, QTime, QDateTime, TimeSpec, DateFormat } require(nodegui); // 1. 用当前时间 const now QDateTime.currentDateTime(); // 2. 由 QDate QTime 组合构造对应两参数构造路径 const date new QDate(2024, 1, 15); // QDate(year, month, day) const time new QTime(10, 30, 0, 0); // QTime(hour, minute, second, msec) const dt new QDateTime(date, time); // 3. 解析字符串 const parsed QDateTime.fromString(2024-01-15 10:30:00, yyyy-MM-dd hh:mm:ss); // 4. 默认构造 —— 注意此时对象无效isNull() 为 true const empty new QDateTime(); console.log(empty.isValid(), empty.isNull());实例方法总览参考文档的 Methods 一节完整列出了 27 个实例方法与 6 个静态方法。为避免信息缺失下表先给出全部实例方法签名与文档一一对应后续小节再按功能分组展开。方法参数返回值addDaysndays: numberQDateTimeaddMSecsmsecs: numberQDateTimeaddMonthsnmonths: numberQDateTimeaddSecss: numberQDateTimeaddYearsnyears: numberQDateTimedate—QDatedaysToother:QDateTimenumberisDaylightTime—booleanisNull—booleanisValid—booleanmsecsToother:QDateTimenumberoffsetFromUtc—numbersecsToother:QDateTimenumbersetDatedate: QDatevoidsetMSecsSinceEpochmsecs: numbervoidsetOffsetFromUtcoffsetSeconds: numbervoidsetSecsSinceEpochsecs: numbervoidsetTimetime: QTimevoidsetTimeSpecspec: TimeSpecvoidtime—QTimetimeSpec—TimeSpectoLocalTime—QDateTimetoMSecsSinceEpoch—numbertoOffsetFromUtcoffsetSeconds: numberQDateTimetoSecsSinceEpoch—numbertoStringformat: string | DateFormatstringtoTimeSpecspec: TimeSpecQDateTimetoUTC—QDateTime时间加减运算add* 系列返回新对象addDays(ndays)、addMSecs(msecs)、addMonths(nmonths)、addSecs(s)、addYears(nyears)五个方法都返回一个新的QDateTime不修改原对象。从 C 实现可以印证这一点qdatetime_wrap.cppNapi::Value QDateTimeWrap::addDays(const Napi::CallbackInfo info) { Napi::Env env info.Env(); qint64 ndays info[0].AsNapi::Number().Int64Value(); QDateTime result this-instance-addDays(ndays); auto instance QDateTimeWrap::constructor.New( {Napi::ExternalQDateTime::New(env, new QDateTime(result))}); return instance; }模式是固定的取出结果后new QDateTime(result)堆分配一份拷贝再经Napi::ExternalQDateTime传回 JS 新建一个包装对象。TS 层则统一写作return new QDateTime(this.native.addDays(ndays))见 src/lib/QtCore/QDateTime.ts。参数精度上有一个源码级细节addDays/addMSecs/addSecs在 C 侧按Int64Value()取 64 位整数qint64而addMonths/addYears按Int32Value()取 32 位整数与 Qt 原生 API 的签名一致。const deadline parsed.addDays(7).addMonths(1).addSecs(3600);比较与差值daysTo / msecsTo / secsTo三个差值方法都接收另一个QDateTime返回number可能为负。C 侧通过Napi::ObjectWrapQDateTimeWrap::Unwrap(otherObject)从传入的 JS 对象解包出内部指针后调用this-instance-daysTo(...)等方法qdatetime_wrap.cpp。因此参数必须也是本封装的QDateTime实例传入普通 JS 对象会导致解包失败。const daysBetween now.daysTo(deadline); // 相差的天数 const msBetween now.msecsTo(deadline); // 相差的毫秒数状态与分量查询date()返回 QDate。注意 C 实现并非直接透传指针而是重建new QDate(date.year(), date.month(), date.day())qdatetime_wrap.cpptime()同理返回由hour/minute/second/msec重建的 QTimeisValid()/isNull()有效性判定的首选手段尤其是经过默认构造或解析失败后isDaylightTime()当前时间点是否处于夏令时offsetFromUtc()距 UTC 的偏移秒timeSpec()返回 TimeSpec 枚举值。原地修改set* 系列与 add* 系列相反set前缀方法原地修改当前对象并返回nullC 侧return env.Null()setDate(date)/setTime(time)分别替换日期部分与时间部分参数必须是QDate/QTime包装对象C 侧同样通过Unwrap取出内部实例setSecsSinceEpoch(secs)/setMSecsSinceEpoch(msecs)以距 Unix 纪元1970-01-01T00:00:00 UTC的秒数/毫秒数整体设定时间值均为 64 位整数入参。这是构造精确时间点的常用技巧setTimeSpec(spec)修改时间的规格类型本地时间/UTC 等入参为 TimeSpec 数值C 侧static_castQt::TimeSpec(spec)转换setOffsetFromUtc(offsetSeconds)仅对OffsetFromUTC规格生效设置与 UTC 的偏移秒数32 位整数。const t new QDateTime(); t.setMSecsSinceEpoch(QDateTime.currentMSecsSinceEpoch()); // 以纪元毫秒填充当前时间转换与格式化toUTC()/toLocalTime()/toTimeSpec(spec)/toOffsetFromUtc(offsetSeconds)均返回新的QDateTimeadd* 系列同款“拷贝 External 回传”模式原对象不变。四个方法与 TimeSpec 共同覆盖 Qt 的时间规格转换路径toSecsSinceEpoch()/toMSecsSinceEpoch()读出距 Unix 纪元的秒/毫秒数64 位与上文setSecsSinceEpoch/setMSecsSinceEpoch构成读写对toString(format)按格式输出字符串format接受解析格式字符串如yyyy-MM-dd hh:mm:ss或 DateFormat 枚举。toString有一个值得留意的命名细节原生绑定中该方法被注册为toString$见 qdatetime_wrap.cpp 中的InstanceMethod(toString$, ...)TS 层toString内部调用this.native.toString$(format)src/lib/QtCore/QDateTime.ts。加$后缀是为了避免与 JS 对象原型链上已有的Object.prototype.toString冲突——这是 NodeGui 全部带toString的封装类的统一做法如QDate、QTime。C 侧对format做了类型分发字符串走QDateTime::toString(QString)数值走static_castQt::DateFormatqdatetime_wrap.cpp。静态方法参考文档的 Static 一节列出 6 个静态方法TS 侧全部委托给addon.QDateTime上的同名静态方法静态方法签名说明currentDateTime(): QDateTime当前本地时间currentDateTimeUtc(): QDateTime当前 UTC 时间currentMSecsSinceEpoch(): number当前时间的纪元毫秒数currentSecsSinceEpoch(): number当前时间的纪元秒数fromString(dateTimeString: string, format: string \| DateFormat): QDateTime按格式解析字符串fromQVariant(variant: [QVariant](https://link.gitcode.com/i/6808c31f67b3434d8cc8b5b44e84f7e1)): QDateTime从 QVariant 提取 QDateTimefromString的 C 实现qdatetime_wrap.cpp与toString一样按参数类型分发format为字符串时走QDateTime::fromString(QString, QString)解析格式为数值时走QDateTime::fromString(QString, Qt::DateFormat)预设格式。解析失败时 Qt 返回空QDateTime即得到的对象isValid()为false调用方应自行检查。fromQVariant通过解包传入的 QVariant 包装对象并执行variant-valueQDateTime()完成提取qdatetime_wrap.cpp适用于 QVariant 中携带 datetime 数据的场景。TimeSpec 与 DateFormat 枚举两个被setTimeSpec/toTimeSpec/timeSpec及toString/fromString引用的枚举其数值定义直接来自仓库源码TimeSpecsrc/lib/QtEnums/TimeSpec/index.ts成员值LocalTime0UTC1OffsetFromUTC2TimeZone3DateFormatsrc/lib/QtEnums/DateFormat/index.ts成员值TextDate0ISODate1SystemLocaleDate2LocaleDate3SystemLocaleShortDate4SystemLocaleLongDate5DefaultLocaleShortDate6DefaultLocaleLongDate7RFC2822Date8ISODateWithMs9在 C 绑定层这些枚举就是普通 32 位整数info[0].AsNapi::Number().Int32Value()static_cast因此也可以不导入枚举直接传对应数值但推荐导入枚举以保证可读性与 Qt 版本间数值稳定。const { QDateTime, DateFormat, TimeSpec } require(nodegui); const now QDateTime.currentDateTime(); console.log(now.toString(DateFormat.ISODate)); // ISO 8601 形式 console.log(now.toUTC().toString(DateFormat.ISODateWithMs)); // 先转 UTC 再带毫秒输出 now.setTimeSpec(TimeSpec.UTC); // 原地修改规格原生层实现要点小结结合 qdatetime_wrap.cpp 与 QDateTime.tsQDateTime 封装的跨层机制可以归纳为以下几点注册QDateTimeWrap::init用DefineClass一次性注册全部实例方法InstanceMethod与 6 个静态方法StaticMethod并挂接COMPONENT_WRAPPED_METHODS_EXPORT_DEFINE宏提供组件通用能力对象传递返回QDateTime/QDate/QTime的方法统一采用“堆分配拷贝 →Napi::ExternalT::New包装 → 类构造器constructor.New生成新 JS 对象”的链路每个 JS 对象独立持有一份 C 实例入参解包接收其他封装类的方法统一用Napi::ObjectWrapTWrap::Unwrap取内部实例因此参数必须是 NodeGui 的对应类型实例枚举即整数TimeSpec/DateFormat在边界处是 intC 侧负责static_cast回 Qt 枚举命名规避冲突与 JS 原型方法重名的绑定统一加$后缀如toString$TS 层再以正常名称重新导出参数个数严格校验构造函数 0/1/2 参数各有语义其他个数直接抛TypeError。参考文档与源码索引API 参考文档本文主体依据website/docs/api/generated/classes/qdatetime.mdTypeScript 封装src/lib/QtCore/QDateTime.tsN-API 实现src/cpp/lib/QtCore/QDateTime/qdatetime_wrap.cppN-API 声明src/cpp/include/nodegui/QtCore/QDateTime/qdatetime_wrap.h关联类型QDate、QTime、QVariant、Component枚举定义src/lib/QtEnums/TimeSpec/index.ts、src/lib/QtEnums/DateFormat/index.ts需要说明的是该 API 参考文档位于generated目录由工具从 TS 源码自动生成因此方法清单、参数名与 src/lib/QtCore/QDateTime.ts 的 TS 签名严格一致而参数精度32 位/64 位整数、解包方式等细节则需以 C 实现为准本文已在相应小节中标注了具体行号。赞分享桌面应用跨平台【免费下载链接】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点击查看免费下载相关推荐为 AirSim 添加新 API从实现、RPC 封装到测试的完整指南为 AirSim 添加新 API从实现、RPC 封装到测试的完整指南 导读 AirSim 提供覆盖多旋翼、汽车、仿真环境与物理引擎的上百个 RPC API自动驾驶人工智能深度学习强化学习计算机视觉科研如何快速找回比特币钱包密码面向新手的完整恢复指南如何快速找回比特币钱包密码面向新手的完整恢复指南 你是否还记得大部分比特币钱包密码或助记词却因为一些拼写错误或记忆偏差而无法访问你的数字资产btcreco桌面应用跨平台Advanced-Deep-Learning-with-Keras项目架构模块化设计与扩展性分析Advanced Deep Learning with Keras项目架构模块化设计与扩展性分析 Advanced Deep Learning with Ke桌面应用跨平台上一篇Awesome Python图神经网络图数据与关系学习的深度学习下一篇5分钟上手Ghost-Downloader-3新一代智能下载器完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考