1# 日程管理
2
3日程指特定的事件或者活动安排，日程管理即对这些事件、活动进行规划和控制，能更有效地利用相关资源、提高生产力和效率，使人们更好地管理时间和任务。
4
5Calendar Kit中的日程[Event](../reference/apis-calendar-kit/js-apis-calendarManager.md#event)归属于某个对应的日历账户[Calendar](../reference/apis-calendar-kit/js-apis-calendarManager.md#calendar)，一个日历账户下可以有多个日程，一个日程只属于一个Calendar。
6
7获取到日历账户对象之后，即可对该账户下的日程进行管理，包括日程的创建、删除、修改、查询等操作。在创建、修改日程时，支持对日程的标题、开始时间、结束时间、日程类型、日程地点、日程提醒时间、日程重复规则等相关信息进行设置，以便进行更丰富更有效的日程管理。
8
9## 接口说明
10
11以下是日程管理的相关接口，更多详细接口及使用请参考[@ohos.calendarManager](../reference/apis-calendar-kit/js-apis-calendarManager.md)。
12
13| 接口名称                                                     | 描述                                                         |
14| ------------------------------------------------------------ | ------------------------------------------------------------ |
15| getCalendarManager(context : Context): CalendarManager       | 根据上下文获取CalendarManager对象，用于管理日历。            |
16| createCalendar(calendarAccount: CalendarAccount): Promise\<Calendar> | 根据日历账户信息，创建一个Calendar对象，使用Promise异步回调。 |
17| addEvent(event: Event): Promise\<number>                     | 创建日程，入参Event不填日程id，使用Promise异步回调。         |
18| editEvent(event: Event): Promise\<number>                    | 创建单个日程，入参Event不填日程id，调用该接口会跳转到日程创建页面，使用Promise异步回调。 |
19| deleteEvent(id: number): Promise\<void>                      | 删除指定日程id的日程，使用Promise异步回调。                  |
20| updateEvent(event: Event): Promise\<void>                    | 更新日程，使用Promise异步回调。                              |
21| getEvents(eventFilter?: EventFilter, eventKey?: (keyof Event)[]): Promise\<Event[]> | 获取Calendar下符合查询条件的Event，使用Promise异步回调。     |
22
23## 开发步骤
24
251. 导入相关依赖。
26
27   ```ts
28   // entry/src/main/ets/entryability/EntryAbility.ets
29   import {abilityAccessCtrl,AbilityConstant, common, PermissionRequestResult, Permissions, UIAbility, Want } from '@kit.AbilityKit';
30   import { BusinessError } from '@kit.BasicServicesKit';
31   import { calendarManager } from '@kit.CalendarKit';
32   import { window } from '@kit.ArkUI';
33   ```
34
352. 申请权限。使用Calendar Kit时，需要在module.json5中声明申请读写日历日程所需的权限：`ohos.permission.READ_CALENDAR`和`ohos.permission.WRITE_CALENDAR`。具体指导可见[声明权限](../security/AccessToken/declare-permissions.md)。
36
373. 根据上下文获取日程管理器对象calendarMgr，用于对日历账户进行相关管理操作。推荐在`EntryAbility.ets`文件中进行操作。
38
39   ```ts
40   // entry/src/main/ets/entryability/EntryAbility.ets
41   export let calendarMgr: calendarManager.CalendarManager | null = null;
42
43   export let mContext: common.UIAbilityContext | null = null;
44
45   export default class EntryAbility extends UIAbility {
46     onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
47       console.info("Ability onCreate");
48     }
49
50     onDestroy(): void {
51       console.info("Ability onDestroy");
52     }
53
54     onWindowStageCreate(windowStage: window.WindowStage): void {
55       // Main window is created, set main page for this ability
56       console.info("Ability onWindowStageCreate");
57       windowStage.loadContent('pages/Index', (err, data) => {
58         if (err.code) {
59           console.error(`Failed to load the content. Code: ${err.code}, message: ${err.message}`);
60           return;
61         }
62         console.info(`Succeeded in loading the content. Data: ${JSON.stringify(data)}`);
63       });
64       mContext = this.context;
65       const permissions: Permissions[] = ['ohos.permission.READ_CALENDAR', 'ohos.permission.WRITE_CALENDAR'];
66       let atManager = abilityAccessCtrl.createAtManager();
67       atManager.requestPermissionsFromUser(mContext, permissions).then((result: PermissionRequestResult) => {
68         console.log(`get Permission success, result: ${JSON.stringify(result)}`);
69         calendarMgr = calendarManager.getCalendarManager(mContext);
70       }).catch((error: BusinessError) => {
71         console.error(`get Permission error, error. Code: ${error.code}, message: ${error.message}`);
72       })
73     }
74
75     onWindowStageDestroy(): void {
76       // Main window is destroyed, release UI related resources
77       console.info("Ability onWindowStageDestroy");
78     }
79
80     onForeground(): void {
81       // Ability has brought to foreground
82       console.info("Ability onForeground");
83     }
84
85     onBackground(): void {
86       // Ability has back to background
87       console.info("Ability onBackground");
88     }
89   }
90   ```
91
924. 根据日历账户信息创建Calendar对象，用于进行日程管理。设置日历配置信息，可以根据需要打开日程提醒、设置日历账户颜色。
93
94   ```ts
95   // Index.ets
96   import { BusinessError } from '@kit.BasicServicesKit';
97   import { calendarMgr } from '../entryability/EntryAbility';
98   import { calendarManager } from '@kit.CalendarKit';
99
100   let calendar: calendarManager.Calendar | undefined = undefined;
101   // 指定日历账户信息
102   const calendarAccount: calendarManager.CalendarAccount = {
103     name: 'MyCalendar',
104     type: calendarManager.CalendarType.LOCAL,
105     // 日历账户显示名称，该字段如果不填，创建的日历账户在界面显示为空字符串。
106     displayName: 'MyCalendar'
107   };
108   // 日历配置信息
109   const config: calendarManager.CalendarConfig = {
110     // 打开日程提醒
111     enableReminder: true,
112     // 设置日历账户颜色
113     color: '#aabbcc'
114   };
115   // 创建日历账户
116   calendarMgr?.createCalendar(calendarAccount).then((data: calendarManager.Calendar) => {
117     console.info(`Succeeded in creating calendar data->${JSON.stringify(data)}`);
118     calendar = data;
119     // 请确保日历账户创建成功后，再进行相关日程的管理
120
121     // 设置日历配置信息，打开日程提醒、设置日历账户颜色
122     calendar.setConfig(config).then(() => {
123       console.info(`Succeeded in setting config, data->${JSON.stringify(config)}`);
124     }).catch((err: BusinessError) => {
125       console.error(`Failed to set config. Code: ${err.code}, message: ${err.message}`);
126     });
127     // ...
128   }).catch((error: BusinessError) => {
129     console.error(`Failed to create calendar. Code: ${error.code}, message: ${error.message}`);
130   });
131   ```
132
1335. 在当前日历账户下添加日历日程，注意入参中不需要填写日程id。
134
135   创建日程时，支持设置日程的标题、开始时间、结束时间、日程类型、日程地点、日程提醒时间、日程重复规则等相关信息。
136
137   日程创建成功后会返回一个日程id，作为日程的唯一标识，后续可按照日程id进行指定日程的更新或删除。
138
139   目前支持以下两种方式来创建日程。
140
141   方式一：可以在日历账户下通过`addEvent()`或`addEvents()`接口创建日程。其中可使用`addEvent()`接口创建单个日程，也可以使用`addEvents()`接口批量创建日程，此处以创建单个日程为例。
142
143   方式二：在获取到日历管理器对象后，可通过`editEvent()`接口创建单个日程。调用此接口创建日程时，会跳转到日程创建页面，在日程创建页面进行相关操作完成日程的创建, `editEvent()`不支持自定义周期性日程创建。
144
145   ```ts
146   // Index.ets
147   let eventId : number | undefined = undefined;
148   const date = new Date();
149   const event: calendarManager.Event = {
150     // 日程标题
151     title: 'title',
152     // 日程类型，不推荐三方开发者使用calendarManager.EventType.IMPORTANT，重要日程类型不支持一键服务跳转功能及无法自定义提醒时间
153     type: calendarManager.EventType.NORMAL,
154     // 日程开始时间
155     startTime: date.getTime(),
156     // 日程结束时间
157     endTime: date.getTime() + 60 * 60 * 1000,
158     // 距开始时间提前10分钟提醒
159     reminderTime: [10],
160     // 日程重复规则，可选属性。如果日程为周期性日程需要填写该属性。
161     recurrenceRule: {
162       // 日程重复规则类型，支持按天、按周、按月、按年重复
163       recurrenceFrequency: calendarManager.RecurrenceFrequency.DAILY,
164       // 日程重复次数，该字段和expire属性只需要填写一个，如果两个都填写按照count属性计算。
165       count: 100,
166       // 重复日程间隔时间，与recurrenceFrequency相关，此示例表示日程每隔2天进行重复。
167       interval: 2,
168       // 日程过期时间，该字段和count属性只需要填写一个，如果两个都填写按照count属性计算。
169       expire: date.getTime() + 60 * 60 * 1000 * 3,
170       // 日程排除日期，将该日期从重复日程中排除掉
171       excludedDates: [date.getTime() + 60 * 60 * 1000 * 2]
172     },
173     // 日程服务，可选字段，需要一键服务功能的日程，填写该属性。
174     service: {
175       // 服务类型，比如一键查看、一键入会、一键追剧等。
176       type: calendarManager.ServiceType.TRIP,
177       // 服务的uri。可以跳转到三方应用相应界面，格式为deeplink。使用deeplink方式需要在华为HAG云侧进行注册，注册提供的信息为应用包名、应用的服务类型。
178       // deeplink包括scheme、host、path以及参数（不包含参数值）
179       uri: 'xxx://xxx.xxx.com/xxx',
180       // 服务辅助描述信息，可选字段
181       description: '一键服务'
182     }
183
184   };
185   // 方式一
186   calendar.addEvent(event).then((data: number) => {
187     console.info(`Succeeded in adding event, id -> ${data}`);
188     eventId = data;
189   }).catch((err: BusinessError) => {
190     console.error(`Failed to addEvent. Code: ${err.code}, message: ${err.message}`);
191   });
192   // 方式二
193    const eventInfo: calendarManager.Event = {
194     // 日程标题
195     title: 'title',
196     // 日程类型
197     type: calendarManager.EventType.NORMAL,
198     // 日程开始时间
199     startTime: date.getTime(),
200     // 日程结束时间
201     endTime: date.getTime() + 60 * 60 * 1000
202   };
203   calendarMgr?.editEvent(eventInfo).then((id: number): void => {
204     console.info(`create Event id = ${id}`);
205     eventId = id;
206   }).catch((err: BusinessError) => {
207     console.error(`Failed to create Event. Code: ${err.code}, message: ${err.message}`);
208   });
209   ```
210
2116. 按照日程id进行指定日程的更新，更新日程相关信息。
212
213   ```ts
214   // Index.ets
215   const updateEvent: calendarManager.Event = {
216     title: 'updateTitle',
217     description: 'updateEventTest',
218     type: calendarManager.EventType.NORMAL,
219     id: eventId,
220     startTime: date.getTime(),
221     endTime: date.getTime() + 60 * 60 * 1000
222   };
223   calendar.updateEvent(updateEvent).then(() => {
224     console.info(`Succeeded in updating event`);
225   }).catch((err: BusinessError) => {
226     console.error(`Failed to update event. Code: ${err.code}, message: ${err.message}`);
227   });
228   ```
229
2307. 查询当前日历账户下的所有日程。由于涉及数据隐私安全，进行了权限管控的应用无法获取其他创建的日程信息。根据不同的查询条件和查询字段，返回不同的查询结果。
231
232   当没有查询条件和查询字段时，可查询指定日历账户下的所有日程。
233   ```ts
234   calendar.getEvents().then((data: calendarManager.Event[]) => {
235     console.info(`Succeeded in getting events, data -> ${JSON.stringify(data)}`);
236   }).catch((err: BusinessError) => {
237     console.error(`Failed to get events. Code: ${err.code}, message: ${err.message}`);
238   });
239   ```
240
241   还支持根据日程id、日程开始和结束时间、日程标题等查询条件来查询日程。
242   ```ts
243   // 根据日程id查询
244   const filterId = calendarManager.EventFilter.filterById([eventId]);
245   calendar.getEvents(filterId).then((data: calendarManager.Event[]) => {
246     console.info(`Succeeded in getting events, data -> ${JSON.stringify(data)}`);
247   }).catch((err: BusinessError) => {
248     console.error(`Failed to get events. Code: ${err.code}, message: ${err.message}`);
249   });
250
251   // 根据日程标题查询
252   const filterTitle = calendarManager.EventFilter.filterByTitle('update');
253   calendar.getEvents(filterTitle).then((data: calendarManager.Event[]) => {
254     console.info(`Succeeded in getting events, data -> ${JSON.stringify(data)}`);
255   }).catch((err: BusinessError) => {
256     console.error(`Failed to get events. Code: ${err.code}, message: ${err.message}`);
257   });
258
259   // 根据日程开始和结束时间查询
260   const filterTime = calendarManager.EventFilter.filterByTime(1686931200000, 1687017600000);
261   calendar.getEvents(filterTime).then((data: calendarManager.Event[]) => {
262     console.info(`Succeeded in getting events filter by time, data -> ${JSON.stringify(data)}`);
263   }).catch((err: BusinessError) => {
264     console.error(`Failed to filter by time. Code: ${err.code}, message: ${err.message}`);
265   });
266   ```
267
2688. 按照日程id进行指定日程的删除。可以通过`deleteEvent()`接口进行单个日程的删除，也可以通过`deleteEvents()`接口批量删除指定日程，此处以删除单个指定日程为例。
269
270   ```ts
271   // Index.ets
272   calendar.deleteEvent(eventId).then(() => {
273      console.info("Succeeded in deleting event");
274    }).catch((err: BusinessError) => {
275      console.error(`Failed to delete event. Code: ${err.code}, message: ${err.message}`);
276   });
277   ```
278