Flutter日历展示与管理插件visuals_calendar的使用

Flutter日历展示与管理插件visuals_calendar的使用

VisualsCalendar 是一个高度可定制的日历小部件，支持 日、周 和 3天 视图。它显示当前月份的头部，并提供了事件选择、自定义样式和异步事件加载等功能。

功能

• 可定制的日历样式，
• 用户定义的事件，
• 兼容未来的事件，
• 滚动和垂直缩放，
• 支持多种视图（如每日、3天、每周）

开始使用

要安装该包，请将其添加到你的 pubspec.yaml 文件中：

flutter pub add visuals_calendar

使用方法

创建一组事件

首先，创建一组事件。事件类型详见下方文档。

List<Event> events = [
  Event(DateTime.now(), 'Event 1', Colors.pink),
  Event(DateTime.now().add(const Duration(hours: 3)), 'Event 2', Colors.blue),
  Event(DateTime.now().add(const Duration(hours: 5)), 'Event 3', Colors.green),
];

使用VisualsCalendar小部件展示事件

接下来，使用 VisualsCalendar 小部件来展示这些事件。

class VisualsApp extends StatelessWidget {
  const VisualsApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: VisualsCalendar(
        events: events,
        defaultFormat: CalendarFormat.week,
        selectionEnabled: true,
      ),
    );
  }
}

事件类型文档

Event 类表示一个带有开始时间和结束时间、标题、颜色等属性的日历事件。其他可选属性包括地点和描述。

构造函数

Event(
  this.start,
  this.title,
  this.color, {
  this.end,
  this.isAllDay,
  this.description,
  this.location,
  this.onTap,
});

构造函数参数及自定义

VisualsCalendar({
  required this.defaultFormat,
  this.events,
  this.futureEvents,
  this.eventBuilder,
  this.appBarBuilder,
  this.selectionEnabled,
  this.onTimeSelected,
  this.style
})

defaultFormat

CalendarFormat

必需。 定义日历的默认显示格式。 可用格式有 [CalendarFormat.day, CalendarFormat.threedays, CalendarFormat.week]。

events

List<Event>?

显示在日历上的事件列表。每个事件包含标题和日期等信息。

futureEvents

Future<List<Event>>?

通过 Future 异步提供事件。在 Future 解析过程中，日历上会显示加载指示器。

eventBuilder

Widget Function(BuildContext context, Event event)?

用于构建自定义事件图块的函数。 允许完全控制单个事件的显示方式。

appBarBuilder

AppBar Function(BuildContext context, String currentMonth, void Function() setToday, void Function(CalendarFormat) setFormat, List<CalendarFormat> availableFormats)?

自定义 AppBar 构建器。提供对 AppBar 的自定义，包括当前月份、跳转到今天的按钮，以及切换日和周格式的能力。

selectionEnabled

bool?

启用或禁用选择功能以创建新事件。当为 true 时，用户可以选中时间段来创建事件。

onTimeSelected

void Function(DateTime start, DateTime end)?

当选定时间段时触发的回调函数。提供选定时间段的开始时间和结束时间。需要 selectionEnabled 为 true。 适用于允许用户直接从日历创建新事件的情况。

style

class CalendarStyle {
  // 日历的背景颜色。
  final Color? backgroundColor;
  // 头部的颜色。
  final Color? headerColor;

  // 头部日期文本样式。
  final TextStyle? dateTextStyle;
  // 左侧小时指示器的文本样式。
  final TextStyle? hourTextStyle;

  // 如果使用默认事件图块，事件标题的文本样式。
  final TextStyle? eventTitleTextStyle;
  // 如果使用默认事件图块，事件描述的文本样式。
  final TextStyle? eventDescriptionTextStyle;

  // 加载指示器的颜色。
  final Color? loadingIndicatorColor;
  // 时间指示器的颜色。
  final Color? timeIndicatorColor;
  // 今天指示器的颜色。
  final Color? todayIndicatorColor;
}

允许自定义日历的外观。你可以定义不同部分的日历样式，例如背景、文本和事件图块。

贡献

如何贡献

• Fork 仓库。
• 克隆你的 Fork 并创建一个新的分支。
• 提交包含你更改的 Pull Request。

开放问题和路线图

• 查看 GitHub Issues 上当前的问题和计划的功能。

开发指南

• 遵循我们的编码标准和测试策略。
• 确保为任何新功能编写单元测试。

如何联系我们

• 加入 GitHub Discussions 或我们的 Slack 频道。

示例代码

以下是示例代码：

import 'package:flutter/material.dart';
import 'package:visuals_calendar/types/calendar_format.types.dart';
import 'package:visuals_calendar/visuals_calendar.dart';

import 'mock_events.dart';

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return const MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Visuals Calendar',
      home: VisualsApp(),
    );
  }
}

class VisualsApp extends StatelessWidget {
  const VisualsApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: VisualsCalendar(
        events: getMockEvents(),
        defaultFormat: CalendarFormat.week,
      ),
    );
  }
}