diff --git a/zh-cn/application-dev/reference/apis/js-apis-system-time.md b/zh-cn/application-dev/reference/apis/js-apis-system-time.md index c34f72f04d7d2dc04795da43569f38c9801a9e15..425d261d08a8c2fee4409d71c97372981dc7b1c9 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-system-time.md +++ b/zh-cn/application-dev/reference/apis/js-apis-system-time.md @@ -1,24 +1,22 @@ -# 设置系统时间 +# 设置系统时间、时区 -本模块用来设置、获取当前系统时间，设置、获取当前系统日期和设置、获取当前系统时区。 +本模块用来设置、获取当前系统时间、系统日期和系统时区。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** +> > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 - ## 导入模块 - -``` +```js import systemTime from '@ohos.systemTime'; ``` - ## systemTime.setTime setTime(time : number, callback : AsyncCallback<void>) : void -设置系统时间。 +设置系统时间，使用callback异步回调。 **需要权限：** ohos.permission.SET_TIME @@ -26,31 +24,30 @@ setTime(time : number, callback : AsyncCallback<void>) : void **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | time | number | 是 | 目标时间戳（ms）。 | - | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| time | number | 是 | 目标时间戳（ms）。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | **示例：** - - ```js - // time对应的时间为2021-01-20 02:36:25 - var time = 1611081385000; - systemTime.setTime(time, (error, data) => { - if (error) { - console.error(`failed to systemTime.setTime because ` + JSON.stringify(error)); - return; - } - console.log(`systemTime.setTime success data : ` + JSON.stringify(data)); - }); - ``` +```js +// time对应的时间为2021-01-20 02:36:25 +let time = 1611081385000; +systemTime.setTime(time, (error) => { + if (error) { + console.error(`Failed to set systemTime. Cause:` + JSON.stringify(error)); + return; + } + console.log('Succeeded in setting systemTime.'); +}); +``` ## systemTime.setTime setTime(time : number) : Promise<void> -设置系统时间。 +设置系统时间，使用Promise异步回调。 **需要权限：** ohos.permission.SET_TIME @@ -58,211 +55,204 @@ setTime(time : number) : Promise<void> **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | time | number | 是 | 目标时间戳（ms）。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| time | number | 是 | 目标时间戳（ms）。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<void> | 返回的异步回调函数。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | 无返回结果的Promise对象。 | **示例：** - - ```js - // time对应的时间为2021-01-20 02:36:25 - var time = 1611081385000; - systemTime.setTime(time).then((data) => { - console.log(`systemTime.setTime success data : ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.setTime because ` + JSON.stringify(error)); - }); - ``` +```js +// time对应的时间为2021-01-20 02:36:25 +let time = 1611081385000; +systemTime.setTime(time).then(() => { + console.log('Succeeded in setting systemTime.'); +}).catch((error) => { + console.error(`Failed to set systemTime. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.getCurrentTime8+ getCurrentTime(isNano?: boolean, callback: AsyncCallback<number>): void -获取自 Unix 纪元以来经过的时间，使用callback形式返回结果。 +获取自Unix纪元以来经过的时间，使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | - | callback | AsyncCallback<number> | 是 | 回调函数，返回自 Unix 纪元以来经过的时间。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | +| callback | AsyncCallback<number> | 是 | 回调函数，返回自Unix纪元以来经过的时间。 | **示例：** - - ```js - systemTime.getCurrentTime(true, (error, data) => { - if (error) { - console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error)); - return; - } - console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data)); - }); - ``` +```js +systemTime.getCurrentTime(true, (error, data) => { + if (error) { + console.error(`Failed to get systemTime. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting systemTime.Data: ` + JSON.stringify(data)); +}); +``` ## systemTime.getCurrentTime8+ getCurrentTime(isNano?: boolean): Promise<number> -获取自 Unix 纪元以来经过的时间，使用Promise形式返回结果。 +获取自Unix纪元以来经过的时间，使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<number> | 以Promise形式返回结果，返回自 Unix 纪元以来经过的时间。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<number> | Promise对象，返回自Unix纪元以来经过的时间。 | **示例：** - - ```js - systemTime.getCurrentTime().then((data) => { - console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error)); - }); - ``` +```js +systemTime.getCurrentTime().then((data) => { + console.log(`Succeeded in getting systemTime.Data: ` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get systemTime. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.getRealActiveTime8+ getRealActiveTime(isNano?: boolean, callback: AsyncCallback<number>): void -获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback形式返回结果。 +获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | - | callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | +| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | **示例：** - - ```js - systemTime.getRealActiveTime(true, (error, data) => { - if (error) { - console.error(`failed to systemTime.getRealActiveTimebecause ` + JSON.stringify(error)); - return; - } - console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data)); - }); - ``` +```js +systemTime.getRealActiveTime(true, (error, data) => { + if (error) { + console.error(`Failed to get real active systemTime. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); +}); +``` ## systemTime.getRealActiveTime8+ getRealActiveTime(isNano?: boolean): Promise<number> -获取自系统启动以来经过的时间，不包括深度睡眠时间，使用Promise形式返回结果。 +获取自系统启动以来经过的时间，不包括深度睡眠时间，使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<number> | 以Promise形式返回结果，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<number> | Promise对象，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | **示例：** - - ```js - systemTime.getRealActiveTime().then((data) => { - console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.getRealActiveTime because ` + JSON.stringify(error)); - }); - ``` +```js +systemTime.getRealActiveTime().then((data) => { + console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get real active systemTime. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.getRealTime8+ getRealTime(isNano?: boolean, callback: AsyncCallback<number>): void -获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback形式返回结果。 +获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | - | callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | +| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。 | **示例：** - - ```js - systemTime.getRealTime(true, (error, data) => { - if (error) { - console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error)); - return; - } - console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data)); - }); - ``` +```js +systemTime.getRealTime(true, (error, data) => { + if (error) { + console.error(`Failed to get real systemTime. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); +}); +``` ## systemTime.getRealTime8+ getRealTime(isNano?: boolean): Promise<number> -获取自系统启动以来经过的时间，包括深度睡眠时间，使用Promise形式返回结果。 +获取自系统启动以来经过的时间，包括深度睡眠时间，使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| isNano | boolean | 否 | 如果是true，返回纳秒数；否则返回毫秒数。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<number> | 以Promise形式返回结果，返回自系统启动以来经过的时间，包括深度睡眠时间。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<number> | Promise对象，返回自系统启动以来经过的时间，包括深度睡眠时间。 | **示例：** - - ```js - systemTime.getRealTime().then((data) => { - console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error)); - }); - ``` +```js +systemTime.getRealTime().then((data) => { + console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get real systemTime. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.setDate setDate(date: Date, callback: AsyncCallback<void>): void -设置系统日期，使用callback形式返回结果。 +设置系统日期，使用callback异步回调。 **需要权限：** ohos.permission.SET_TIME @@ -270,30 +260,29 @@ setDate(date: Date, callback: AsyncCallback<void>): void **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | date | Date | 是 | 目标日期。 | - | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| date | Date | 是 | 目标日期。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | **示例：** - - ```js - var data = new Date("October 13, 2020 11:13:00"); - systemTime.setDate(data,(error, data) => { - if (error) { - console.error('failed to systemTime.setDate because ' + JSON.stringify(error)); - return; - } - console.info('systemTime.setDate success data : ' + JSON.stringify(data)); - }); - ``` +```js +let data = new Date("October 13, 2020 11:13:00"); +systemTime.setDate(data,(error) => { + if (error) { + console.error('Failed to set systemDate. Cause: ' + JSON.stringify(error)); + return; +} + console.info('Succeeded in setting systemDate.'); +}); +``` ## systemTime.setDate setDate(date: Date): Promise<void> -设置系统日期，使用Promise形式返回结果。 +设置系统日期，使用Promise异步回调。 **需要权限：** ohos.permission.SET_TIME @@ -301,85 +290,82 @@ setDate(date: Date): Promise<void> **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | date | Date | 是 | 目标日期。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| date | Date | 是 | 目标日期。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<void> | 返回的异步回调函数。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | 无返回结果的Promise对象。 | **示例：** - - ```js - var data = new Date("October 13, 2020 11:13:00"); - systemTime.setDate(data).then((value) => { - console.log(`systemTime.setDate success data : ` + JSON.stringify(value)); - }).catch((error) => { - console.error(`failed to systemTime.setDate because: ` + JSON.stringify(error)); - }); - ``` +```js +let data = new Date("October 13, 2020 11:13:00"); +systemTime.setDate(data).then(() => { + console.log('Succeeded in setting systemDate.'); +}).catch((error) => { + console.error(`Failed to set systemDate. Cause: ` + JSON.stringify(error)); +}); +``` ## systemTime.getDate8+ getDate(callback: AsyncCallback<Date>): void -获取当前系统日期，使用callback形式返回结果。 +获取当前系统日期，使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<Date> | 是 | 回调函数，返回当前系统日期。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<Date> | 是 | 回调函数，返回当前系统日期。 | **示例：** - - ```js - systemTime.getDate((error, data) => { - if (error) { - console.error(`failed to systemTime.getDate because ` + JSON.stringify(error)); - return; - } - console.log(`systemTime.getDate success data : ` + JSON.stringify(data)); - }); - ``` +```js +systemTime.getDate((error, data) => { + if (error) { + console.error(`Failed to get systemDate. Cause: ` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting systemDate. Data: ` + JSON.stringify(data)); +}); +``` ## systemTime.getDate8+ getDate(): Promise<Date> -获取当前系统日期，使用Promise形式返回结果。 +获取当前系统日期，使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.Time **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<Date> | 以Promise形式返回结果，返回当前系统日期。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<Date> | Promise对象，返回当前系统日期。 | **示例：** - - ```js - systemTime.getDate().then((data) => { - console.log(`systemTime.getDate success data : ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.getDate because ` + JSON.stringify(error)); - }); - ``` +```js +systemTime.getDate().then((data) => { + console.log(`Succeeded in getting systemDate. Data: ` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get systemDate. Cause: ` + JSON.stringify(error)); +}); +``` ## systemTime.setTimezone setTimezone(timezone: string, callback: AsyncCallback<void>): void -设置系统时区。 +设置系统时区，使用callback异步回调。 **需要权限：** ohos.permission.SET_TIME_ZONE @@ -387,29 +373,28 @@ setTimezone(timezone: string, callback: AsyncCallback<void>): void **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | timezone | string | 是 | 系统时区。 | - | callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| timezone | string | 是 | 系统时区。 | +| callback | AsyncCallback<void> | 是 | 回调函数。 | **示例：** - - ```js - systemTime.setTimezone('Asia/Shanghai', (error, data) => { - if (error) { - console.error('failed to systemTime.setTimezone because ' + JSON.stringify(error)); - return; - } - console.info('SystemTimePlugin systemTime.setTimezone success data : ' + JSON.stringify(data)); - }); - ``` +```js +systemTime.setTimezone('Asia/Shanghai', (error) => { + if (error) { + console.error('Failed to set systemTimeZone. Cause: ' + JSON.stringify(error)); + return; + } + console.info('Succeeded in setting systemTimeZone.'); +}); +``` ## systemTime.setTimezone setTimezone(timezone: string): Promise<void> -设置系统时区。 +设置系统时区，使用Promise异步回调。 **需要权限：** ohos.permission.SET_TIME_ZONE @@ -417,74 +402,72 @@ setTimezone(timezone: string): Promise<void> **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | timezone | string | 是 | 系统时区。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| timezone | string | 是 | 系统时区。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<void> | 返回的异步回调函数。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | 无返回结果的Promise对象。 | **示例：** - - ```js - systemTime.setTimezone('Asia/Shanghai').then((data) => { - console.log(`systemTime.setTimezone success data : ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.setTimezone because: ` + JSON.stringify(error)); - }); - ``` +```js +systemTime.setTimezone('Asia/Shanghai').then(() => { + console.log('Succeeded in setting systemTimeZone.'); +}).catch((error) => { + console.error(`Failed to set systemTimeZone. Cause: ` + JSON.stringify(error)); +}); +``` ## systemTime.getTimezone8+ getTimezone(callback: AsyncCallback<string>): void -获取系统时区，使用callback形式返回结果。 +获取系统时区，使用callback异步回调。 **系统能力：** SystemCapability.MiscServices.Time **参数：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<string> | 是 | 回调函数，返回系统时区。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<string> | 是 | 回调函数，返回系统时区。 | **示例：** - - ```js - systemTime.getTimezone((error, data) => { - if (error) { - console.error(`failed to systemTime.getTimezone because ` + JSON.stringify(error)); - return; - } - console.log(`systemTime.getTimezone success data : ` + JSON.stringify(data)); - }); - ``` +```js +systemTime.getTimezone((error, data) => { + if (error) { + console.error(`Failed to get systemTimeZone. Cause: ` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting systemTimeZone. Data: ` + JSON.stringify(data)); +}); +``` ## systemTime.getTimezone8+ getTimezone(): Promise<string> -获取系统时区，使用Promise形式返回结果。 +获取系统时区，使用Promise异步回调。 **系统能力：** SystemCapability.MiscServices.Time **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<string> | 以Promise形式返回结果，返回系统时区。 | +| 类型 | 说明 | +| -------- | -------- | +| Promise<string> | Promise对象，返回系统时区。 | **示例：** - - ```js - systemTime.getTimezone().then((data) => { - console.log(`systemTime.getTimezone success data : ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.getTimezone because ` + JSON.stringify(error)); - }); - ``` + +```js +systemTime.getTimezone().then((data) => { + console.log(`Succeeded in getting systemTimeZone. Data: ` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get systemTimeZone. Cause: ` + JSON.stringify(error)); +}); +``` \ No newline at end of file