add_calendar 0.0.1

A Flutter plugin that invokes the native calendar app's "Add Event" page with prefilled fields, across Android, iOS, and HarmonyOS.

add_calendar

A Flutter plugin that invokes the native calendar app's "Add Event" page with prefilled fields, across Android, iOS, and HarmonyOS.

add_calendar 是一个调起系统日历 App「添加日程」页面并预填字段的 Flutter 插件，支持 Android、iOS、HarmonyOS 三端。

通过集成此插件，开发者可以快速实现日程添加功能，满足会议预约、生日提醒、日程跟进等场景的需求。

---

✨ 功能特性

• 📅 添加日程：调起系统日历的原生「添加日程」页面，字段自动预填。
• 🔔 提前提醒：支持配置多个提醒时间（提前 N 分钟），iOS / HarmonyOS 预填生效。
• 🌞 全天事件：支持全天日程，鸿蒙端自动按半开区间 [start, end) 预填结束时间。
• 📝 备注预填：支持日程备注预填。
• 🔐 权限管理：提供日历读写权限申请接口，未授权时自动拉起系统授权弹窗。
• 🛡️ 免权限调用：addEvent 调起系统页面本身不需要日历权限（数据读写均由系统日历完成）。
• 📱 三端覆盖：支持 Android、iOS、HarmonyOS，统一 API，平台差异内部处理。

---

📋 前置准备

在使用插件前，请务必完成以下配置：

说明：addEvent 调起系统日历页面不需要日历权限；如需在 App 内直接读写日历数据（如查询、删除日程），才需要申请权限并完成以下声明。

Android

在 AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />

iOS

在 Info.plist 中添加：

<key>NSCalendarsFullAccessUsageDescription</key>
<string>我们需要访问您的日历以便添加日程提醒</string>
<key>NSCalendarsUsageDescription</key>
<string>我们需要访问您的日历以便添加日程提醒</string>

NSCalendarsFullAccessUsageDescription 用于 iOS 17+ 的完整日历访问授权；NSCalendarsUsageDescription 用于 iOS 17 以下版本。

HarmonyOS

在 module.json5 中添加：

{
  "requestPermissions": [
    {
      "name": "ohos.permission.READ_CALENDAR",
      "reason": "$string:calendar_permission_reason",
      "usedScene": { "abilities": [], "when": "inuse" }
    },
    {
      "name": "ohos.permission.WRITE_CALENDAR",
      "reason": "$string:calendar_permission_reason",
      "usedScene": { "abilities": [], "when": "inuse" }
    }
  ]
}

---

🚀 快速开始

1. 添加依赖

在 pubspec.yaml 中添加：

dependencies:
  add_calendar: ^0.0.1

2. 导入包

import 'package:add_calendar/add_calendar.dart';

3. 代码示例

申请日历权限

void requestPermission() async {
  // 已授权直接返回 true；未授权自动拉起系统授权弹窗
  bool granted = await AddCalendarPlugin().requestPermission();
  print('日历权限：${granted ? '已授权' : '未授权'}');
}

添加日程

void addEvent() async {
  final event = AddCalendarEvent(
    title: '客户例会',                                  // 必填
    startTimeMs: DateTime(2026, 9, 24, 10, 0)          // 必填，毫秒时间戳
        .millisecondsSinceEpoch,
    endTimeMs: DateTime(2026, 9, 24, 11, 0)            // 必填，毫秒时间戳
        .millisecondsSinceEpoch,
    allDay: false,                                     // 可选，默认 false
    notes: '与客户沟通续保方案',                          // 可选
    minutesBeforeList: [5, 15, 30],                    // 可选，提前 5/15/30 分钟提醒
  );

  // 内部会调起系统日历「添加日程」页面并预填字段
  // 返回 true 表示用户在原生页面保存成功；false 表示取消或添加失败
  bool saved = await AddCalendarPlugin().addEvent(event);
  print(saved ? '日程已保存' : '已取消或添加失败');
}

---

📦 日程参数模型

class AddCalendarEvent {
  String title;                  // 日程标题（必填）
  int startTimeMs;               // 开始时间，毫秒时间戳（必填）
  int endTimeMs;                 // 结束时间，毫秒时间戳（必填）
  bool allDay;                   // 是否为全天事件，默认 false
  String? notes;                 // 备注
  List<int>? minutesBeforeList;  // 提醒时间数组，单位分钟，如 [5, 15, 30]
}

---

⚠️ 平台差异说明

平台	实现方式	保存/取消判定	提醒预填
iOS	App 内 modal 弹起 EKEventEditViewController	✅ 可精确区分（仅 .saved 返回 true）	✅ 支持
Android	Intent(ACTION_INSERT) 跳转系统日历添加页	⚠️ 不可精确区分（多数 OEM 日历无论保存还是取消均返回 RESULT_OK，约定「页面正常返回」即 true）	❌ 系统不支持预填提前提醒
HarmonyOS	CalendarManager.editEvent（API 12+）调起系统日程创建页	✅ 可精确区分（返回 eventId > 0 即保存成功）	✅ 支持

其他说明：

• HarmonyOS 端全天事件的结束时间会自动预填为「结束日次日 0 点」（半开区间 [start, end)）。
• iOS 权限接口在 iOS 17+ 使用 requestFullAccessToEvents，iOS 17 以下使用 requestAccess(to: .event)。
• Android 端全天事件使用文档化 extra EXTRA_EVENT_ALL_DAY，兼容部分忽略 Events.ALL_DAY 列名的系统日历。

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.