仓颉（Cangjie）ohos.system_date_time 实战：获取系统时间、开机时间与系统时区

文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载本文基于 OpenHarmony 仓颉 API 参考中的ohos.system_date_time模块文档讲解如何在仓颉应用中使用SystemDateTime类获取 Unix 时间、系统开机时长Startup/Active两种语义与当前系统时区并覆盖模块导入方式、参数与返回值说明、异常处理与错误码排查以及系统能力SysCap适配检查的完整实战要点。模块定位BasicServicesKit 中的系统时间与时区能力ohos.system_date_time系统时间、时区模块是 OpenHarmony 仓颉 SDK 中Basic Services Kit基础服务的一部分该 Kit 在语料库中被标注为 Beta 特性其文档索引见 BasicServicesKit README。该模块主要由系统时间和系统时区两类功能组成开发者可以获取系统时间、系统开机时长以及系统时区。整个模块对外暴露的核心构成如下构件类型功能SystemDateTimeclass系统时间、时区功能类全部接口均为static funcTimeTypeenum定义获取时间的枚举类型取值Startup/Active模块与每个接口均标注了统一的元信息在选型和适配时需要留意系统能力SystemCapability.MiscServices.Time—— 只有设备支持该系统能力时接口才可用起始版本22 —— 从 API 起始版本 22 开始提供。SystemDateTime类声明如下public class SystemDateTime {}导入模块与示例代码约定使用模块能力前需要先导入 Kitimport kit.BasicServicesKit.*根据语料库中的 API 开发说明SDK 对同一个 Kit 下的接口模块进行了封装开发者可通过导入 Kit 的方式使用其包含的接口能力。关于 API 示例代码有两条使用约定需要遵守若示例代码首行有// index.cj注释表示该示例可在仓颉模板工程的index.cj文件中编译运行若示例需获取Context应用上下文参见 UIAbility 中的 Context则需在仓颉模板工程的main_ability.cj文件中配置。上述示例工程及配置模板详见 仓颉示例代码说明。本文涉及的所有示例均标注// index.cj即可直接粘贴进模板工程的index.cj文件运行。接口一static func getTime(Bool) 获取当前系统时间public static func getTime(isNanoseconds!: Bool false): Int64功能获取自 Unix 纪元1970-01-01 00:00:00 UTC以来到当前系统时间所经过的时间。系统能力SystemCapability.MiscServices.Time起始版本22参数说明参数名类型必填默认值说明isNanosecondsBool否false命名参数。返回结果是否为纳秒数。true返回结果为纳秒数nsfalse返回结果为毫秒数ms。默认值为false。返回值类型说明Int64自 Unix 纪元以来到当前系统时间所经过的时间。完整示例含Hilog日志输出与BusinessException异常捕获// index.cj import kit.BasicServicesKit.* import ohos.business_exception.BusinessException import kit.PerformanceAnalysisKit.Hilog try { let time SystemDateTime.getTime() Hilog.info(0, cangjie_ohos_test, Succeeded in getting time : ${time}) } catch (e: BusinessException) { Hilog.info(0, test, ${e.message}) }示例要点默认调用SystemDateTime.getTime()返回毫秒粒度的 Unix 时间戳需要更高精度时传入命名参数isNanoseconds: true获取纳秒粒度返回值类型Int64足以容纳纳秒级时间戳避免 32 位整型的溢出问题接口失败路径通过抛出BusinessException表达示例中统一捕获并打印e.message定位问题。接口二static func getTimezone() 获取系统时区public static func getTimezone(): String功能获取系统时区。系统能力SystemCapability.MiscServices.Time起始版本22返回值类型说明String返回系统时区具体取值范围见文档中支持的系统时区一节。示例// index.cj import kit.BasicServicesKit.* import ohos.business_exception.BusinessException import kit.PerformanceAnalysisKit.Hilog try { let time SystemDateTime.getTimezone() Hilog.info(0, cangjie_ohos_test, Succeeded to getTimezone, getTimezone is ${time} ) } catch (e: BusinessException) { Hilog.info(0, test, ${e.message}) }返回值为字符串形式的时区标识。如果需要面向用户展示本地化的时区名称例如不同语言环境下时区称呼不同可以结合 LocalizationKit 的能力进一步处理语料库中 本地化时区名称 一章给出了Calendar.getDisplayName等配套用法可与本接口组合使用先用getTimezone()拿到设备当前时区再按语言环境做展示转换。接口三static func getUptime(TimeType, Bool) 获取开机时长public static func getUptime(timeType: TimeType, isNanoseconds!: Bool false): Int64功能获取自系统启动以来经过的时间。系统能力SystemCapability.MiscServices.Time起始版本22参数说明参数名类型必填默认值说明timeTypeTimeType是-获取时间的类型仅能为Startup或者Active。isNanosecondsBool否false命名参数。返回结果是否为纳秒数。true返回结果为纳秒数nsfalse返回结果为毫秒数ms。默认值为false。返回值类型说明Int64自系统启动以来经过的时间。示例// index.cj import kit.BasicServicesKit.* import ohos.business_exception.BusinessException import kit.PerformanceAnalysisKit.Hilog try { let time SystemDateTime.getUptime(TimeType.Active) Hilog.info(0, cangjie_ohos_test, Succeeded to getUptime : ${time}) } catch (e: BusinessException) { Hilog.info(0, test, ${e.message}) }enum TimeTypeStartup 与 Active 的语义区别public enum TimeType { | Startup | Active | ... }功能定义获取时间的枚举类型。系统能力SystemCapability.MiscServices.Time起始版本22枚举项语义Startup自系统启动以来经过的毫秒数包括深度睡眠时间。Active自系统启动以来经过的毫秒数不包括深度睡眠时间。两者的关键差异在于是否计入深度睡眠期间Startup是设备开机后经过的总时长Active则是设备实际处于活动状态的累计时长。从接口语义看选择哪个枚举取决于业务意图——例如统计用户本次连续使用时长这类场景更接近Active的口径而记录设备开机以来发生了多少次事件这类场景更接近Startup的口径具体以实际业务需求为准。系统能力检查与跨设备适配文档为模块和每个接口都标注了系统能力SystemCapability.MiscServices.Time。语料库中的系统能力列表如 手机端系统能力列表显示该能力已列入手机设备的支持能力集平板设备系统能力列表 同样包含该能力。为了在运行期确认目标设备是否支持该能力可以使用canIUse接口进行判断用法参见 系统能力 SystemCapability 使用指南。以本模块为例可以在调用前做如下检查import ohos.base.canIUse if (canIUse(SystemCapability.MiscServices.Time)) { // 设备支持系统时间/时区能力可调用 SystemDateTime 各接口 } else { // 设备不支持走降级逻辑 }需要注意的是同一系统能力在不同设备下可能存在能力差异跨设备应用建议在运行期通过canIUse查询兜底。异常处理与错误码排查文档示例统一采用try / catch (e: BusinessException)的写法捕获业务异常这与仓颉 API 的异常处理模型一致。当SystemDateTime相关调用失败时可结合 时间时区服务错误码 进行排查错误码-1时间时区服务异常错误信息为 The parameter check failed or permission denied or system error.含义为参数校验失败、权限校验失败或者时间时区服务异常。可能原因与对应处理步骤参数校验失败传入参数无效 —— 检查参数是否按照要求传入权限校验失败权限未配置 —— 设置时间需配置ohos.permission.SET_TIME设置时区需配置ohos.permission.SET_TIME_ZONE注意本文涉及的三个接口均为读取操作文档中未标注需要权限权限要求主要出现在设置时间/时区的场景系统运行异常内存申请、多线程处理等内核通用错误—— 确认内存是否足够。小结ohos.system_date_time模块用一组静态接口提供了仓颉应用获取时间信息的完整能力面需求接口关键参数返回值获取当前 Unix 时间SystemDateTime.getTimeisNanoseconds可选默认false返回毫秒Int64获取系统时区SystemDateTime.getTimezone无String获取开机时长SystemDateTime.getUptimetimeType必填Startup/ActiveisNanoseconds可选Int64所有接口自版本 22 起提供依赖系统能力SystemCapability.MiscServices.Time调用前可通过canIUse做运行期检查失败路径统一抛出BusinessException可依据时间时区错误码-1的排查步骤定位参数、权限或系统级问题。示例代码均可放入仓颉模板工程的index.cj直接编译运行配合 开发说明 中的模板工程流程即可在真机或模拟器上完成验证。赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐如何快速获取系统时间与时区信息fastfetch实用指南如何快速获取系统时间与时区信息fastfetch实用指南 fastfetch是一款用C语言编写的系统信息工具以其极致的速度和丰富的功能超越同类工具。它不仅能CLI开发工具仓颉 std.time 包实战详解DateTimeFormat 时间格式与 TimeZone 时区 API仓颉 std.time 包实战详解DateTimeFormat 时间格式与 TimeZone 时区 API 本文围绕仓颉Cangjie标准库 std.ti编程语言语言运行时标准库垃圾回收并发编程Neofetch时间区间统计系统信息随时间变化的趋势分析方法Neofetch时间区间统计系统信息随时间变化的趋势分析方法 痛点与解决方案 系统管理员、开发者和运维人员经常需要监控服务器或个人设备的性能变化趋势但传统命CLI开发工具上一篇终极指南探索Linux系统上的顶级教育软件与学习工具集下一篇Apache NuttX深度解析微内核架构设计与实时性能优化实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考