Flutter插件ctmanager的使用方法

Flutter插件ctmanager的使用方法

在本篇文章中，我们将探讨一个名为 ctmanager 的 Flutter 插件，该插件主要用于管理多个取消令牌（CancellationToken），并展示其在不同场景下的潜在用途。该插件可以帮助我们更轻松地处理一些可以被用户取消的操作，如 HTTP 请求或图像处理等。

注意事项

请注意，此插件并不实际取消已执行的操作，而只是防止在取消时挂起的 await 进程。对于 HTTP 请求或图像处理等操作，你可能需要添加额外的机制来处理取消事件。

使用方法

CTManager 可以作为单例使用，也可以作为新实例使用。让我们通过几个示例来看看如何使用它。

单例方式

final newCancelToken = CTManager.I.create(
    token: 'ct1',
    operation: Future.delayed(
        const Duration(seconds: 5), 
        () => 'done',
    ),
    // 可选参数
    onCancel: () => print('cancelled'),
);

非单例方式

final ctManager = CTManager();
final newCancelToken = ctManager.create(
    token: 'ct1',
    operation: Future.delayed(
        const Duration(seconds: 5), 
        () => 'done',
    ),
    // 可选参数
    onCancel: () => print('cancelled'),
);

注意：token 字段不能为 null。

在这两个示例中，newCancelToken 都是一个新的 CancellationToken<String, String?> 实例，因为 token 是一个 String，且 operation 的返回值也是一个 String。

示例 1

// 该操作将在3秒后被取消。
Future.delayed(
    const Duration(seconds: 3), 
    newCancelToken.cancel,
);

final result = await newCancelToken.result;

// 因为该操作永远不会返回 `null`，
// 我们只需要检查它是否为 `null`。
// 如果是，则表示该操作已被取消。
if(result == null) {
    print('操作在3秒后被取消');
} else {
    print('操作成功完成');
}

示例 2

final nullableValueCancelToken = CTManager.I.create(
    token: 'ct1',
    operation: Future.delayed(
        const Duration(seconds: 5), 
        () => 1 < 2 ? null : 'done',
    ),
);

// 该操作将在3秒后被取消。
Future.delayed(
    const Duration(seconds: 3), 
    nullableValueCancelToken.cancel,
);

final result = await nullableValueCancelToken.result;

if(nullableValueCancelToken.isCompleted) {
    if(result == null) {
        print('操作成功完成，结果为 null');
    } else {
        print('操作成功完成，结果不为 null');
    }
} else {
    print('操作在3秒后被取消');
}

其他功能

除了上述示例外，CTManager 还提供了其他一些有用的功能，如查找特定的取消令牌、检查令牌是否存在，以及直接运行操作等。

查找取消令牌

final findToken = CTManager.I.of<String, String>('ct1');
// 注意：在检查令牌之前，请确保检查 `[findToken]` 是否为 `null`。
// 如果是 `null`，则表示要查找的令牌可能已经被取消、已完成或者从未创建过。

检查令牌是否存在

final bool isStillRunning = CTManager.I.hasTokenOf('ct1');
// 或者
// final bool isNotRunning = CTManager.I.noTokenOf('ct1'); 

取消令牌

CTManager.I.cancel('ct1');

直接运行操作

如果已经知道 operation 不会返回 null，可以直接运行它。

final result = await CTManager.I.run(
    token: 'ct1',
    operation: Future.delayed(
        const Duration(seconds: 5), 
        () => print('done'),
    ),
);

// 要取消操作，只需调用
// CTManager.I.cancel('ct1');
// 在操作完成之前调用。
// 请注意，即使在取消后，`print('done')` 仍然会被执行，这是正常的。

完整示例 Demo

以下是一个完整的示例，展示了如何在 Flutter 应用程序中使用 ctmanager 插件。

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

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

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomeScreen(),
    );
  }
}

class HomeScreen extends StatefulWidget {
  [@override](/user/override)
  _HomeScreenState createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('CTManager Example'),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            example1();
            example2();
            example1_2();
            example3();
          },
          child: Text('Run Examples'),
        ),
      ),
    );
  }

  Future<void> example1() async {
    final ctManager = CTManager();
    final newCancelToken = ctManager.create(
      token: 'ct1',
      operation: Future.delayed(
        const Duration(seconds: 5),
        () => 'done',
      ),
      // 可选参数
      onCancel: () => print('[example1]: cancelled'),
    );
    // 该操作将在3秒后被取消。
    Future.delayed(
      const Duration(seconds: 3),
      newCancelToken.cancel,
    );

    final result = await newCancelToken.result;
    // 因为该操作永远不会返回 `null`，
    // 我们只需要检查它是否为 `null`。
    // 如果是，则表示该操作已被取消。
    if (result == null) {
      print('[example1]: 操作在3秒后被取消');
    } else {
      print('[example1]: 操作成功完成');
    }
  }

  Future<void> example2() async {
    final nullableValueCancelToken = CTManager.I.create(
      token: 'ct1',
      operation: Future.delayed(
        const Duration(seconds: 5),
        () => 1 < 2 ? null : 'done',
      ),
      // 可选参数
      onCancel: () => print('[example2]: cancelled'),
    );
    // 该操作将在3秒后被取消。
    Future.delayed(
      const Duration(seconds: 3),
      nullableValueCancelToken.cancel,
    );

    final result = await nullableValueCancelToken.result;
    if (nullableValueCancelToken.isCompleted) {
      if (result == null) {
        print('[example2]: 操作成功完成，结果为 null');
      } else {
        print('[example2]: 操作成功完成，结果不为 null');
      }
    } else {
      print('[example2]: 操作在3秒后被取消');
    }
  }

  Future<void> example1_2() async {
    CTManager.I.run(
      token: 'ct2',
      operation: Future.delayed(
        const Duration(seconds: 5),
        () => print('[example1_2]: done'),
      ),
      onCancel: () => print('[example1_2]: cancelled'),
    );
    // 取消操作在3秒后
    Future.delayed(
      const Duration(seconds: 3),
      () => CTManager.I.cancel('ct2'),
    );
  }

  Future<void> example3() async {
    final ct3 = CTManager.I.create(
      token: 'ct3',
      operation: Future.delayed(const Duration(seconds: 1), () => 'done ct3'),
    );
    final ct3result = await ct3.result;
    if (ct3result != null && ct3.isCompleted) {
      print('[example3]: 结果为 `$ct3result`');
    } else {
      print('[example3]: 操作被取消');
    }
  }
}