插件介绍

FlutterTPC Device Calendar 是一个跨平台的 Flutter 插件，专门为 HarmonyOS 平台进行了适配，用于访问和管理设备上的日历功能。这个插件提供了丰富的 API，允许开发者在 Flutter 应用中实现日历的查看、创建、编辑和删除等操作。

主要功能特性

• 权限管理：检查和请求日历权限
• 日历管理：获取、创建和删除设备上的日历
• 事件管理：创建、更新、删除和检索日历事件
• 重复事件：支持设置重复事件规则
• 提醒功能：为事件添加提醒
• 参与者管理：添加、修改或删除事件参与者
• 时区支持：使用 TZDateTime 支持时区功能

如何使用插件

包的引入

由于这是一个自定义修改版本的三方库，需要以 git 形式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  device_calendar:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/device_calendar/device_calendar"
  device_calendar_ohos:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/device_calendar_ohos/device_calendar_ohos"
  timezone:
    ^0.9.0

添加依赖后，运行以下命令获取依赖包：

flutter pub get

API 的调用

初始化插件

import 'package:device_calendar/device_calendar.dart';
import 'package:timezone/timezone.dart';

DeviceCalendarPlugin _deviceCalendarPlugin = DeviceCalendarPlugin();

// 初始化时区
tz.initializeTimeZones();

权限管理

在使用日历功能之前，需要检查并请求日历权限：

// 检查是否有日历权限
final result = await _deviceCalendarPlugin.hasPermissions();
if (result.isSuccess && !result.data!) {
  // 请求日历权限
  final requestResult = await _deviceCalendarPlugin.requestPermissions();
  if (!requestResult.isSuccess || !requestResult.data!) {
    // 权限请求失败
    return;
  }
}

获取所有日历

// 获取设备上的所有日历
final calendarsResult = await _deviceCalendarPlugin.retrieveCalendars();
if (calendarsResult.isSuccess) {
  List<Calendar> calendars = calendarsResult.data!;
  for (var calendar in calendars) {
    print('日历名称: ${calendar.name}, ID: ${calendar.id}');
  }
}

创建新日历

// 创建一个新的日历
final createCalendarResult = await _deviceCalendarPlugin.createCalendar(
  '我的测试日历',
  calendarColor: Colors.blue,
  localAccountName: 'Device Calendar',
);

if (createCalendarResult.isSuccess) {
  String newCalendarId = createCalendarResult.data!;
  print('新日历创建成功，ID: $newCalendarId');
}

创建日历事件

// 获取当前时区
Location currentLocation = getLocation('Asia/Shanghai');
setLocalLocation(currentLocation);

// 创建事件
final event = Event(
  calendarId, // 目标日历ID
  title: '鸿蒙开发者会议',
  description: '讨论Flutter在鸿蒙上的应用开发',
  start: TZDateTime.now(currentLocation).add(Duration(hours: 1)),
  end: TZDateTime.now(currentLocation).add(Duration(hours: 2)),
  allDay: false,
  attendees: [
    Attendee(
      email: 'developer@example.com',
      name: '开发者',
    ),
  ],
  reminders: [
    Reminder(minutes: 30), // 提前30分钟提醒
  ],
);

// 保存事件
final createEventResult = await _deviceCalendarPlugin.createOrUpdateEvent(event);
if (createEventResult != null && createEventResult.isSuccess) {
  String eventId = createEventResult.data!;
  print('事件创建成功，ID: $eventId');
}

创建重复事件

// 创建重复事件规则
final recurrenceRule = RecurrenceRule(
  RecurrenceFrequency.Daily, // 每天重复
  interval: 1, // 间隔1天
  endDate: TZDateTime.now(currentLocation).add(Duration(days: 7)), // 7天后结束
);

// 创建重复事件
final recurringEvent = Event(
  calendarId,
  title: '每日站会',
  description: '团队每日站会',
  start: TZDateTime.now(currentLocation).add(Duration(hours: 9)),
  end: TZDateTime.now(currentLocation).add(Duration(hours: 9, minutes: 15)),
  allDay: false,
  recurrenceRule: recurrenceRule,
);

// 保存重复事件
final createRecurringEventResult = await _deviceCalendarPlugin.createOrUpdateEvent(recurringEvent);
if (createRecurringEventResult != null && createRecurringEventResult.isSuccess) {
  String recurringEventId = createRecurringEventResult.data!;
  print('重复事件创建成功，ID: $recurringEventId');
}

检索日历事件

// 设置检索参数
final params = RetrieveEventsParams(
  startDate: TZDateTime.now(currentLocation).subtract(Duration(days: 7)),
  endDate: TZDateTime.now(currentLocation).add(Duration(days: 7)),
);

// 检索事件
final eventsResult = await _deviceCalendarPlugin.retrieveEvents(calendarId, params);
if (eventsResult.isSuccess) {
  List<Event> events = eventsResult.data!;
  for (var event in events) {
    print('事件标题: ${event.title}, 开始时间: ${event.start}');
  }
}

更新日历事件

// 首先获取要更新的事件
final params = RetrieveEventsParams(
  eventIds: [eventId],
);

final eventsResult = await _deviceCalendarPlugin.retrieveEvents(calendarId, params);
if (eventsResult.isSuccess && eventsResult.data!.isNotEmpty) {
  Event eventToUpdate = eventsResult.data!.first;
  
  // 更新事件信息
  eventToUpdate.title = '更新后的会议标题';
  eventToUpdate.description = '更新后的会议描述';
  
  // 保存更新
  final updateResult = await _deviceCalendarPlugin.createOrUpdateEvent(eventToUpdate);
  if (updateResult != null && updateResult.isSuccess) {
    print('事件更新成功');
  }
}

删除日历事件

// 删除指定事件
final deleteResult = await _deviceCalendarPlugin.deleteEvent(calendarId, eventId);
if (deleteResult.isSuccess && deleteResult.data!) {
  print('事件删除成功');
}

鸿蒙平台特别说明

支持的功能

功能	HarmonyOS
hasPermissions	✅
requestPermissions	✅
retrieveCalendars	✅
retrieveEvents	✅
deleteCalendar	✅
createOrUpdateEvent	✅
deleteEvent	✅
deleteEventInstance	⛔️

注意事项

1. 时区处理：在鸿蒙平台上，所有日期时间操作都需要使用 TZDateTime 来确保时区正确性
2. 全天事件：全天事件的日期存储时区是 Asia/Shanghai，但获取时是 UTC，可能会导致日期显示提前一天
3. 权限配置：鸿蒙平台需要在应用配置文件中声明日历权限

总结

FlutterTPC Device Calendar 插件为 HarmonyOS 平台的 Flutter 应用提供了完整的日历功能支持。通过本文的介绍，你应该已经了解了：

1. 插件介绍：FlutterTPC Device Calendar 是一个跨平台插件，为 HarmonyOS 提供了日历管理功能
2. 包的引入：通过 Git 形式引入自定义修改版本的依赖包
3. API 的调用：包括权限管理、日历管理、事件管理等核心功能的使用方法
4. 鸿蒙平台特别说明：了解在鸿蒙平台上的功能支持情况和注意事项

使用这个插件，开发者可以在 HarmonyOS 平台上轻松实现日历相关的功能，为用户提供更好的日程管理体验。

示例项目

插件提供了鸿蒙平台的示例项目，可以在 ohos/example 目录下找到。通过运行示例项目，可以更好地了解插件的使用方法和功能特性。

运行示例项目：

cd fluttertpc_device_calendar-master/ohos/example
flutter run

常见问题

1. 权限问题：确保在应用配置文件中正确声明了日历权限
2. 时区问题：始终使用 TZDateTime 来处理日期时间，避免时区错误
3. 全天事件问题：注意全天事件的日期存储和获取时区差异

如果在使用过程中遇到问题，可以参考插件的官方文档或在社区寻求帮助。