微信小程序可以写入手机日历吗？日程添加接口与实现方法

用户在微信小程序中预约了一场会议、购买了一张演出票，或者报名了一节课程，能不能直接把活动时间添加到手机自带日历中，并在开始前自动提醒？

答案是可以。微信小程序提供了专门的手机日历接口，开发者可以将日程标题、开始时间、结束时间、地点和提醒时间等信息写入手机系统日历，不必让用户退出小程序后手动创建日程。

不过，这项能力有明确的权限要求。小程序不能在未经用户授权的情况下随意修改手机日历，也不能把“添加日历事件”直接理解为能够读取、修改和管理用户的全部日程。

微信小程序有哪些日历接口

微信小程序提供了两个与写入系统日历直接相关的接口，分别用于添加普通日程和重复日程。

根据微信小程序开发接口资料，这两个接口从基础库2.15.0开始支持，需要做好低版本兼容处理，并且涉及相同的日历授权范围。

它们操作的是手机系统日历，而不是在小程序页面内部绘制一个日历组件。

例如用户点击“添加到日历”后，日程可以保存到手机的日历应用中。至于最终显示在哪个日历账户，以及是否同步到其他设备，则取决于手机的日历账户与同步设置。

什么场景适合写入手机日历

对于预约类小程序，添加系统日程通常具有比较明确的实际价值。

例如用户在小程序中预约了下午三点的服务，虽然订单已经生成，但几天之后可能忘记预约时间。如果提供一个“添加到手机日历”按钮，用户就可以把预约信息保存在自己平时使用的日历中。

类似需求还包括：

• 课程小程序：将上课时间加入手机日历。

• 活动报名：保存活动开始时间和地点。

• 医疗预约：添加就诊时间提醒。

• 会议预约：将会议安排加入个人日程。

• 票务小程序：保存演出或出行时间。

• 健身预约：记录训练课程和周期安排。

这种方式特别适合时间已经明确、用户确实需要提前准备的事件。对于普通内容浏览、电商商品查看等没有明确时间要求的操作，则没有必要频繁申请日历权限。

addPhoneCalendar支持哪些参数

wx.addPhoneCalendar的主要作用是向手机系统日历添加一条事件。

开发者可以传入以下常用参数：

如果只是添加一条简单日程，提供标题和开始时间即可。但在实际业务中，建议尽量补充结束时间、地点和说明，让用户添加后能够直接了解事件安排。

如何添加一条手机日程

假设用户预约了一场2026年10月20日上午9点开始、10点结束的会议，希望提前30分钟收到提醒，可以使用下面的代码。

function addCalendarEvent() {
  const startTime = Math.floor(
    new Date('2026-10-20T09:00:00+08:00').getTime() / 1000
  );

  const endTime = Math.floor(
    new Date('2026-10-20T10:00:00+08:00').getTime() / 1000
  );

  wx.addPhoneCalendar({
    title: '项目沟通会议',
    startTime,
    endTime,
    description: '讨论项目进度与后续安排',
    location: '公司会议室',
    allDay: false,
    alarm: true,
    alarmOffset: 1800,

    success() {
      wx.showToast({
        title: '日程添加成功',
        icon: 'success'
      });
    },

    fail(err) {
      console.error('添加日程失败', err);

      wx.showToast({
        title: '未能添加日程',
        icon: 'none'
      });
    }
  });
}

这段代码的关键是调用wx.addPhoneCalendar，并设置日程标题、开始时间、结束时间以及提醒提前量。

alarmOffset使用秒作为单位，因此1800代表提前30分钟提醒。

实际开发时，应该把示例中的固定日期替换成订单、预约记录或者活动数据中的真实时间。

时间戳格式需要特别注意

日历接口中的时间参数采用Unix时间戳。开发时尤其需要注意秒和毫秒之间的区别。

JavaScript中的Date.getTime()返回的是毫秒时间戳，而微信日历接口文档对Unix时间戳的描述采用秒数，因此传参时需要进行转换。

例如：

const timestamp = Math.floor(
  new Date('2026-10-20T09:00:00+08:00').getTime() / 1000
);

如果直接把JavaScript毫秒时间戳当作秒数传入，就可能出现时间无效或者日期不正确的问题。

此外，开发者应该明确日期所采用的时区。对于跨地区活动，最好由服务端统一保存带时区的时间，再根据业务需要转换，避免把北京时间误当成用户手机所在地时间。

添加日历需要用户授权吗

需要。

微信小程序日历接口涉及的授权范围是：

scope.addPhoneCalendar

根据微信相关权限调整说明，wx.addPhoneCalendar和wx.addPhoneRepeatCalendar都需要对应授权。

如果用户尚未作出授权选择，调用接口时可能触发授权请求。用户拒绝授权后，接口可能进入失败回调。

因此，比较合理的交互方式是在预约详情或活动成功页面提供一个明确的“添加到手机日历”按钮，由用户主动决定是否使用。

如果用户已经拒绝权限，可以通过wx.getSetting检查授权状态，并在用户主动点击设置按钮时，通过wx.openSetting引导其重新管理权限。

不建议在用户刚打开小程序时就直接申请日历权限，因为此时用户可能还不知道小程序为什么需要操作自己的手机日历。

重复日程应该使用哪个接口

如果用户希望添加的不是一次性会议，而是每周固定时间的课程，就可以考虑wx.addPhoneRepeatCalendar。

该接口在普通日程参数之外，还提供了重复规则和重复结束时间。

其中repeatInterval支持以下周期：

例如一个课程小程序需要添加每周重复的课程，可以在调用接口时指定：

wx.addPhoneRepeatCalendar({
  title: '每周课程',
  startTime,
  endTime,
  repeatInterval: 'week',
  repeatEndTime,
  alarm: true,
  alarmOffset: 1800,

  success() {
    console.log('重复日程添加成功');
  },

  fail(err) {
    console.error('重复日程添加失败', err);
  }
});

其中startTime、endTime和repeatEndTime需要在调用前计算好。

重复接口还存在一定规则限制。例如官方接口资料注明，每月重复模式中的日期不能大于28日。因此，对于每月29日、30日或31日的复杂周期安排，需要重新设计业务逻辑，并在目标设备上测试。

添加日程后能自动提醒吗

可以在创建日程时设置提醒参数，但不能把它理解为微信小程序本身拥有一个独立、可靠的定时推送系统。

日历接口提供alarm和alarmOffset两个参数。

例如：

alarm: true,
alarmOffset: 3600

表示为事件设置提前一小时的提醒。

日程添加成功以后，后续提醒主要由手机系统日历负责，而不是要求用户一直打开微信小程序。

但最终能否正常弹出通知，还受到手机系统通知权限、日历设置、省电策略以及设备兼容性等因素影响。

因此，接口调用成功不代表开发者可以保证每一台设备都在指定时刻弹出通知。

能不能后台自动写入日历

需要区分“获得授权后添加日程”和“后台静默管理日历”。

对于正常预约场景，小程序可以在获得对应权限后通过接口添加事件；但不能把这一能力理解为可以绕过用户授权，在任意时间、任意设备上批量写入日程。

从产品设计来看，最好把添加日程放在用户明确的操作之后，例如：

• 预约成功后点击添加日历。

• 活动报名成功后主动保存日程。

• 用户选择某节课程后点击添加提醒。

如果用户不希望使用这一功能，应该允许其直接跳过，而不是把授权日历作为完成普通订单或浏览内容的必要条件。

能否读取和修改已有日程

从上述两个接口的功能定位来看，它们主要解决的是向系统日历添加单次或重复事件，并不是完整的日历管理接口。

不能因为小程序获得了scope.addPhoneCalendar权限，就推断它能够随意读取手机中已有的所有日程、修改其他应用创建的事件或者删除用户的历史安排。

如果业务需要实现完整的日程同步，例如用户在小程序内修改会议时间后，手机日历也自动更新，就不能只依赖添加接口。

这种情况下，更适合把小程序服务端数据库作为业务日程的管理来源，再设计相应的更新提示或其他日历集成方案。

具体能否进一步集成第三方日历，还需要结合对应平台开放的API、授权方式与业务场景判断。

日程写入和订阅消息有什么区别

微信小程序提供的订阅消息，与系统日历属于两种不同机制。

例如预约成功以后，小程序可以提供“添加到手机日历”按钮，让用户保存时间；如果业务还需要发送预约变更、取消或其他服务通知，则可以另外考虑符合平台规则的订阅消息。

两者可以组合，但不能互相替代。尤其不能认为保存了日历事件，就意味着小程序已经获得向用户无限发送微信消息的权限。

iPhone和安卓需要分别测试吗

需要。

虽然微信提供统一的小程序日历接口，但它最终调用的是手机操作系统提供的日历能力。

iPhone和不同品牌安卓手机在日历账户、权限管理、系统通知、默认日历以及重复事件处理上可能存在差异。

例如某些用户没有配置正常可用的日历账户，或者关闭了日历通知，最终体验就可能与开发者测试设备不同。

正式上线前建议至少覆盖以下情况：

• 首次授权后添加日程。

• 用户拒绝权限后的失败处理。

• 用户重新开启权限后的操作。

• 单次事件与重复事件。

• 开启和关闭系统通知。

• 不同品牌安卓手机及iPhone。

• 低版本基础库和接口不可用情况。

如果小程序使用uni-app、Taro等跨端框架，还需要额外核对框架对应版本的API兼容情况，不能直接假设所有端的日历接口表现完全相同。

重复添加与日程变更怎么处理

实际业务中，比第一次写入日历更容易被忽略的是重复添加。

例如用户在订单详情中连续点击三次“添加到日历”，如果程序没有做任何限制，就可能重复创建多条相同的事件。

比较合理的处理方式是，在小程序自身保存与业务订单相关的添加状态，避免用户无意间重复操作。

但也要明确，自己数据库里的“已经添加”标记，并不意味着小程序能够随时查询手机日历，确认用户是否已经手动删除对应事件。

此外，如果课程临时改期，原先保存到手机日历中的时间不会因为小程序后台修改订单就必然自动改变。

开发者应该把这种情况纳入产品设计，例如明确提示用户日程发生变更，并提供重新保存新时间的操作，而不是默认两个系统中的数据始终实时同步。

参考资料

1. 微信小程序添加手机日程接口

2. 微信小程序添加重复日程接口

3. 腾讯云日历接口参数文档

4. 腾讯云微信小程序用户授权说明

5. Taro添加手机日程接口文档