Flutter定时器控制插件timer_controller的使用

概述

timer_controller 是一个Flutter库，它提供了对计时器的操作（播放、暂停、重启等）以及用于消费计时器值的小部件。这个库非常适合需要在应用中实现倒计时或正计时功能的开发者。

• GitHub Actions Build
• Pub Package
• Codecov Coverage

开始使用

添加依赖

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  ...
  timer_controller: ^0.1.0

然后在 Dart 文件中导入包：

import 'package:timer_controller/timer_controller.dart';

TimerController

TimerController 继承自 ValueNotifier，因此你可以访问它的 value 属性来获取计时器的信息。

构造函数

根据可用的时间单位，可以使用不同的构造函数创建 TimerController 实例：

final TimerController secondsTimer = TimerController.seconds(15);
final TimerController minutesTimer = TimerController.minutes(3);
final TimerController hoursTimer = TimerController.hours(2);

注意：记得在不再需要 TimerController 时调用 dispose() 方法释放资源。

控制方法

• start()：开始计时。
• pause()：暂停计时。
• reset()：将计时器重置为初始值。
• restart()：将计时器重置为初始值并重新开始计时。

TimerValue

TimerValue 表示计时器的状态，并具有以下属性：

TimerValue({
  required int remaining, // 剩余时间
  required TimerUnit unit, // 计时单位
  TimerStatus status = TimerStatus.initial, // 计时器状态
});

内置小部件

timer_controller 提供了几个内置的小部件来构建基于控制器的UI或执行某些动作。

TimerControllerBuilder

TimerControllerBuilder 可以根据 TimerController 的值构建小部件：

TimerControllerBuilder(
  controller: myTimerController,
  builder: (context, value, child) {
    // 根据 myTimerController 的值返回相应的 widget
  }
)

可选条件：如果想要更细粒度地控制何时调用构建函数，可以提供一个条件给 TimerControllerBuilder。该条件接受前一个计时器值和当前计时器值作为参数，并返回一个布尔值。如果条件返回 true，则构建函数将被调用，并且小部件会重新构建；如果条件返回 false，则不会调用构建函数也不会触发重建。

TimerControllerListener

TimerControllerListener 可以根据 TimerController 的值运行特定的动作：

TimerControllerListener(
  controller: myTimerController,
  listener: (context, value) {
    // 根据 myTimerController 的值执行相应操作
  },
  child: Container(),
)

可选条件：与 TimerControllerBuilder 类似，可以通过提供条件来控制监听器函数的调用时机。

示例代码

下面是一个完整的示例程序，展示了如何使用 timer_controller 创建一个简单的计时器应用程序：

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

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Timer controller demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const _TimerWidget(),
    );
  }
}

class _TimerWidget extends StatefulWidget {
  const _TimerWidget({Key? key}) : super(key: key);

  @override
  __TimerWidgetState createState() => __TimerWidgetState();
}

class __TimerWidgetState extends State<_TimerWidget> {
  late TimerController _controller;

  @override
  void initState() {
    _controller = TimerController.seconds(20);
    super.initState();
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Timer controller demo'),
      ),
      body: TimerControllerListener(
        controller: _controller,
        listenWhen: (previousValue, currentValue) =>
            previousValue.status != currentValue.status,
        listener: (context, timerValue) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text('Status: ${describeEnum(timerValue.status)}'),
              duration: const Duration(seconds: 1),
            ),
          );
        },
        child: Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              TimerControllerBuilder(
                controller: _controller,
                builder: (context, timerValue, _) {
                  Color timerColor = Colors.black;
                  switch (timerValue.status) {
                    case TimerStatus.initial:
                      timerColor = Colors.black;
                      break;
                    case TimerStatus.running:
                      timerColor = Colors.green;
                      break;
                    case TimerStatus.paused:
                      timerColor = Colors.grey;
                      break;
                    case TimerStatus.finished:
                      timerColor = Colors.red;
                      break;
                  }
                  return Text(
                    '${timerValue.remaining}',
                    style: TextStyle(
                      fontSize: 50,
                      color: timerColor,
                    ),
                  );
                },
              ),
              const SizedBox(height: 40),
              Wrap(
                spacing: 20,
                runSpacing: 20,
                children: [
                  _ActionButton(
                    title: 'Start',
                    onPressed: () => _controller.start(),
                  ),
                  _ActionButton(
                    title: 'Pause',
                    onPressed: () => _controller.pause(),
                  ),
                  _ActionButton(
                    title: 'Reset',
                    onPressed: () => _controller.reset(),
                  ),
                  _ActionButton(
                    title: 'Restart',
                    onPressed: () => _controller.restart(),
                  ),
                ],
              ),
            ],
          ),
        ),
      ),
    );
  }
}

class _ActionButton extends StatelessWidget {
  const _ActionButton({
    Key? key,
    this.onPressed,
    required this.title,
  })  : assert(title != null),
        super(key: key);

  final VoidCallback? onPressed;
  final String title;

  @override
  Widget build(BuildContext context) {
    return OutlinedButton(
      onPressed: onPressed,
      child: Text(title),
    );
  }
}

这段代码创建了一个包含计时器显示和四个按钮（开始、暂停、重置、重启）的应用程序界面。当计时器状态改变时，还会显示一个短暂的消息提示用户当前的状态。