仓颉（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。该模块主要由系统时间和系统时区两类功能组成：开发者可以获取系统时间、系统开机时长以及系统时区。

整个模块对外暴露的核心构成如下：

构件	类型	功能
`SystemDateTime`	class	系统时间、时区功能类，全部接口均为`static func`
`TimeType`	enum	定义获取时间的枚举类型，取值`Startup`/`Active`

模块与每个接口均标注了统一的元信息，在选型和适配时需要留意：

系统能力：SystemCapability.MiscServices.Time—— 只有设备支持该系统能力时接口才可用；
起始版本：22 —— 从 API 起始版本 22 开始提供。

SystemDateTime类声明如下：

public class SystemDateTime {}

导入模块与示例代码约定

使用模块能力前需要先导入 Kit：

import 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

参数说明：

参数名	类型	必填	默认值	说明
`isNanoseconds`	`Bool`	否	`false`	命名参数。返回结果是否为纳秒数。`true`：返回结果为纳秒数（ns）；`false`：返回结果为毫秒数（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

参数说明：

参数名	类型	必填	默认值	说明
`timeType`	TimeType	是	-	获取时间的类型，仅能为`Startup`或者`Active`。
`isNanoseconds`	`Bool`	否	`false`	命名参数。返回结果是否为纳秒数。`true`：返回结果为纳秒数（ns）；`false`：返回结果为毫秒数（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 TimeType：Startup 与 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.getTime`	`isNanoseconds`（可选，默认`false`返回毫秒）	`Int64`
获取系统时区	`SystemDateTime.getTimezone`	无	`String`
获取开机时长	`SystemDateTime.getUptime`	`timeType`（必填，`Startup`/`Active`）；`isNanoseconds`（可选）	`Int64`

所有接口自版本 22 起提供，依赖系统能力SystemCapability.MiscServices.Time，调用前可通过canIUse做运行期检查；失败路径统一抛出BusinessException，可依据时间时区错误码-1的排查步骤定位参数、权限或系统级问题。示例代码均可放入仓颉模板工程的index.cj直接编译运行，配合开发说明中的模板工程流程即可在真机或模拟器上完成验证。