diff --git a/en/application-dev/background-agent-scheduled-reminder/background-agent-scheduled-reminder-guide.md b/en/application-dev/background-agent-scheduled-reminder/background-agent-scheduled-reminder-guide.md index af3a0ef7b32ceef033874010047e12de41f0a67a..63e42760af0329365bd1a0379a21259dd3502c14 100644 --- a/en/application-dev/background-agent-scheduled-reminder/background-agent-scheduled-reminder-guide.md +++ b/en/application-dev/background-agent-scheduled-reminder/background-agent-scheduled-reminder-guide.md @@ -1,606 +1,214 @@ -# Agent-Powered Scheduled Reminder Development - -## When to Use - -You can set your application to call the **ReminderRequest** class to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background, even when your application is frozen or exits. - -## Available APIs - -**reminderAgent** encapsulates the methods for publishing and canceling reminders. - -**Table 1** Major APIs in reminderAgent - - - - - - - - - - - - - - - - - - - - - - - - - -

API

-

Description

-

function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void;

-

function publishReminder(reminderReq: ReminderRequest): Promise<number>;

-

Publishes a scheduled reminder.

-

The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system.

-

function cancelReminder(reminderId: number, callback: AsyncCallback<void>): void;

-

function cancelReminder(reminderId: number): Promise<void>;

-

Cancels a specified reminder. (The value of reminderId is obtained from the return value of publishReminder.)

-

function getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void;

-

function getValidReminders(): Promise<Array<ReminderRequest>>;

-

Obtains all valid reminders set by the current application.

-

function cancelAllReminders(callback: AsyncCallback<void>): void;

-

function cancelAllReminders(): Promise<void>;

-

Cancels all reminders set by the current application.

-

function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void;

-

function addNotificationSlot(slot: NotificationSlot): Promise<void>;

-

Registers a NotificationSlot instance to be used by the reminder.

-

function removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void;

-

function removeNotificationSlot(slotType: notification.SlotType): Promise<void>;

-

Removes a NotificationSlot instance of a specified type.

-
- -**ActionButtonType** enumerates types of buttons displayed in a reminder notification. - -**Table 2** ActionButtonType enumeration - - - - - - - - - - -

Name

-

Description

-

ACTION_BUTTON_TYPE_CLOSE

-

Close button, which can be tapped to stop the reminder alert tone, close the reminder notification, and cancel the reminder snoozing.

-
- -**ReminderType** enumerates the reminder types. - -**Table 3** ReminderType enumeration - - - - - - - - - - - - - - - - -

Name

-

Description

-

REMINDER_TYPE_TIMER

-

Countdown reminder.

-

REMINDER_TYPE_CALENDAR

-

Calendar reminder.

-

REMINDER_TYPE_ALARM

-

Alarm reminder.

-
- -**ActionButton** defines a button displayed in the reminder notification. - -**Table 4** ActionButton instance - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

title

-

string

-

Yes

-

Text on the button.

-

type

-

ActionButtonType

-

Yes

-

Button type.

-
- -**WantAgent** sets the package and ability that are redirected to when the reminder notification is clicked. - -**Table 5** WantAgent instance - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

pkgName

-

string

-

Yes

-

Name of the package redirected to when the reminder notification is clicked.

-

abilityName

-

string

-

Yes

-

Name of the ability redirected to when the reminder notification is clicked.

-
- -**MaxScreenWantAgent** sets the name of the target package and ability to start automatically when the reminder arrives and the device is not in use. If the device is in use, a notification will be displayed. - -**Table 6** MaxScreenWantAgent instance - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

pkgName

-

string

-

Yes

-

Name of the package that is automatically started when the reminder arrives and the device is not in use.

-

abilityName

-

string

-

Yes

-

Name of the ability that is automatically started when the reminder arrives and the device is not in use.

-
- -**ReminderRequest** defines the reminder to publish. - -**Table 7** ReminderRequest instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

reminderType

-

ReminderType

-

Yes

-

Type of the reminder.

-

actionButton

-

[ActionButton?, ActionButton?]

-

No

-

Action button displayed in the reminder notification.

-

wantAgent

-

WantAgent

-

No

-

Information about the ability that is redirected to when the notification is clicked.

-

maxScreenWantAgent

-

MaxScreenWantAgent

-

No

-

Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.

-

ringDuration

-

number

-

No

-

Ring duration.

-

snoozeTimes

-

number

-

No

-

Number of reminder snooze times.

-

timeInterval

-

number

-

No

-

Reminder snooze interval.

-

title

-

string

-

No

-

Reminder title.

-

content

-

string

-

No

-

Reminder content.

-

expiredContent

-

string

-

No

-

Extended content to be displayed when the reminder expires.

-

snoozeContent

-

string

-

No

-

Extended content to be displayed when the reminder is snoozing.

-

notificationId

-

number

-

No

-

Notification ID used by the reminder. For details, see the API reference of the NotificationRequest::SetNotificationId(int32_t id) method.

-

slotType

-

SlotType

-

No

-

Type of the slot used by the reminder.

-
- -**ReminderRequestCalendar** extends **ReminderRequest** and defines a reminder for a calendar event. +# Agent-Powered Scheduled Reminder Development + +## When to Use + +You can set your application to call the **ReminderRequest** class to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background, even when your application is frozen or exits. + +## Available APIs + +**reminderAgent** encapsulates the methods for publishing and canceling reminders. + +**Table 1** Major APIs in reminderAgent + + + +| API | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback\): void;
function publishReminder(reminderReq: ReminderRequest): Promise\; | Publishes a scheduled reminder.
The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system. | +| function cancelReminder(reminderId: number, callback: AsyncCallback\): void;
function cancelReminder(reminderId: number): Promise\; | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.) | +| function getValidReminders(callback: AsyncCallback>): void;
function getValidReminders(): Promise>; | Obtains all valid reminders set by the current application. | +| function cancelAllReminders(callback: AsyncCallback\): void;
function cancelAllReminders(): Promise\; | Cancels all reminders set by the current application. | +| function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback\): void;
function addNotificationSlot(slot: NotificationSlot): Promise; | Registers a NotificationSlot instance to be used by the reminder. | +| function removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback\): void;function removeNotificationSlot(slotType: notification.SlotType): Promise\; | Removes a NotificationSlot instance of a specified type. | + +**ActionButtonType** enumerates types of buttons displayed in a reminder notification. + +**Table 2** ActionButtonType enumeration + + + +| Name | Description | +| ------------------------ | ------------------------------------------------------------ | +| ACTION_BUTTON_TYPE_CLOSE | Close button, which can be tapped to stop the reminder alert tone, close the reminder notification, and cancel the reminder snoozing. | + +**ReminderType** enumerates the reminder types. + +**Table 3** ReminderType enumeration + + + +| Name | Description | +| ---------------------- | ------------------- | +| REMINDER_TYPE_TIMER | Countdown reminder. | +| REMINDER_TYPE_CALENDAR | Calendar reminder. | +| REMINDER_TYPE_ALARM | Alarm reminder. | + +**ActionButton** defines a button displayed in the reminder notification. + +**Table 4** ActionButton instance + + + +| Name | Type | Mandatory | Description | +| ----- | ---------------- | --------- | ------------------- | +| title | string | Yes | Text on the button. | +| type | ActionButtonType | Yes | Button type. | + +**WantAgent** sets the package and ability that are redirected to when the reminder notification is clicked. + +**Table 5** WantAgent instance + + + +| Name | Type | Mandatory | Description | +| ----------- | ------ | --------- | ------------------------------------------------------------ | +| pkgName | string | Yes | Name of the package redirected to when the reminder notification is clicked. | +| abilityName | string | Yes | Name of the ability redirected to when the reminder notification is clicked. | + +**MaxScreenWantAgent** sets the name of the target package and ability to start automatically when the reminder arrives and the device is not in use. If the device is in use, a notification will be displayed. + +**Table 6** MaxScreenWantAgent instance + + + +| Name | Type | Mandatory | Description | +| ----------- | ------ | --------- | ------------------------------------------------------------ | +| pkgName | string | Yes | Name of the package that is automatically started when the reminder arrives and the device is not in use. | +| abilityName | string | Yes | Name of the ability that is automatically started when the reminder arrives and the device is not in use. | + +**ReminderRequest** defines the reminder to publish. + +**Table 7** ReminderRequest instance + + + +| Name | Type | Mandatory | Description | +| ------------------ | ------------------------------ | --------- | ------------------------------------------------------------ | +| reminderType | ReminderType | Yes | Type of the reminder. | +| actionButton | [ActionButton?, ActionButton?] | No | Action button displayed in the reminder notification. | +| wantAgent | WantAgent | No | Information about the ability that is redirected to when the notification is clicked. | +| maxScreenWantAgent | MaxScreenWantAgent | No | Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed. | +| ringDuration | number | No | Ring duration. | +| snoozeTimes | number | No | Number of reminder snooze times. | +| timeInterval | number | No | Reminder snooze interval. | +| title | string | No | Reminder title. | +| content | string | No | Reminder content. | +| expiredContent | string | No | Extended content to be displayed when the reminder expires. | +| snoozeContent | string | No | Extended content to be displayed when the reminder is snoozing. | +| notificationId | number | No | Notification ID used by the reminder. For details, see the API reference of the **NotificationRequest.setNotificationId(int id)** method. | +| slotType | SlotType | No | Type of the slot used by the reminder. | + +**ReminderRequestCalendar** extends **ReminderRequest** and defines a reminder for a calendar event. For the application to run properly, if both **repeatMonths** and **repeatDays** are not specified, the earliest reminder time must be later than the current time. -**Table 8** ReminderRequestCalendar instance - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

dateTime

-

LocalDateTime

-

Yes

-

Reminder time, accurate to the minute.

-

repeatMonths

-

Array<number>

-

No

-

Months in which the reminder repeats. The value range is 1 to 12.

-

repeatDays

-

Array<number>

-

No

-

Date on which the reminder repeats. The value range is 1 to 31.

-
- -**ReminderRequestAlarm** extends **ReminderRequest** and defines a reminder for the alarm clock. - -**Table 9** ReminderRequestAlarm instance - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

hour

-

number

-

Yes

-

Hour portion of the reminder time. The value range is 0 to 23.

-

minute

-

number

-

Yes

-

Minute portion of the reminder time. The value range is 0 to 59.

-

daysOfWeek

-

Array<number>

-

No

-

Days of a week when the reminder repeats. The value range is 1 to 7.

-
- -**ReminderRequestTimer** extends **ReminderRequest** and defines a reminder for a scheduled timer. - -**Table 10** ReminderRequestTimer instance - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

triggerTimeInSeconds

-

number

-

Yes

-

Number of seconds in the countdown timer.

-
- -**LocalDateTime** defines a **LocalDateTime** instance. - -**Table 11** LocalDateTime instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

year

-

number

-

Yes

-

Year.

-

month

-

number

-

Yes

-

Month.

-

day

-

number

-

Yes

-

Date.

-

hour

-

number

-

Yes

-

Hour.

-

minute

-

number

-

Yes

-

Minute.

-

second

-

number

-

No

-

Second.

-
- -## How to Develop - ->**NOTE**
->To publish a reminder, your application needs to apply for the **ohos.permission.PUBLISH\_AGENT\_REMINDER** permission. +**Table 8** ReminderRequestCalendar instance -Publish a 10-second countdown reminder. -1. Define a countdown timer instance. - - ``` - import reminderAgent from '@ohos.reminderAgent'; - import notification from '@ohos.notification'; - export default { - // In JS Project: - // timer: { - // In eTS Project: - let timer : reminderAgent.ReminderRequestTimer = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, - triggerTimeInSeconds: 10, - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - } - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION - } - } - ``` - -2. Publish the reminder. - - ``` - startTimer() { - reminderAgent.publishReminder(this.timer, (err, reminderId) =>{ - this.printInfo(JSON.stringify(err)); - this.printInfo("reminderId:" + reminderId); - }); - } - ``` - - HML page code: - - ``` -
- -
- ``` +| Name | Type | Mandatory | Description | +| ------------ | -------------- | --------- | ------------------------------------------------------------ | +| dateTime | LocalDateTime | Yes | Reminder time, accurate to the minute. | +| repeatMonths | Array\ | No | Months in which the reminder repeats. The value range is 1 to 12. | +| repeatDays | Array\ | No | Date on which the reminder repeats. The value range is 1 to 31. | + +**ReminderRequestAlarm** extends **ReminderRequest** and defines a reminder for the alarm clock. + +**Table 9** ReminderRequestAlarm instance + + + +| Name | Type | Mandatory | Description | +| ---------- | -------------- | --------- | ------------------------------------------------------------ | +| hour | number | Yes | Hour portion of the reminder time. The value range is 0 to 23. | +| minute | number | Yes | Minute portion of the reminder time. The value range is 0 to 59. | +| daysOfWeek | Array\ | No | Days of a week when the reminder repeats. The value range is 1 to 7. | + +**ReminderRequestTimer** extends **ReminderRequest** and defines a reminder for a scheduled timer. + +**Table 10** ReminderRequestTimer instance + + + +| Name | Type | Mandatory | Description | +| -------------------- | ------ | --------- | ----------------------------------------- | +| triggerTimeInSeconds | number | Yes | Number of seconds in the countdown timer. | + +**LocalDateTime** defines a **LocalDateTime** instance. + +**Table 11** LocalDateTime instance + + + +| Name | Type | Mandatory | Description | +| ------ | ------ | --------- | ----------- | +| year | number | Yes | Year. | +| month | number | Yes | Month. | +| day | number | Yes | Date. | +| hour | number | Yes | Hour. | +| minute | number | Yes | Minute. | +| second | number | No | Second. | + +## How to Develop + +> **NOTE** +> To publish a reminder, your application needs to apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission. + +Publish a 10-second countdown reminder. + +1. Define a countdown timer instance. + + ``` + import reminderAgent from '@ohos.reminderAgent'; + import notification from '@ohos.notification'; + export default { + // In JS Project: + // timer: { + // In eTS Project: + let timer : reminderAgent.ReminderRequestTimer = { + reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, + triggerTimeInSeconds: 10, + actionButton: [ + { + title: "close", + type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + } + ], + wantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + maxScreenWantAgent: { + pkgName: "com.example.device", + abilityName: "com.example.device.MainAbility" + }, + title: "this is title", + content: "this is content", + expiredContent: "this reminder has expired", + notificationId: 100, + slotType: notification.SlotType.SOCIAL_COMMUNICATION + } + } + ``` + +2. Publish the reminder. + + ``` + startTimer() { + reminderAgent.publishReminder(this.timer, (err, reminderId) =>{ + this.printInfo(JSON.stringify(err)); + this.printInfo("reminderId:" + reminderId); + }); + } + ``` + + HML page code: + + ``` +
+ +
+ ``` Sample code for defining a calendar reminder instance: @@ -689,5 +297,4 @@ let alarm : reminderAgent.ReminderRequestAlarm = { notificationId: 100, slotType: notification.SlotType.SOCIAL_COMMUNICATION } -``` - +``` \ No newline at end of file diff --git a/en/application-dev/reference/apis/js-apis-timer.md b/en/application-dev/reference/apis/js-apis-timer.md index a7265c4972c52318d2f624939e935e56abdb2e63..e85037469d3dd0d931ea7de0a37df77d35880bae 100644 --- a/en/application-dev/reference/apis/js-apis-timer.md +++ b/en/application-dev/reference/apis/js-apis-timer.md @@ -1,261 +1,137 @@ -# Timer +# Timer ->![](../../public_sys-resources/icon-note.gif) **NOTE:** ->The initial APIs of this module are supported since API version 4. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> **NOTE:** The initial APIs of this module are supported since API version 4. Newly added APIs will be marked with a superscript to indicate their earliest API version. -## Module to Import +## Module to Import None -## Required Permissions +## Required Permissions None -## setTimeout +## setTimeout -setTimeout\(handler\[,delay\[, ...args\]\]\): number +setTimeout(handler[,delay[, ...args]]): number Sets a timer for the system to call a function after the timer goes off. -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

handler

-

Function

-

Yes

-

Function to be called after the timer goes off.

-

delay

-

number

-

No

-

Number of milliseconds delayed before the execution. If this parameter is left empty, the default value 0 is used, which means that the execution starts immediately or as soon as possible.

-

...args

-

Array<any>

-

No

-

Additional parameter to pass to the handler after the timer goes off.

-
- -- Return Value - - - - - - - - - - -

Type

-

Description

-

number

-

Timer ID.

-
- -- Example - - ``` - export default { - setTimeOut() { - var timeoutID = setTimeout(function() { - console.log('delay 1s'); - }, 1000); - } - } - ``` - - -## clearTimeout - -clearTimeout\(timeoutID: number\): void - -Cancels the timer created via **setTimeout\(\)**. - -- Parameter - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

timeoutID

-

number

-

Yes

-

ID of the timer to cancel, which is returned by setTimeout()

-
- -- Example - - ``` - export default { - clearTimeOut() { - var timeoutID = setTimeout(function() { - console.log('do after 1s delay.'); - }, 1000); - clearTimeout(timeoutID); - } +- Parameters + + + + | Name | Type | Mandatory | Description | + | ------- | ----------- | --------- | ------------------------------------------------------------ | + | handler | Function | Yes | Function to be called after the timer goes off. | + | delay | number | No | Number of milliseconds delayed before the execution. If this parameter is left empty, the default value **0** is used, which means that the execution starts immediately or as soon as possible. | + | ...args | Array\ | No | Additional parameter to pass to the handler after the timer goes off. | + +- Return Value + + + + | Type | Description | + | ------ | ----------- | + | number | Timer ID. | + +- Example + + ``` + export default { + setTimeOut() { + var timeoutID = setTimeout(function() { + console.log('delay 1s'); + }, 1000); } - ``` + } + ``` +## clearTimeout -## setInterval +clearTimeout(timeoutID: number): void -setInterval\(handler\[, delay\[, ...args\]\]\): number +Cancels the timer created via **setTimeout()**. -Sets a repeating timer for the system to repeatedly call a function at a fixed interval. +- Parameter + + + + | Name | Type | Mandatory | Description | + | --------- | ------ | --------- | ------------------------------------------------------------ | + | timeoutID | number | Yes | ID of the timer to cancel, which is returned by **setTimeout()** | + +- Example -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

handler

-

Function

-

Yes

-

Function to be called repeatedly

-

delay

-

number

-

No

-

Number of milliseconds delayed before the execution

-

...args

-

Array<any>

-

No

-

Additional parameter to pass to the handler after the timer goes off

-
- -- Return Value - - - - - - - - - - -

Type

-

Description

-

number

-

ID of the repeated timer.

-
- -- Example - - ``` - export default { - setInterval() { - var intervalID = setInterval(function() { - console.log('do very 1s.'); - }, 1000); - } + ``` + export default { + clearTimeOut() { + var timeoutID = setTimeout(function() { + console.log('do after 1s delay.'); + }, 1000); + clearTimeout(timeoutID); } - ``` - - -## clearInterval - -clearInterval\(intervalID: number\): void - -Cancels the repeating timer set via **setInterval\(\)**. - -- Parameter - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

intervalID

-

number

-

Yes

-

ID of the repeating timer to cancel, which is returned by setInterval().

-
- -- Example - - ``` - export default { - clearInterval() { - var intervalID = setInterval(function() { - console.log('do very 1s.'); - }, 1000); - clearInterval(intervalID); - } + } + ``` + +## setInterval + +setInterval(handler[, delay[, ...args]]): number + +Sets a repeating timer for the system to repeatedly call a function at a fixed interval. + +- Parameters + + + + | Name | Type | Mandatory | Description | + | ------- | ----------- | --------- | ------------------------------------------------------------ | + | handler | Function | Yes | Function to be called repeatedly | + | delay | number | No | Number of milliseconds delayed before the execution | + | ...args | Array\ | No | Additional parameter to pass to the handler after the timer goes off | + +- Return Value + + + + | Type | Description | + | ------ | ------------------------- | + | number | ID of the repeated timer. | + +- Example + + ``` + export default { + setInterval() { + var intervalID = setInterval(function() { + console.log('do very 1s.'); + }, 1000); } - ``` + } + ``` +## clearInterval +clearInterval(intervalID: number): void + +Cancels the repeating timer set via **setInterval()**. + +- Parameter + + + + | Name | Type | Mandatory | Description | + | ---------- | ------ | --------- | ------------------------------------------------------------ | + | intervalID | number | Yes | ID of the repeating timer to cancel, which is returned by **setInterval()**. | + +- Example + + ``` + export default { + clearInterval() { + var intervalID = setInterval(function() { + console.log('do very 1s.'); + }, 1000); + clearInterval(intervalID); + } + } + ``` \ No newline at end of file