日历账户管理
日历账户用于存储和管理个人或团队的日程,通过日历账户,用户可以方便地查看、编辑和共享日程信息。
日历管理器CalendarManager用于管理日历账户Calendar。日历账户主要包含账户信息CalendarAccount和配置信息CalendarConfig。
开发者可以创建属于应用特有的日历账户,还可以对日历账户进行新增、删除、更新和查询。此外,每个日程Event归属于某一个特定的日历账户,可以通过日历账户对该账户下面的日程进行管理,具体相关指导可见日程管理。
接口说明
以下是日历账户管理的相关接口,更多详细接口及使用请参考@ohos.calendarManager。
| 接口名称 | 描述 |
|---|---|
| getCalendarManager(context: Context): CalendarManager | 根据上下文获取日历管理器对象CalendarManager,用于管理日历。 |
| createCalendar(calendarAccount: CalendarAccount): Promise<Calendar> | 根据日历账户信息,创建一个Calendar对象,使用Promise异步回调。 |
| getCalendar(calendarAccount?: CalendarAccount): Promise<Calendar> | 获取默认Calendar对象或者指定Calendar对象,使用Promise异步回调。 默认Calendar是日历存储首次运行时创建的,若创建Event时不关注其Calendar归属,则无须通过createCalendar()创建Calendar,直接使用默认Calendar。 |
| getAllCalendars(): Promise<Calendar[]> | 获取当前应用所有创建的Calendar对象以及默认Calendar对象,使用Promise异步回调。 |
| deleteCalendar(calendar: Calendar): Promise<void> | 删除指定Calendar对象,使用Promise异步回调。 |
| getConfig(): CalendarConfig | 获取日历配置信息。 |
| setConfig(config: CalendarConfig): Promise<void> | 设置日历配置信息,使用Promise异步回调。 |
| getAccount(): CalendarAccount | 获取日历账户信息。 |
开发步骤
-
导入相关依赖。
-
申请权限。使用Calendar Kit时,需要在module.json5中声明申请读写日历日程所需的权限:
ohos.permission.READ_CALENDAR和ohos.permission.WRITE_CALENDAR。具体指导可见声明权限。 -
根据上下文获取日程管理器对象calendarMgr,用于对日历账户进行相关管理操作。推荐在
EntryAbility.ets文件中进行操作。const DOMAIN = 0x0000; onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate'); } onDestroy(): void { hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy'); } onWindowStageCreate(windowStage: window.WindowStage): void { // 主窗口已创建,请为此Ability设置主页 hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); windowStage.loadContent('pages/Index', (err, data) => { if (err.code) { hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err)); return; } hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.'); }); mContext = this.context; const permissions: Permissions[] = ['ohos.permission.READ_CALENDAR', 'ohos.permission.WRITE_CALENDAR']; let atManager = abilityAccessCtrl.createAtManager(); atManager.requestPermissionsFromUser(mContext, permissions).then((result: PermissionRequestResult) => { hilog.info(DOMAIN, 'testTag', 'get Permission success'); calendarMgr = calendarManager.getCalendarManager(mContext); }).catch((error: BusinessError) => { hilog.error(DOMAIN, 'testTag', 'get Permission error, Cause: %{public}s', JSON.stringify(error)); }) } onWindowStageDestroy(): void { // 主窗口已销毁,释放 UI 相关资源 hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); } onForeground(): void { // Ability 进入前台 hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground'); } onBackground(): void { // Ability 进入后台 hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground'); } } -
根据日历账户信息,创建一个日历账户Calendar对象。
创建日历账户之前,开发者需要先根据账户信息进行查询,如果账户不存在则抛出异常信息,捕获到异常再进行日历账户的创建,否则可能会出现账户重复创建的问题。
const DOMAIN = 0x0000; let calendar: calendarManager.Calendar | undefined = undefined; // 指定日历账户信息 const calendarAccount: calendarManager.CalendarAccount = { // 日历账户名称 name: 'MyCalendar', // 日历账户类型 type: calendarManager.CalendarType.LOCAL, // 日历账户显示名称,该字段如果不填,创建的日历账户在界面显示为空字符串。 displayName: 'MyCalendar' };// 创建日历账户 calendarMgr?.createCalendar(calendarAccount).then((data: calendarManager.Calendar) => { hilog.info(DOMAIN, 'testTag', '%{public}s', `Succeeded in creating calendar data->${JSON.stringify(data)}`); calendar = data; // 请确保日历账户创建成功后,再进行后续相关操作 // ... }).catch((error: BusinessError) => { hilog.error(DOMAIN, 'testTag', `Failed to create calendar. Code: ${error.code}, message: ${error.message}`); }); -
日历账户创建之后,日历账户颜色默认为黑色,不指定日历账户颜色可能导致部分版本/设备深色模式下显示效果不佳。开发者需要调用setConfig()接口设置日历配置信息,包括是否打开日历账户下的日程提醒能力、设置日历账户颜色。
const calendarAccounts: calendarManager.CalendarAccount = { name: 'MyCalendar', type: calendarManager.CalendarType.LOCAL, displayName: 'MyCalendar' }; // 日历配置信息 calendarMgr?.getCalendar(calendarAccounts, (err, data) => { // 获取日历账户 if (err) { hilog.error(DOMAIN, 'testTag', `Failed to get calendar, Code is ${err.code}, message is ${err.message}`); } else { const config: calendarManager.CalendarConfig = { // 打开日程提醒 enableReminder: true, // 设置日历账户颜色 color: '#aabbcc' }; // 设置日历配置信息 data.setConfig(config).then(() => { hilog.info(DOMAIN, 'testTag', '%{public}s', `Succeeded in setting config, data->${JSON.stringify(config)}`); }).catch((err: BusinessError) => { hilog.error(DOMAIN, 'testTag', `Failed to set config. Code: ${err.code}, message: ${err.message}`); }) } }); -
可以查询指定日历账户。
calendarMgr?.getCalendar(calendarAccount).then((data: calendarManager.Calendar) => { hilog.info(DOMAIN, 'testTag', '%{public}s', `Succeeded in getting calendar, data -> ${JSON.stringify(data)}`); }).catch((err: BusinessError) => { hilog.error(DOMAIN, 'testTag', `Failed to get calendar. Code: ${err.code}, message: ${err.message}`); }); -
也可以查询默认日历账户,默认日历账户是日历存储首次运行时创建的,若创建日程时不关注归属哪个账户,则无须单独创建日历账户,可以直接使用默认日历账户。
calendarMgr?.getCalendar().then((data: calendarManager.Calendar) => { hilog.info(DOMAIN, 'testTag', '%{public}s', `Succeeded in getting calendar, data -> ${JSON.stringify(data)}`); }).catch((err: BusinessError) => { hilog.error(DOMAIN, 'testTag', `Failed to get calendar. Code: ${err.code}, message: ${err.message}`); }); -
获取当前应用所有创建的日历账户及默认日历账户Calendar对象。
由于涉及数据隐私安全,进行了权限管控的应用无法获取其他应用创建的账户信息。
calendarMgr?.getAllCalendars().then((data: calendarManager.Calendar[]) => { hilog.info(DOMAIN, 'testTag', '%{public}s', `Succeeded in getting all calendars, data -> ${JSON.stringify(data)}`); data.forEach((calendar) => { const account = calendar.getAccount(); hilog.info(DOMAIN, 'testTag', '%{public}s', `account -> ${JSON.stringify(account)}`); }) }).catch((err: BusinessError) => { hilog.error(DOMAIN, 'testTag', `Failed to get all calendars. Code: ${err.code}, message: ${err.message}`); }); -
删除指定的日历账户,删除账户后,该账户下的所有日程会全部删除。
if (!calendar || calendar === null) { hilog.error(DOMAIN, 'testTag', 'Failed to delete calendar. calendar is null'); return; } calendarMgr?.deleteCalendar(calendar).then(() => { hilog.info(DOMAIN, 'testTag', '%{public}s', 'Succeeded in deleting calendar'); }).catch((err: BusinessError) => { hilog.error(DOMAIN, 'testTag', `Failed to delete calendar. Code: ${err.code}, message: ${err.message}`); });
本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
