自学记录鸿蒙API 13:Calendar Kit日历功能从学习到实践

这次的目标是学习和使用HarmonyOS的Calendar Kit功能，特别是最新的API 13版本。Calendar Kit让我感受到了一种与传统开发完全不同的体验——它提供的不只是简单的日历功能，而是一套集创建、查询、更新、删除等强大能力于一体的日程管理服务。

一开始，我仅仅是希望开发一个能够管理日常工作和个人事务的小工具。但随着学习的深入，我意识到这个模块的潜力远远超出了我的预期。于是，带着对HarmonyOS的浓厚兴趣，我决定通过实际开发一个完整的日程管理应用，将理论和实践结合起来，全面探索Calendar Kit的功能。

第一部分：构建基础——获取日历管理器

每个优秀的应用都有一个强大的核心，在Calendar Kit中，这个核心就是CalendarManager。它是我们与日历和日程打交道的桥梁。通过它，我们可以完成从创建日历到操作日程的一切功能。

在开始之前，我们需要请求用户权限，因为日历涉及隐私信息，需要
ohos.permission.READ_CALENDAR和ohos.permission.WRITE_CALENDAR权限。

代码实现：初始化CalendarManager

以下是获取CalendarManager对象的代码实现：

import { calendarManager } from '@kit.CalendarKit';
import { Permissions, abilityAccessCtrl, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let calendarMgr: calendarManager.CalendarManager | null = null;
let mContext: common.UIAbilityContext | null = null;

async function initializeCalendarManager() {
    try {
        const permissions = ['ohos.permission.READ_CALENDAR', 'ohos.permission.WRITE_CALENDAR'];
        const atManager = abilityAccessCtrl.createAtManager();
        await atManager.requestPermissionsFromUser(mContext, permissions);
        console.info('权限请求成功');
        calendarMgr = calendarManager.getCalendarManager(mContext);
        console.info('CalendarManager 初始化成功');
    } catch (error) {
        console.error('初始化失败:', error);
    }
}

我的思考

权限请求是开发中的第一步，也是与用户交互的重要环节。通过清晰的提示，让用户理解为何需要这些权限，既能提升用户体验，也有助于合规开发。

第二部分：管理日历——从创建到配置

在获得CalendarManager对象后，我们可以通过它创建和管理多个日历。一个日历是管理日程的容器，因此，为不同的用途创建独立的日历是非常有必要的。

代码实现：创建日历

以下代码展示了如何使用createCalendar方法创建一个日历：

const calendarAccount: calendarManager.CalendarAccount = {
    name: 'MyWorkCalendar',
    type: calendarManager.CalendarType.LOCAL,
    displayName: '工作日历'
};

async function createCalendar() {
    try {
        const calendar = await calendarMgr?.createCalendar(calendarAccount);
        console.info(`日历创建成功: ${JSON.stringify(calendar)}`);
        return calendar;
    } catch (error) {
        console.error('创建日历失败:', error);
    }
}

配置日历

创建日历后，我们可以通过setConfig方法为其添加配置，例如是否启用提醒、设置颜色等：

const calendarConfig: calendarManager.CalendarConfig = {
    enableReminder: true,
    color: '#FF5733'
};

async function configureCalendar(calendar: calendarManager.Calendar) {
    try {
        await calendar.setConfig(calendarConfig);
        console.info('日历配置成功');
    } catch (error) {
        console.error('配置日历失败:', error);
    }
}

我的思考

我特别喜欢通过颜色区分不同的日历类型。比如，为工作日历设置红色，为个人日历设置蓝色，这种视觉化的管理方式让信息一目了然。

第三部分：日程管理——让生活井井有条

有了日历后，我们可以通过它添加日程。addEvent方法让我们能够轻松地创建一个事件，并为其添加标题、时间、描述等信息。

代码实现：添加日程

以下代码展示了如何向日历中添加一个会议事件：

const event: calendarManager.Event = {
    title: '团队会议',
    type: calendarManager.EventType.NORMAL,
    startTime: Date.now() + 60 * 60 * 1000, // 1小时后
    endTime: Date.now() + 2 * 60 * 60 * 1000, // 2小时后
    location: { location: '会议室1', latitude: 0, longitude: 0 },
    description: '讨论项目进展',
    reminderTime: [10] // 提前10分钟提醒
};

async function addEvent(calendar: calendarManager.Calendar) {
    try {
        const eventId = await calendar.addEvent(event);
        console.info(`日程添加成功，ID: ${eventId}`);
    } catch (error) {
        console.error('添加日程失败:', error);
    }
}

第四部分：查询与筛选——精准管理日程

当日程变得越来越多时，查询和筛选就显得尤为重要。Calendar Kit 提供了丰富的查询功能，比如通过标题、时间或ID来筛选事件。

代码实现：按标题查询

以下代码展示了如何通过标题模糊查询日程：

async function getEventsByTitle(calendar: calendarManager.Calendar, title: string) {
    try {
        const filter = calendarManager.EventFilter.filterByTitle(title);
        const events = await calendar.getEvents(filter);
        console.info(`查询到的日程: ${JSON.stringify(events)}`);
    } catch (error) {
        console.error('查询日程失败:', error);
    }
}

我的思考

模糊查询非常适合快速定位某类任务。例如，搜索“会议”可以找到所有与会议相关的日程，这在实际应用中极具实用价值。

第五部分：实战项目——智能日程管理工具

基于以上功能，我开发了一个智能日程管理应用。用户可以通过简洁的界面添加、查看和管理日程。

功能展示：创建新日程的UI组件

@Entry
@Component
struct CreateEventPage {
    @State title: string = '';
    @State description: string = '';
    @State startTime: string = '';
    @State endTime: string = '';

    build() {
        Column() {
            TextField({ text: this.title, placeholder: '请输入标题' })
                .onChange((value: string) => this.title = value);

            TextField({ text: this.description, placeholder: '请输入描述' })
                .onChange((value: string) => this.description = value);

            TextField({ text: this.startTime, placeholder: '开始时间 (YYYY-MM-DD HH:MM)' })
                .onChange((value: string) => this.startTime = value);

            TextField({ text: this.endTime, placeholder: '结束时间 (YYYY-MM-DD HH:MM)' })
                .onChange((value: string) => this.endTime = value);

            Button('创建日程')
                .onClick(async () => {
                    await addEvent({
                        title: this.title,
                        description: this.description,
                        startTime: new Date(this.startTime).getTime(),
                        endTime: new Date(this.endTime).getTime()
                    });
                });
        }
    }
}