@ohos.systemTime (系统时间、时区)

本模块主要由系统时间和系统时区功能组成。开发者可以设置、获取系统时间及系统时区。

说明：

从API version 9 开始，该模块接口不再维护，推荐使用新模块接口@ohos.systemDateTime (系统时间、时区)

本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import systemTime from '@ohos.systemTime';

systemTime.setTime

setTime(time : number, callback : AsyncCallback<void>) : void

设置系统时间，使用callback异步回调。

需要权限： ohos.permission.SET_TIME

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
time	number	是	目标时间戳（ms）。
callback	AsyncCallback<void>	是	回调函数。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or permission denied or system error.

示例：

// time对应的时间为2021-01-20 02:36:25
let time = 1611081385000;
try {
  systemTime.setTime(time, (error) => {
    if (error) {
      console.info(`Failed to setting time. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in setting time`);
  });
} catch(e) {
  console.info(`Failed to set time. message: ${e.message}, code: ${e.code}`);
}

systemTime.setTime

setTime(time : number) : Promise<void>

设置系统时间，使用Promise异步回调。

需要权限： ohos.permission.SET_TIME

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
time	number	是	目标时间戳（ms）。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or permission denied or system error.

示例：

// time对应的时间为2021-01-20 02:36:25
let time = 1611081385000;
try {
  systemTime.setTime(time).then(() => {
    console.info(`Succeeded in setting time.`);
  }).catch((error) => {
    console.info(`Failed to setting time. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to set time. message: ${e.message}, code: ${e.code}`);
}

systemTime.getCurrentTime⁸⁺

getCurrentTime(isNano: boolean, callback: AsyncCallback<number>): void

获取自Unix纪元以来经过的时间，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
isNano	boolean	是	返回结果是否为纳秒数。 - true：表示返回结果为纳秒数（ns）。 - false：表示返回结果为毫秒数（ms）。
callback	AsyncCallback<number>	是	回调函数，返回自Unix纪元以来经过的时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getCurrentTime(true, (error, time) => {
    if (error) {
      console.info(`Failed to getting currentTime. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in getting currentTime: ${time}`);
  });
} catch(e) {
  console.info(`Failed to get currentTime. message: ${e.message}, code: ${e.code}`);
}

systemTime.getCurrentTime⁸⁺

getCurrentTime(callback: AsyncCallback<number>): void

获取自Unix纪元以来经过的时间，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
callback	AsyncCallback<number>	是	回调函数，返回自Unix纪元以来经过的时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getCurrentTime((error, time) => {
    if (error) {
      console.info(`Failed to getting currentTime. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in getting currentTime : ${time}`);
  });
} catch(e) {
  console.info(`Failed to get currentTime. message: ${e.message}, code: ${e.code}`);
}

systemTime.getCurrentTime⁸⁺

getCurrentTime(isNano?: boolean): Promise<number>

获取自Unix纪元以来经过的时间，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
isNano	boolean	否	返回结果是否为纳秒数。 - true：表示返回结果为纳秒数（ns）。 - false：表示返回结果为毫秒数（ms）。

返回值：

类型	说明
Promise<number>	Promise对象，返回自Unix纪元以来经过的时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getCurrentTime().then((time) => {
    console.info(`Succeeded in getting currentTime : ${time}`);
  }).catch((error) => {
    console.info(`Failed to getting currentTime. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to get currentTime. message: ${e.message}, code: ${e.code}`);
}

systemTime.getRealActiveTime⁸⁺

getRealActiveTime(isNano: boolean, callback: AsyncCallback<number>): void

获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
isNano	boolean	是	返回结果是否为纳秒数。 - true：表示返回结果为纳秒数（ns）。 - false：表示返回结果为毫秒数（ms）。
callback	AsyncCallback<number>	是	回调函数，返回自系统启动以来经过的时间，但不包括度睡眠时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getRealActiveTime(true, (error, time) => {
    if (error) {
      console.info(`Failed to getting real active time. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in getting real active time : ${time}`);
  });
} catch(e) {
  console.info(`Failed to get real active time. message: ${e.message}, code: ${e.code}`);
}

systemTime.getRealActiveTime⁸⁺

getRealActiveTime(callback: AsyncCallback<number>): void

获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
callback	AsyncCallback<number>	是	回调函数，返回自系统启动以来经过的时间，但不包括度睡眠时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getRealActiveTime((error, time) => {
    if (error) {
      console.info(`Failed to getting real active time. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in getting real active time : ${time}`);
  });
} catch(e) {
  console.info(`Failed to get real active time. message: ${e.message}, code: ${e.code}`);
}

systemTime.getRealActiveTime⁸⁺

getRealActiveTime(isNano?: boolean): Promise<number>

获取自系统启动以来经过的时间，不包括深度睡眠时间，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
isNano	boolean	否	返回结果是否为纳秒数。 - true：表示返回结果为纳秒数（ns）。 - false：表示返回结果为毫秒数（ms）。

返回值：

类型	说明
Promise<number>	Promise对象，返回自系统启动以来经过的时间，但不包括深度睡眠时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getRealActiveTime().then((time) => {
    console.info(`Succeeded in getting real active time : ${time}`);
  }).catch((error) => {
    console.info(`Failed to getting real active time. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to get real active time. message: ${e.message}, code: ${e.code}`);
}

systemTime.getRealTime⁸⁺

getRealTime(isNano: boolean, callback: AsyncCallback<number>): void

获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
isNano	boolean	是	返回结果是否为纳秒数。 - true：表示返回结果为纳秒数（ns）。 - false：表示返回结果为毫秒数（ms）。
callback	AsyncCallback<number>	是	回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getRealTime(true, (error, time) => {
    if (error) {
      console.info(`Failed to getting real time. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in getting real time : ${time}`);
  });
} catch(e) {
  console.info(`Failed to get real time. message: ${e.message}, code: ${e.code}`);
}

systemTime.getRealTime⁸⁺

getRealTime(callback: AsyncCallback<number>): void

获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
callback	AsyncCallback<number>	是	回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getRealTime((error, time) => {
    if (error) {
      console.info(`Failed to getting real time. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in getting real time : ${time}`);
  });
} catch(e) {
  console.info(`Failed to get real time. message: ${e.message}, code: ${e.code}`);
}

systemTime.getRealTime⁸⁺

getRealTime(isNano?: boolean): Promise<number>

获取自系统启动以来经过的时间，包括深度睡眠时间，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
isNano	boolean	否	返回结果是否为纳秒数。 - true：表示返回结果为纳秒数（ns）。 - false：表示返回结果为毫秒数（ms）。

返回值：

类型	说明
Promise<number>	Promise对象，返回自系统启动以来经过的时间，包括深度睡眠时间。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getRealTime().then((time) => {
    console.info(`Succeeded in getting real time : ${time}`);
  }).catch((error) => {
    console.info(`Failed to getting real time. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to get real time. message: ${e.message}, code: ${e.code}`);
}

systemTime.setDate

setDate(date: Date, callback: AsyncCallback<void>): void

设置系统日期，使用callback异步回调。

需要权限： ohos.permission.SET_TIME

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
date	Date	是	目标日期。
callback	AsyncCallback<void>	是	回调函数。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or permission denied or system error.

示例：

let date = new Date();
try {
  systemTime.setDate(date, (error) => {
    if (error) {
      console.info(`Failed to setting date. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in setting date.`);
  });
} catch(e) {
  console.info(`Failed to set date. message: ${e.message}, code: ${e.code}`);
}

systemTime.setDate

setDate(date: Date): Promise<void>

设置系统日期，使用Promise异步回调。

需要权限： ohos.permission.SET_TIME

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
date	Date	是	目标日期。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or permission denied or system error.

示例：

let date = new Date(); 
try {
  systemTime.setDate(date).then(() => {
    console.info(`Succeeded in setting date.`);
  }).catch((error) => {
    console.info(`Failed to setting date. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to set date. message: ${e.message}, code: ${e.code}`);
}

systemTime.getDate⁸⁺

getDate(callback: AsyncCallback<Date>): void

获取当前系统日期，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Date>	是	回调函数，返回当前系统日期。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getDate((error, date) => {
    if (error) {
      console.info(`Failed to get date. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in get date : ${date}`);;
  });
} catch(e) {
  console.info(`Failed to get date. message: ${e.message}, code: ${e.code}`);
}

systemTime.getDate⁸⁺

getDate(): Promise<Date>

获取当前系统日期，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Time

返回值：

类型	说明
Promise<Date>	Promise对象，返回当前系统日期。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getDate().then((date) => {
    console.info(`Succeeded in getting date : ${date}`);
  }).catch((error) => {
    console.info(`Failed to getting date. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to get date. message: ${e.message}, code: ${e.code}`);
}

systemTime.setTimezone

setTimezone(timezone: string, callback: AsyncCallback<void>): void

设置系统时区，使用callback异步回调。

需要权限： ohos.permission.SET_TIME_ZONE

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
timezone	string	是	系统时区。具体可见支持的系统时区。
callback	AsyncCallback<void>	是	回调函数。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or permission denied or system error.

示例：

try {
  systemTime.setTimezone('Asia/Shanghai', (error) => {
    if (error) {
      console.info(`Failed to setting timezone. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in setting timezone.`);
  });
} catch(e) {
  console.info(`Failed to set timezone. message: ${e.message}, code: ${e.code}`);
}

systemTime.setTimezone

setTimezone(timezone: string): Promise<void>

设置系统时区，使用Promise异步回调。

需要权限： ohos.permission.SET_TIME_ZONE

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
timezone	string	是	系统时区。具体可见支持的系统时区。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or permission denied or system error.

示例：

try {
  systemTime.setTimezone('Asia/Shanghai').then(() => {
    console.info(`Succeeded in setting timezone.`);
  }).catch((error) => {
    console.info(`Failed to setting timezone. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to set timezone. message: ${e.message}, code: ${e.code}`);
}

systemTime.getTimezone⁸⁺

getTimezone(callback: AsyncCallback<string>): void

获取系统时区，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Time

参数：

参数名	类型	必填	说明
callback	AsyncCallback<string>	是	回调函数，返回系统时区。具体可见支持的系统时区。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getTimezone((error, data) => {
    if (error) {
      console.info(`Failed to get timezone. message: ${error.message}, code: ${error.code}`);
      return;
    }
    console.info(`Succeeded in get timezone : ${data}`);
  });
} catch(e) {
  console.info(`Failed to get timezone. message: ${e.message}, code: ${e.code}`);
}

systemTime.getTimezone⁸⁺

getTimezone(): Promise<string>

获取系统时区，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Time

返回值：

类型	说明
Promise<string>	Promise对象，返回系统时区。具体可见支持的系统时区。

错误码：

以下错误码的详细介绍请参见时间时区错误码。

错误码ID	错误信息
-1	The parameter check failed or system error.

示例：

try {
  systemTime.getTimezone().then((data) => {
    console.info(`Succeeded in getting timezone: ${data}`);
  }).catch((error) => {
    console.info(`Failed to getting timezone. message: ${error.message}, code: ${error.code}`);
  });
} catch(e) {
  console.info(`Failed to get timezone. message: ${e.message}, code: ${e.code}`);
}

支持的系统时区

支持的系统时区及各时区与0时区相比的偏移量（单位：h）可见下表。

时区	偏移量
Antarctica/McMurdo	12
America/Argentina/Buenos_Aires	-3
Australia/Sydney	10
America/Noronha	-2
America/St_Johns	-3
Africa/Kinshasa	1
America/Santiago	-3
Asia/Shanghai	8
Asia/Nicosia	3
Europe/Berlin	2
America/Guayaquil	-5
Europe/Madrid	2
Pacific/Pohnpei	11
America/Godthab	-2
Asia/Jakarta	7
Pacific/Tarawa	12
Asia/Almaty	6
Pacific/Majuro	12
Asia/Ulaanbaatar	8
America/Mexico_City	-5
Asia/Kuala_Lumpur	8
Pacific/Auckland	12
Pacific/Tahiti	-10
Pacific/Port_Moresby	10
Asia/Gaza	3
Europe/Lisbon	1
Europe/Moscow	3
Europe/Kiev	3
Pacific/Wake	12
America/New_York	-4
Asia/Tashkent	5

@ohos.systemTime (系统时间、时区)

导入模块

systemTime.setTime

systemTime.setTime

systemTime.getCurrentTime8+

systemTime.getCurrentTime8+

systemTime.getCurrentTime8+

systemTime.getRealActiveTime8+

systemTime.getRealActiveTime8+

systemTime.getRealActiveTime8+

systemTime.getRealTime8+

systemTime.getRealTime8+

systemTime.getRealTime8+

systemTime.setDate

systemTime.setDate

systemTime.getDate8+

systemTime.getDate8+

systemTime.setTimezone

systemTime.setTimezone

systemTime.getTimezone8+

systemTime.getTimezone8+

支持的系统时区

systemTime.getCurrentTime⁸⁺

systemTime.getCurrentTime⁸⁺

systemTime.getCurrentTime⁸⁺

systemTime.getRealActiveTime⁸⁺

systemTime.getRealActiveTime⁸⁺

systemTime.getRealActiveTime⁸⁺

systemTime.getRealTime⁸⁺

systemTime.getRealTime⁸⁺

systemTime.getRealTime⁸⁺

systemTime.getDate⁸⁺

systemTime.getDate⁸⁺

systemTime.getTimezone⁸⁺

systemTime.getTimezone⁸⁺