Flutter日历同步插件caldav_client的使用

CalDAV 客户端

一个用于 Dart 的 CalDAV 客户端。它允许轻松快速地向服务器发送 CalDAV 请求。

教程

设置

要使用 CalDAV 客户端，你需要创建一个 CalDavClient 实例，并传入请求将被发送到的 URL。

var client = CalDavClient(
  baseUrl: 'https://your-caldav-server-url',
  headers: Authorization('username', 'password').basic(),
);

初始同步

你可能首先想要进行初始同步，这将返回每个日历集合的 path、displayname 和 ctag。 该 ctag 类似于变更 ID。每次 ctag 发生变化时，你知道日历中也发生了变化。

var response = await client.initialSync('/dav.php/calendars/username/');

返回属性：getctag 和 displayname。

获取对象

如果你想要获取日历数据，需要使用 getObjects 方法。通过此方法，你可以获得 calendar-data，以及 path 和 etag。 这些数据由每个 .ics 文件（即每个日历对象）提供。该方法必须接收作为参数的日历集合路径。 etag 在日历对象发生变化时会改变。

var response = await client.getObjects('/dav.php/calendars/username/calendar-name');

返回属性：getetag 和 calendar-data。

获取时间范围内的对象

为了获取某个时间范围内的对象，可以使用 getObjectsInTimeRange 方法。通过此方法，你可以获得 calendar-data，以及 path 和 etag。

var now = DateTime.now();
var end = DateTime.utc(2021, 11, 9);
var response = await client.getObjectsInTimeRange('/dav.php/calendars/username/calendar-name', now, end);

返回属性：getetag 和 calendar-data。

获取更改

你必须首先执行另一个初始同步以查看 ctag 是否发生变化。如果发生变化，则可以更具体地检查每个对象以查看哪个对象发生了变化。为此，你必须使用 getChanges 方法，该方法返回每个 etag。请记住，每个 etag 在对象发生变化时会改变。除了 etag，你还应该检查是否有更多的 URL 或更少的 URL。

var response = await client.getChanges('/dav.php/calendars/username/calendar-name');

返回属性：getetag。

下载 .ics 文件

如果你想下载每个日历对象的 .ics 文件，必须使用 downloadIcs 方法。第一个参数是要下载的文件路径，第二个参数是要保存文件的目录路径。

var response = await client.downloadIcs('/dav.php/calendars/username/calendar-name/object1.ics', '/path/to/save');

多重获取

频繁地使用 getObject 进行查询可能会导致高带宽消耗。如果使用 downloadIcs 查询数据，对于每个更改的对象逐一进行操作可能会很麻烦。为了解决这个问题，我们可以使用 multiget。multiget 允许我们查询多个日历对象的数据，不一定是所有对象。

var files = ['object1.ics', 'object2.ics'];

var response = await client.multiget('/dav.php/calendars/username/calendar-name', files);

返回属性：getetag 和 calendar-data。

更新日历

如果你想更新一个对象，只需要使用 updateCal 方法。它接收要更新的对象路径、etag 以及将替换它的日历对象。日历必须遵循 ICalendar 格式。

var response = await client.updateCal('/dav.php/calendars/username/calendar-name/object1.ics', 'etag-value', icalendarData);

注意事项：

• 不得更改原始对象的 UID
• 每个对象应仅包含一个事件或任务
• 不能将 VEVENT 更改为 VTODO

创建日历

创建日历对象非常简单，只需注意要使用的路径未被其他对象使用。

var response = await client.createCal('/dav.php/calendars/username/calendar-name/new-object.ics', calendarData);

删除日历

删除日历对象可能是最容易做的事情。第二参数中的 etag 必须与要删除的对象的 etag 相符。要删除的对象位于第一个参数中的路径。

var response = await client.deleteCal('/dav.php/calendars/username/calendar-name/object1.ics', 'etag-value');

多状态

通过 CalDAV 进行的查询结果是通过多状态返回的。多状态包含不同元素（无论是日历还是对象）的信息，以及它们返回的状态。其结构如下图所示：

.
+-- Multistatus  
    +-- Response (list)
        +-- href
        +-- Propstat
            +-- prop (map)
            +-- status

Response：每个查询元素的答案列表。

href：查询元素的路径。

Propstat：与返回的状态一起获得的属性。

prop：包含属性名称作为键的映射。你必须在每个方法中检查它返回什么属性。

以下方法在响应中包含一个多状态对象：

• initialSync
• getObjects
• getChanges
• multiget

特性和错误报告

请在 GitHub issue 跟踪器 上提交功能请求和错误报告。

示例代码

import 'package:caldav_client/caldav_client.dart';
import 'package:caldav_client/src/utils.dart';

void main() async {
  var client = CalDavClient(
    baseUrl: 'https://your-caldav-server-url',
    headers: Authorization('username', 'password').basic(),
  );

  // 初始同步
  var initialSyncResult = await client.initialSync('/dav.php/calendars/username/');

  var calendars = <String>[];

  // 打印日历并保存日历路径
  for (var result in initialSyncResult.multistatus!.response) {
    print('PATH: ${result.href}');

    if (result.propstat.status == 200) {
      var displayname = result.propstat.prop['displayname'];
      var ctag = result.propstat.prop['getctag'];

      if (displayname != null && ctag != null) {
        print('CALENDAR: $displayname');
        print('CTAG: $ctag');

        calendars.add(result.href);
      } else {
        print('This collection is not a calendar');
      }
    } else {
      print('Bad prop status');
    }
  }

  // 打印日历对象信息
  if (calendars.isNotEmpty) {
    var getObjectsResult = await client.getObjects(calendars.first);

    for (var result in getObjectsResult.multistatus!.response) {
      print('PATH: ${result.href}');

      if (result.propstat.status == 200) {
        print('CALENDAR DATA:\n${result.propstat.prop['calendar-data']}');
        print('ETAG: ${result.propstat.prop['getetag']}');
      }
      print('Bad prop status');
    }

    var calendar = '''
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//PYVOBJECT//NONSGML Version 1//EN
BEGIN:VEVENT
UID:test@example.com
DTSTART;VALUE=DATE:20190306
CLASS:PRIVATE
DESCRIPTION:Arman and Adrian released their SRT-file parser library for Dart
DTSTAMP;X-VOBJ-FLOATINGTIME-ALLOWED=TRUE:20190306T000000
LOCATION:Heilbronn
PRIORITY:0
RRULE:FREQ=YEARLY
STATUS:CONFIRMED
SUMMARY:SRT-file Parser Release
URL:https://pub.dartlang.org/packages/srt_parser
END:VEVENT
END:VCALENDAR''';

    // 创建日历
    var createCalResponse =
        await client.createCal(join(calendars.first, '/example.ics'), calendar);

    if (createCalResponse.statusCode == 201) print('Created');
  }
}