很多应用都会产生带时间属性的事件——买了张火车票、预约了一场直播、信用卡该还款了、晚上有节线上课。这些信息散落在各个应用里，用户需要自己记住或者手动添加提醒，难免遗漏。

鸿蒙的 Calendar Kit 提供了一种更好的方式：让应用直接把这些事件写入系统日历。写入后，日程会通过通知中心、桌面卡片、日历应用等多个入口触达用户，还能配上一个**”一键服务”按钮**，用户点一下就能跳回应用完成操作——比如”加入会议”、”马上还款”、”立即观看”。

本文面向希望接入日历服务的鸿蒙开发者，梳理日历日程的创建机制、一键服务的场景设计，并通过两个典型场景的完整实现，帮你快速理解开发要点。

一、日历服务能做什么

1.1 核心能力

简单说就是三件事：

1. 写入日程：把应用中带时间属性的事件以标准格式写入系统日历，包括标题、时间、地点、备注等信息。
2. 提醒用户：通过系统级的提醒机制，在日程开始前的指定时间通知用户。
3. 一键直达：在日程卡片上提供服务按钮，用户点击后通过 DeepLink 跳回应用的对应页面，完成后续操作。

写入日历的日程会出现在多个地方——日历应用内部、桌面日历卡片、通知中心。用户不需要打开你的应用就能看到这些信息，这对提升事件的到达率很有帮助。

1.2 一键服务按钮的显示时机

一键服务按钮不是一直显示的，不同入口的出现时机不一样：

这意味着一键服务按钮是有”时效性”的——它在用户最需要行动的时间窗口出现，而不是一直挂在那里。

1.3 9 种典型服务场景

Calendar Kit 为不同的业务场景预定义了服务类型，每种类型对应一个具体的按钮文案：

选择合适的服务类型，按钮文案就会自动匹配，不需要开发者自定义。

二、开发前的准备工作

在写第一行业务代码之前，有三步准备工作需要完成：

第一步，导入依赖。日历管理相关的能力都在 @kit.CalendarKit 中。

第二步，申请权限。日历是用户的私有数据，读写操作需要在 module.json5 中声明两个权限：ohos.permission.READ_CALENDAR 和 ohos.permission.WRITE_CALENDAR。

第三步，获取日程管理器对象。通过上下文获取 calendarMgr 对象，后续所有日历账户和日程的管理操作都通过它来进行。推荐在 EntryAbility.ets 中完成这一步，确保管理器对象在应用生命周期内可用。

三、理解日程的数据结构

在看具体场景之前，先理解日程涉及的几个关键概念，后面写代码时会更清楚为什么要这样配置。

3.1 日历账户

每个写入系统日历的日程都归属于一个日历账户。你可以理解为日历中的一个”分组”——用户打开日历应用时，能看到来自不同应用的日程被归类在各自的账户下。

账户有三个关键属性：

• name：账户标识，供系统内部使用。
• type：账户类型，一般使用 LOCAL。
• displayName：展示给用户看的名称，建议和应用在应用市场中的名称保持一致，方便用户识别”这个日程是哪个应用写的”。

3.2 日程字段

一条日程的核心字段包括：

• title：标题，出现在日程卡片上最醒目的位置。
• startTime / endTime：起止时间，时间戳格式。
• isAllDay：是否是全天日程。全天日程不会显示具体时刻，适合”入住日””还款日”这类以天为单位的事件。
• reminderTime：提醒时间，是一个数组，单位是分钟。比如 [0, 10] 表示日程开始时和开始前 10 分钟各提醒一次。对于全天日程，0 表示当天上午 9 点提醒，1440（即 24 小时）表示前一天上午 9 点提醒。
• description：备注信息，可以补充标题里放不下的细节。
• location：地点信息，包含地址文本和经纬度。
• service：一键服务配置，包括服务类型（type）和跳转链接（uri，DeepLink 格式）。

3.3 日程的增删改查

日历服务提供了完整的 CRUD 操作。创建日历账户后，可以在该账户下添加日程、按条件查询日程、更新日程信息、删除日程。后面的场景示例中会展示这些操作的具体写法。

四、典型场景实践

下面通过两个最常见的场景——出行服务和会议——来完整走一遍开发流程。其他场景（直播、购物、还款、课程等）的开发思路完全一致，区别只在于字段内容和 ServiceType 的选择。

4.1 出行服务场景

这大概是最容易理解的场景了：用户在购票应用里买了一张高铁票，应用把行程信息写入日历，出发前提醒用户，用户还能一键跳回应用查看电子客票。

字段设计思路：

标题要一目了然，建议包含车次和起终点，比如”行程信息：G107 上海虹桥-北京南”。备注里可以放检票口和座位号这类到了车站才需要的细节。提醒时间设两个——4 小时前提醒用户该出门了，2 小时前再提醒一次。一键服务类型选 TRIP。

创建日程：

import { calendarMgr } from '../entryability/EntryAbility';
import { calendarManager } from '@kit.CalendarKit';

let tripCalendar: calendarManager.Calendar | undefined = undefined;
let oriEvent: calendarManager.Event | null = null;
let id: number = 0;

async createTripCalendarAndEvent(): Promise<void> {
  const calendarAccount: calendarManager.CalendarAccount = {
    name: 'TripCalendar',
    type: calendarManager.CalendarType.LOCAL,
    displayName: '高铁出行'
  };

  const config: calendarManager.CalendarConfig = {
    color: '#aabbcc'
  };

  const startTime = new Date('2025-10-01T08:17:00').getTime();
  const endTime = new Date('2025-10-01T12:51:00').getTime();

  const event: calendarManager.Event = {
    type: calendarManager.EventType.NORMAL,
    title: '行程信息：G107 上海虹桥-北京南',
    startTime: startTime,
    endTime: endTime,
    isAllDay: false,
    reminderTime: [120, 240],
    description: '检票口：南二楼1口或北广场B2候车室 \n座位号：02车04二等座',
    service: {
      type: calendarManager.ServiceType.TRIP,
      uri: 'demo://mobile/player?params='
    }
  };

  try {
    tripCalendar = await calendarMgr?.createCalendar(calendarAccount);
    if (!tripCalendar) {
      console.error('Failed to create calendar.');
      return;
    }
    await tripCalendar.setConfig(config);
    id = await tripCalendar.addEvent(event);
    oriEvent = event;
    oriEvent.id = id;
    console.info(`日程创建成功，ID: ${id}`);
  } catch (error) {
    console.error(`创建失败: ${error.code}, ${error.message}`);
  }
}

这段代码做了三件事：创建日历账户、设置账户配色、添加日程。注意一定要确保日历账户创建成功后再进行日程操作，否则后续调用会失败。

日程的后续管理：

出行场景下，行程变更是常有的事——改签了车次、换了出发时间。这时候需要更新已有日程而不是删掉重建：

async updateTripEvent(): Promise<void> {
  if (!tripCalendar || !oriEvent) return;
  
  // 改签后更新起止时间
  oriEvent.startTime = new Date('2025-10-01T07:03:00').getTime();
  oriEvent.endTime = new Date('2025-10-01T11:51:00').getTime();

  try {
    await tripCalendar.updateEvent(oriEvent);
    console.info('日程更新成功');
  } catch (err) {
    console.error(`更新失败: ${err.code}, ${err.message}`);
  }
}

如果用户退票了，则直接删除日程：

async deleteTripEvent(): Promise<void> {
  if (!tripCalendar) return;
  try {
    await tripCalendar.deleteEvent(id);
    oriEvent = null;
    console.info('日程已删除');
  } catch (err) {
    console.error(`删除失败: ${err.code}, ${err.message}`);
  }
}

需要查询已有日程时，通过 EventFilter.filterById 按 ID 查询：

async getTripEvent(): Promise<void> {
  if (!tripCalendar) return;
  try {
    const filter = calendarManager.EventFilter.filterById([id]);
    let data = await tripCalendar.getEvents(filter, 
      ['title', 'type', 'startTime', 'endTime']);
    if (data && data.length > 0) {
      oriEvent = data[0];
    }
  } catch (err) {
    console.error(`查询失败: ${err.code}, ${err.message}`);
  }
}

4.2 会议场景

会议场景和出行的最大区别在于：它有与会人信息。用户在会议应用中创建或被邀请参加一个会议，应用将其写入日历，到时间时用户看到提醒，点击”加入会议”按钮就能直接进入会议。

字段设计思路：

标题就是会议主题。提醒时间设准时和 15 分钟前——太早没意义，太晚来不及。会议场景特有的是 attendee 字段，用来记录与会人信息，每个与会人有姓名、邮箱、角色（组织者还是参与者）和类型（必选还是可选）。

async createMeetingEvent(): Promise<void> {
  const calendarAccount: calendarManager.CalendarAccount = {
    name: 'meetingCalendar',
    type: calendarManager.CalendarType.LOCAL,
    displayName: '会议'
  };

  const config: calendarManager.CalendarConfig = {
    color: '#aabbcc'
  };

  let attendee: calendarManager.Attendee[] = [
    {
      name: 'Alice',
      email: 'alice@example.com',
      role: calendarManager.AttendeeRole.ORGANIZER
    },
    {
      name: 'Jack',
      email: 'jack@example.com',
      role: calendarManager.AttendeeRole.PARTICIPANT,
      type: calendarManager.AttendeeType.REQUIRED
    },
    {
      name: 'Jerry',
      email: 'jerry@example.com',
      role: calendarManager.AttendeeRole.PARTICIPANT,
      type: calendarManager.AttendeeType.REQUIRED
    }
  ];

  const startTime = new Date('2025-10-20T09:00:00').getTime();
  const endTime = new Date('2025-10-20T10:00:00').getTime();

  const event: calendarManager.Event = {
    type: calendarManager.EventType.NORMAL,
    title: '产品方案评审会议',
    startTime: startTime,
    endTime: endTime,
    isAllDay: false,
    reminderTime: [0, 15],
    attendee: attendee,
    description: 'Q4产品方案评审',
    service: {
      type: calendarManager.ServiceType.MEETING,
      uri: 'demo://mobile/player?params='
    }
  };

  try {
    let calendar = await calendarMgr?.createCalendar(calendarAccount);
    if (!calendar) return;
    await calendar.setConfig(config);
    id = await calendar.addEvent(event);
    console.info(`会议日程创建成功，ID: ${id}`);
  } catch (error) {
    console.error(`创建失败: ${error.code}, ${error.message}`);
  }
}

与会人信息会展示在日程详情中，帮助用户确认参会人员。对于会议应用来说，service.uri 中的 DeepLink 通常会携带会议室 ID 等参数，用户点击”加入会议”后直接进入对应的会议房间。

五、其他场景速览

前面详细讲了出行和会议两个场景的完整实现，其他场景的代码结构完全一样，差异只在字段内容的填写上。这里简要列出几个场景的要点，帮你快速对照：

酒店住宿：适合设置为全天日程（isAllDay: true），标题包含酒店名称和地址，别忘了填 location 字段（包含经纬度），ServiceType 用 TRIP。提醒建议设前一天上午 9 点（reminderTime: [1440]）和当天上午 9 点（reminderTime: [0]）。

还款提醒：也是全天日程，毕竟还款日是以”天”为单位的。备注里写上待还款金额，ServiceType 用 REPAYMENT，提醒一次就够了——当天上午 9 点（reminderTime: [0]）。

直播 / 抢购 / 课程 / 赛事 / 运动：都是精确到具体时刻的非全天日程，提醒时间一般设准时和开始前 10-30 分钟。区别就是选对 ServiceType，按钮文案就会自动匹配。

六、总结与实践建议

日历服务的接入逻辑并不复杂——创建账户、配置日程、写入系统。但要把体验做好，有几个细节值得注意：

1. 标题要有信息量。用户在桌面卡片上看到的可能只有标题，所以”G107 上海虹桥-北京南”远比”火车票行程”有用。
2. 提醒时间要合理。出行类提前 2-4 小时，会议和课程提前 10-15 分钟，全天日程用上午 9 点。不要设过多提醒，免得用户觉得被打扰。
3. 及时更新和清理。行程改签了就更新日程，退票了就删除。不要让过期或无效的日程留在用户的日历里，这会损害用户对应用的信任。
4. displayName 要用应用真名。用户看到一条日程时，会通过日历账户名称判断”这是哪个应用写的”。用正式的应用名称，而不是内部代号或缩写。
5. DeepLink 要能真正落地。一键服务按钮点下去后跳转的链接，必须能正确打开应用的对应页面。如果链接失效或跳错位置，这个功能反而会让用户感到困惑。

日历是一个天然的时间管理入口，用户每天都会看。把应用中有价值的时间事件写进去，既帮用户管理好了日程，也为应用争取到了在系统级入口的露出机会。

本文由人人都是产品经理作者【纯爱掌门人】，原创/授权 发布于人人都是产品经理，未经许可，禁止转载。

题图来自Unsplash，基于 CC0 协议。