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 d7cedf77c5f9d2c403e243952dba0ba3e8974564..31f3f1303601716d2f471a514487827b1b2dfae1 100644 --- a/en/application-dev/reference/apis/js-apis-system-time.md +++ b/en/application-dev/reference/apis/js-apis-system-time.md @@ -1,355 +1,466 @@ -# Setting the System Time +# Setting the System Time ->![](../../public_sys-resources/icon-note.gif) **NOTE:** ->The APIs of this module are supported since API version 7. +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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. -## Modules to Import +## Modules to Import + ``` import systemTime from '@ohos.systemTime'; ``` -## systemTime.setTime - -setTime\(time : number, callback : AsyncCallback\) : void - -Set the system time. You must have the ohos.permission.SET\_TIME permission. The value is returned in callback mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

time

-

number

-

Yes

-

Timestamp to set, in milliseconds

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to process the received return value

-
- -- Example - - ``` - // Set the date and 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(`success to systemTime.setTime: ` + JSON.stringify(data)); - }); - ``` - - -## systemTime.setTime - -setTime\(time : number\) : Promise - -Set the system time. You must have the ohos.permission.SET\_TIME permission. The value is returned in promise mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

time

-

number

-

Yes

-

Timestamp to set, in milliseconds

-
- - -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Callback returned in promise mode

-
- -- Example - - ``` - // Set the date and time to 2021-01-20 02:36:25. - var time = 1611081385000; - systemTime.setTime(time).then((data) => { - console.log(`success to systemTime.setTime: ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`failed to systemTime.setTime because ` + JSON.stringify(error)); - }); - ``` - - -## systemTime.setDate - -setDate\(date: Date, callback: AsyncCallback\): void - -Set the system date. You must have the ohos.permission.SET\_TIME permission. The value is returned in callback mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

date

-

Date

-

Yes

-

Target date

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to process the received return value

-
- -- Example - - ``` - var data = new Date("October 13, 2020 11:13:00"); - systemTime.setDate(data,(error, data) => { - if (error) { - console.error('SystemTimePlugin setDate failed because ' + JSON.stringify(error)); - return; - } - console.info('SystemTimePlugin setDate success data : ' + JSON.stringify(data)); - }); - ``` - - -## systemTime.setDate - -setDate\(date: Date\): Promise - -Set the system date. You must have the ohos.permission.SET\_TIME permission. The value is returned in promise mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

date

-

Date

-

Yes

-

Target date

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Callback returned in promise mode

-
- -- Example - - ``` - var data = new Date("October 13, 2020 11:13:00"); - systemTime.setDate(data).then((value) => { - console.log(`SystemTimePlugin success to systemTime.setDate: ` + JSON.stringify(value)); - }).catch((error) => { - console.error(`SystemTimePlugin failed to systemTime.setDate because: ` + JSON.stringify(error)); - }); - ``` - - -## systemTime.setTimezone - -setTimezone\(timezone: string, callback: AsyncCallback\): void - -Set the system time zone. You must have the ohos.permission.SET\_TIME\_ZONE permission. The value is returned in callback mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

timezone

-

string

-

Yes

-

System time zone

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to process the received return value

-
- -- Example - - ``` - systemTime.setTimezone('Asia/Shanghai', (error, data) => { - if (error) { - console.error('SystemTimePlugin setTimezone failed because ' + JSON.stringify(error)); - return; - } - console.info('SystemTimePlugin setTimezone success data : ' + JSON.stringify(data)); - }); - ``` - - -## systemTime.setTimezone - -setTimezone\(timezone: string\): Promise - -Set the system time zone. You must have the ohos.permission.SET\_TIME\_ZONE permission. The value is returned in promise mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

timezone

-

string

-

Yes

-

System time zone

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Callback returned in promise mode

-
- -- Example - - ``` - systemTime.setTimezone('Asia/Shanghai').then((data) => { - console.log(`SystemTimePlugin success to systemTime.setTimezone: ` + JSON.stringify(data)); - }).catch((error) => { - console.error(`SystemTimePlugin failed to systemTime.setTimezone because: ` + JSON.stringify(error)); - }); - ``` +## systemTime.setTime +setTime(time : number, callback : AsyncCallback<void>) : void + +Sets the system time. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_TIME + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | time | number | Yes| Timestamp to set, in milliseconds.| + | callback | AsyncCallback<void> | Yes| Callback used to process the received return value.| + +- Example + + ``` + // 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)); + }); + ``` + + +## systemTime.setTime + +setTime(time : number) : Promise<void> + +Sets the system time. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.SET_TIME + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | time | number | Yes| Timestamp to set, in milliseconds.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + + ``` + // 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)); + }); + ``` + + +## systemTime.getCurrentTime8+ + +getCurrentTime(isNano?: boolean, callback: AsyncCallback<number>): void + +Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.| + | callback | AsyncCallback<number> | Yes| Callback used to return the time.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.getCurrentTime8+ + +getCurrentTime(isNano?: boolean): Promise<number> + +Obtains the time elapsed since the Unix epoch. This API uses a promise to return the result. + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<number> | Promise used to return the time.| + +- Example + + ``` + 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)); + }); + ``` + + +## 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. + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.| + | callback | AsyncCallback<number> | Yes| Callback used to return the time.| + +- Example + + ``` + 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)); + }); + ``` + + +## 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. + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<number> | Promise used to return the time.| + +- Example + + ``` + systemTime.getCurrentTime().then((data) => { + console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data)); + }).catch((error) => { + console.error(`failed to systemTime.getRealActiveTime because ` + JSON.stringify(error)); + }); + ``` + + +## 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. + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.| + | callback | AsyncCallback<number> | Yes| Callback used to return the time.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.getRealTime8+ + +getRealTime(): Promise<number> + +Obtains the time elapsed since system start, 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 nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<number> | Promise used to return the time.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.setDate + +setDate(date: Date, callback: AsyncCallback<void>): void + +Sets the system date. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_TIME + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | date | Date | Yes| Target date to set.| + | callback | AsyncCallback<void> | Yes| Callback used to process the received return value.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.setDate + +setDate(date: Date): Promise<void> + +Sets the system date. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.SET_TIME + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | date | Date | Yes| Target date to set.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.getDate8+ + +getDate(callback: AsyncCallback<Date>): void + +Obtains the current system date. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<Date> | Yes| Callback used to return the current system date.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.getDate8+ + +getDate(): Promise<Date> + +Obtains the current system date. This API uses a promise to return the result. + +**System capability**: SystemCapability.Miscservices.Time + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<Date> | Promise used to return the current system date.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.setTimezone + +setTimezone(timezone: string, callback: AsyncCallback<void>): void + +Sets the system time zone. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_TIME_ZONE + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | timezone | string | Yes| System time zone to set.| + | callback | AsyncCallback<void> | Yes| Callback used to process the received return value.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.setTimezone + +setTimezone(timezone: string): Promise<void> + +Sets the system time zone. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.SET_TIME_ZONE + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | timezone | string | Yes| System time zone to set.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.getTimezone8+ + +getTimezone(callback: AsyncCallback<string>): void + +Obtains the system time zone. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Miscservices.Time + +- **Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | Yes| Callback used to return the system time zone.| + +- Example + + ``` + 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)); + }); + ``` + + +## systemTime.getTimezone8+ + +getTimezone(): Promise<string> + +Obtains the system time zone. This API uses a promise to return the result. + +**System capability**: SystemCapability.Miscservices.Time + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<string> | Promise used to return the system time zone.| + +- Example + + ``` + 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)); + }); + ```