System Time and Time Zone
The systemTime module provides system time and time zone features. You can use the APIs of this module to set and obtain the system time and time zone.
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
import systemTime from '@ohos.systemTime';
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 return the result. |
Example
// Set the system time to 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>
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 that returns no value. |
Example
// Set the system time to 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
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 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
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>
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 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 elapsed since the Unix epoch. |
Example
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 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 | No | 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
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>
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 (ns). - false: in milliseconds (ms). |
Return value
Type | Description |
---|---|
Promise<number> | Promise used to return the time elapsed since system startup, excluding the deep sleep time. |
Example
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
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 | No | 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
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>
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 (ns). - false: in milliseconds (ms). |
Return value
Type | Description |
---|---|
Promise<number> | Promise used to return the time elapsed since system startup, including the deep sleep time. |
Example
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
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 return the result. |
Example
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>
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 that returns no value. |
Example
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
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 get systemDate. Cause: ` + JSON.stringify(error));
return;
}
console.log(`Succeeded in getting systemDate. 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(`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
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 return the result. |
Example
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>
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 that returns no value. |
Example
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
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 get systemTimeZone. Cause: ` + JSON.stringify(error));
return;
}
console.log(`Succeeded in getting systemTimeZone. 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(`Succeeded in getting systemTimeZone. Data: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`Failed to get systemTimeZone. Cause: ` + JSON.stringify(error));
});