Flutter重复事件规则解析插件rrule的使用

简介

rrule 是一个用于解析和计算符合iCalendar RFC定义的重复规则的Dart库。它可以帮助开发者轻松地处理日历中的重复事件，如每周、每月或每年发生的事件。

如何使用此包

创建 RecurrenceRule

// 每两周的星期二和星期四，但仅限12月。
final rrule = RecurrenceRule(
  frequency: Frequency.weekly,
  interval: 2,
  byWeekDays: {
    ByWeekDayEntry(DateTime.tuesday),
    ByWeekDayEntry(DateTime.thursday),
  },
  byMonths: {12},
);

获取重复实例

final Iterable<DateTime> instances = rrule.getInstances(
  start: DateTime.now().copyWith(isUtc: true),
);

⚠️ 注意：rrule 不处理任何与时区相关的问题。所有提供的 DateTime 必须将 isUtc 设置为 true（因为UTC没有夏令时和冬令时等复杂情况），但实际时区会被忽略，例如在生成人类可读文本时。

如果有一个本地时区的 DateTime 实例，可以使用 rrule 的辅助方法 dateTime.copyWith(isUtc: true)，这会保持日期和时间但设置 isUtc 为 true。要将生成的实例转换回本地时区，可以使用 dateTime.copyWith(isUtc: false)。

限制返回的实例

除了使用 RecurrenceRule.until 或 RecurrenceRule.count 外，还可以使用 Dart 的默认 Iterable 函数来限制返回的实例：

final firstThreeInstances = instances.take(3);

final onlyThisYear = instances.takeWhile(
  (instance) => instance.year == DateTime.now().year,
);

final startingNextYear = instances.where(
  (instance) => instance.year > DateTime.now().year,
);

机器可读字符串转换

可以通过 RecurrenceRuleStringCodec 或以下便捷方法在 RecurrenceRule 和 iCalendar/RFC 5545 兼容的 String 之间进行转换：

final string = 'RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;BYMONTH=12';
final rrule = RecurrenceRule.fromString(string);

assert(rrule.toString() == string); // true

人类可读文本转换

可以通过 RecurrenceRule.toText() 将 RecurrenceRule 转换为人类可读的 String：

// 首先加载本地化（目前仅支持英语和荷兰语）：
final l10n = await RruleL10nEn.create();

final rrule = RecurrenceRule.fromString(
  'RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;BYMONTH=12',
);

final text = 'Every other week in December on Tuesday & Thursday';
assert(rrule.toText(l10n: l10n) == text); // true

JSON转换

可以通过以下便捷方法在 RecurrenceRule 和 jCal/RFC 7265 兼容的 JSON 之间进行转换：

final json = <String, dynamic>{
  'freq': 'WEEKLY',
  'interval': 2,
  'byday': ['TU', 'TH'],
  'bymonth': [12],
};
final rrule = RecurrenceRule.fromJson(json);

expect(rrule.toJson(), json);

限制

• 自定义周开始不被支持（WKST 在规范中）—— 星期一（编码为 MO）是唯一有效的值。
• 不支持闰秒（Dart 的 DateTime 限制）。
• 仅支持公元纪元的 0 到 9999 年（iCalendar RFC 的限制，但如果需要，扩展起来应该很容易）。

示例 Demo

下面是一个完整的示例，展示了如何使用 rrule 插件来创建和解析重复规则，并获取重复实例。

import 'package:flutter/material.dart';
import 'package:rrule/rrule.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('rrule 示例')),
        body: Center(child: RruleDemo()),
      ),
    );
  }
}

class RruleDemo extends StatefulWidget {
  @override
  _RruleDemoState createState() => _RruleDemoState();
}

class _RruleDemoState extends State<RruleDemo> {
  List<String> instances = [];

  void _generateInstances() async {
    final rrule = RecurrenceRule(
      frequency: Frequency.weekly,
      interval: 2,
      byWeekDays: {
        ByWeekDayEntry(DateTime.tuesday),
        ByWeekDayEntry(DateTime.thursday),
      },
      byMonths: {12},
    );

    final Iterable<DateTime> allInstances = rrule.getInstances(
      start: DateTime.now().copyWith(isUtc: true),
    );

    final limitedInstances = allInstances.take(5).toList();

    setState(() {
      instances = limitedInstances.map((dt) => dt.toLocal().toString()).toList();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        ElevatedButton(
          onPressed: _generateInstances,
          child: Text('生成实例'),
        ),
        SizedBox(height: 20),
        Expanded(
          child: ListView.builder(
            itemCount: instances.length,
            itemBuilder: (context, index) {
              return ListTile(
                title: Text(instances[index]),
              );
            },
          ),
        ),
      ],
    );
  }
}

这个示例应用程序提供了一个按钮，点击后会生成并显示前五个符合条件的重复实例。希望这个示例能帮助你更好地理解和使用 rrule 插件。