From e42aeb9b6adffc7412916a578d23daab7b9a5e1c Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Thu, 17 Nov 2022 11:35:50 +0800 Subject: [PATCH] Update doc (11419) Signed-off-by: ester.zhou --- .../reference/apis/js-apis-system-time.md | 461 +++++++++--------- 1 file changed, 221 insertions(+), 240 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-system-time.md b/en/application-dev/reference/apis/js-apis-system-time.md index 193e6a66e0..5247364504 100644 --- a/en/application-dev/reference/apis/js-apis-system-time.md +++ b/en/application-dev/reference/apis/js-apis-system-time.md @@ -4,16 +4,14 @@ The **systemTime** module provides system time and time zone features. You can u > **NOTE** > -> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import - -``` +```js import systemTime from '@ohos.systemTime'; ``` - ## systemTime.setTime setTime(time : number, callback : AsyncCallback<void>) : void @@ -26,25 +24,24 @@ Sets the system time. This API uses an asynchronous callback to return the resul **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ------------------------------------------ | -| time | number | Yes | Timestamp to set, in milliseconds. | +| Name | Type | Mandatory| Description | +| -------- | ----------- | ---- | ---------------- | +| time | number | Yes | Timestamp to set, in milliseconds. | | callback | AsyncCallback<void> | Yes | Callback used to return the result.| **Example** - ```js - // Set the system time to 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 +// Set the system time to 2021-01-20 02:36:25. +let time = 1611081385000; +systemTime.setTime(time, (error, data) => { + if (error) { + console.error(`Failed to set systemTime. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in setting systemTime. Data:` + JSON.stringify(data)); +}); +``` ## systemTime.setTime @@ -64,22 +61,21 @@ Sets the system time. This API uses a promise to return the result. **Return value** -| Type | Description | -| ------------------- | -------------------- | -| Promise<void> | Promise used to return the result.| +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| **Example** - ```js - // Set the system time to 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 +// Set the system time to 2021-01-20 02:36:25. +let time = 1611081385000; +systemTime.setTime(time).then((data) => { + console.log(`Succeeded in setting systemTime. Data:` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to set systemTime. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.getCurrentTime8+ @@ -91,23 +87,22 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | -| isNano | boolean | Yes | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds.
- **false**: in milliseconds. | -| callback | AsyncCallback<number> | Yes | Callback used to return the time. | +| Name | Type | Mandatory| Description | +| -------- | -------------- | ---- | ------------------ | +| isNano | boolean | Yes | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds (ns).
- **false**: in milliseconds (ms).| +| callback | AsyncCallback<number> | Yes | Callback used to return the time elapsed since the Unix epoch. | **Example** - ```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+ @@ -119,22 +114,21 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback<number> | Yes | Callback used to return the time. | +| Name | Type | Mandatory| Description | +| -------- | ----------- | ---- | ---------------------------------- | +| callback | AsyncCallback<number> | Yes | Callback used to return the time elapsed since the Unix epoch. | **Example** - ```js - systemTime.getCurrentTime((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((error, data) => { + if (error) { + console.error(`Succeeded in getting systemTime. Data:` + JSON.stringify(error)); + return; + } + console.log(`Failed to get systemTime. Cause:` + JSON.stringify(data)); +}); +``` ## systemTime.getCurrentTime8+ @@ -146,197 +140,191 @@ Obtains the time elapsed since the Unix epoch. This API uses a promise to return **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| isNano | boolean | No | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds.
- **false**: in milliseconds. | +| Name| Type | Mandatory| Description | +| ------ | ------- | ---- | ------------------------- | +| isNano | boolean | No | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds (ns).
- **false**: in milliseconds (ms).| **Return value** -| Type | Description | -| --------------------- | ------------------------------------------------------------ | -| Promise<number> | Promise used to return the time.| +| Type | Description | +| --------------------- | --------------------------- | +| Promise<number> | Promise used to return the time elapsed since the Unix epoch.| **Example** - ```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 -Obtains the time elapsed since system start, excluding the deep sleep time. This API uses an asynchronous callback to return the result. +Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.MiscServices.Time **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | -| isNano | boolean | Yes | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds.
- **false**: in milliseconds. | +| Name | Type | Mandatory| Description | +| -------- | ---------- | ---- | -------------------------- | +| isNano | boolean | Yes | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds (ns).
- **false**: in milliseconds (ms).| | callback | AsyncCallback<number> | Yes | Callback used to return the time.| **Example** - ```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 time. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting real active time. Data:` + JSON.stringify(data)); +}); +``` ## systemTime.getRealActiveTime8+ getRealActiveTime(callback: AsyncCallback<number>): void -Obtains the time elapsed since system start, excluding the deep sleep time. This API uses an asynchronous callback to return the result. +Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.MiscServices.Time **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | +| Name | Type | Mandatory| Description | +| -------- | -------------- | ---- | --------------------- | | callback | AsyncCallback<number> | Yes | Callback used to return the time.| **Example** - ```js - systemTime.getRealActiveTime((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((error, data) => { + if (error) { + console.error(`Failed to get real active time. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting real active time. Data:` + JSON.stringify(data)); +}); +``` ## systemTime.getRealActiveTime8+ getRealActiveTime(isNano?: boolean): Promise<number> -Obtains the time elapsed since system start, excluding the deep sleep time. This API uses a promise to return the result. +Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses a promise to return the result. **System capability**: SystemCapability.MiscServices.Time **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| isNano | boolean | No | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds.
- **false**: in milliseconds. | +| Name| Type | Mandatory| Description | +| ------ | ------- | ---- | ----------------------------------- | +| isNano | boolean | No | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds (ns).
- **false**: in milliseconds (ms).| **Return value** -| Type | Description | -| --------------------- | ------------------------------------------------------------ | -| Promise<number> | Promise used to return the time.| +| Type | Description | +| -------------- | -------------------------------- | +| Promise<number> | Promise used to return the time elapsed since system startup, excluding the deep sleep time.| **Example** - ```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 time. Data:` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get real active time. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.getRealTime8+ getRealTime(isNano: boolean, callback: AsyncCallback<number>): void -Obtains the time elapsed since system start, including the deep sleep time. This API uses an asynchronous callback to return the result. +Obtains the time elapsed since system startup, including the deep sleep time. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.MiscServices.Time **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | -| isNano | boolean | Yes | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds.
- **false**: in milliseconds. | +| Name | Type | Mandatory| Description | +| -------- | --------------- | ---- | ------------------------------- | +| isNano | boolean | Yes | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds (ns).
- **false**: in milliseconds (ms).| | callback | AsyncCallback<number> | Yes | Callback used to return the time. | **Example** - ```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 time. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting real time. Data:` + JSON.stringify(data)); +}); +``` ## systemTime.getRealTime8+ getRealTime(callback: AsyncCallback<number>): void -Obtains the time elapsed since system start, including the deep sleep time. This API uses an asynchronous callback to return the result. +Obtains the time elapsed since system startup, including the deep sleep time. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.MiscServices.Time **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | +| Name | Type | Mandatory| Description | +| -------- | --------- | ---- | --------------------------- | | callback | AsyncCallback<number> | Yes | Callback used to return the time. | **Example** - ```js - systemTime.getRealTime((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((error, data) => { + if (error) { + console.error(`Failed to get real time. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting real time. Data:` + JSON.stringify(data)); +}); +``` ## systemTime.getRealTime8+ getRealTime(isNano?: boolean): Promise<number> -Obtains the time elapsed since system start, including the deep sleep time. This API uses a promise to return the result. +Obtains the time elapsed since system startup, including the deep sleep time. This API uses a promise to return the result. **System capability**: SystemCapability.MiscServices.Time **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| isNano | boolean | No | Whether the time to return is in nanoseconds.
- **true**: in nanoseconds.
- **false**: in milliseconds. | +| Name| Type | Mandatory| Description | +| ------ | ------- | ---- | ------------------------------- | +| isNano | boolean | No | Whether the time to return is in nanoseconds.<
- **true**: in nanoseconds (ns).
- **false**: in milliseconds (ms).| **Return value** -| Type | Description | -| --------------------- | ------------------------------------------------------------ | -| Promise<number> | Promise used to return the time.| +| Type | Description | +| --------------------- | ------------------------------- | +| Promise<number> | Promise used to return the time elapsed since system startup, including the deep sleep time.| **Example** - ```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 time. Data:` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get real time. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.setDate @@ -350,24 +338,23 @@ Sets the system date. This API uses an asynchronous callback to return the resul **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ------------------------------------------ | +| Name | Type | Mandatory| Description | +| -------- | ------------- | ---- | --------------------- | | date | Date | Yes | Target date to set. | | callback | AsyncCallback<void> | Yes | Callback used to return the result.| **Example** - ```js - var data = new Date(); - 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(); +systemTime.setDate(data,(error, data) => { + if (error) { + console.error('Failed to set system date. Cause:' + JSON.stringify(error)); + return; +} + console.info('Succeeded in setting system date. Data:' + JSON.stringify(data)); +}); +``` ## systemTime.setDate @@ -389,19 +376,18 @@ Sets the system date. This API uses a promise to return the result. | Type | Description | | ------------------- | -------------------- | -| Promise<void> | Promise used to return the result.| +| Promise<void> | Promise that returns no value.| **Example** - ```js - var data = new Date(); - 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(); +systemTime.setDate(data).then((value) => { + console.log(`Succeeded in setting system date. Data:` + JSON.stringify(value)); +}).catch((error) => { + console.error(`Failed to set system date. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.getDate8+ @@ -413,28 +399,27 @@ Obtains the current system date. This API uses an asynchronous callback to retur **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ---------------------------- | +| Name | Type | Mandatory| Description | +| -------- | -------------- | ---- | --------------------- | | callback | AsyncCallback<Date> | Yes | Callback used to return the current system date.| **Example** - ```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 system date. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting system date. Data:` + JSON.stringify(data)); +}); +``` ## systemTime.getDate8+ getDate(): Promise<Date> -Obtains the current system date. This API uses a promise to return the result. +Obtains the current system date. This API uses a promise to return the result. **System capability**: SystemCapability.MiscServices.Time @@ -446,14 +431,13 @@ Obtains the current system date. This API uses a promise to return the result. **Example** - ```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 system date. Data:` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get system date. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.setTimezone @@ -467,23 +451,22 @@ Sets the system time zone. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ------------------------------------------ | +| Name | Type | Mandatory| Description | +| -------- | ------------- | ---- | -------------------------- | | timezone | string | Yes | System time zone to set. | | callback | AsyncCallback<void> | Yes | Callback used to return the result.| **Example** - ```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, data) => { + if (error) { + console.error('Failed to set system time zone. Cause:' + JSON.stringify(error)); + return; + } + console.info('Succeeded in setting system time zone. Data:' + JSON.stringify(data)); +}); +``` ## systemTime.setTimezone @@ -505,18 +488,17 @@ Sets the system time zone. This API uses a promise to return the result. | Type | Description | | ------------------- | -------------------- | -| Promise<void> | Promise used to return the result.| +| Promise<void> | Promise that returns no value.| **Example** - ```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((data) => { + console.log(`Succeeded in setting system time zone. Data:` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to set system time zone. Cause:` + JSON.stringify(error)); +}); +``` ## systemTime.getTimezone8+ @@ -528,22 +510,21 @@ Obtains the system time zone. This API uses an asynchronous callback to return t **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------ | +| Name | Type | Mandatory| Description | +| -------- | --------- | ---- | ------------------------ | | callback | AsyncCallback<string> | Yes | Callback used to return the system time zone.| **Example** - ```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 system time zone. Cause:` + JSON.stringify(error)); + return; + } + console.log(`Succeeded in getting system time zone. Data:` + JSON.stringify(data)); +}); +``` ## systemTime.getTimezone8+ @@ -561,10 +542,10 @@ Obtains the system time zone. This API uses a promise to return the result. **Example** - ```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 system time zone. Data:` + JSON.stringify(data)); +}).catch((error) => { + console.error(`Failed to get system time zone. Cause:` + JSON.stringify(error)); +}); +``` -- GitLab