bot_toast 1.1.0

BotToast ❤ #

Build Status codecov

一个真正意义上的flutter Toast库! #

🐶特点 #

  • 真正意义上的Toast,可以在任何你需要的时候调用,不会有任何限制! (这是他最重要的特点,跟别的Toast库不同的地方)

  • 功能丰富,支持显示通知,文本,加载,附属等类型Toast

  • 支持在弹出各种自定义Toast,或者说你可以弹出任何Widget,只要它符合flutter代码的要求即可

  • Api简单易用,基本上没有必要参数(包括BuildContext),基本上都是可选参数

  • 纯flutter实现,不容易带来兼容问题

  • In the true sense of Toast, you can call it whenever you need it, without any restrictions! (This is his most important feature, different from other Toast libraries)

  • Feature-rich, support for displaying notifications, text, loading, attachments, etc. Toast

  • Support for popping up various custom Toasts, or you can pop up any Widget as long as it meets the requirements of the flutter code.

  • Api is easy to use, basically has no necessary parameters (including BuildContext), basically all optional parameters

  • Pure flutter implementation, it is not easy to bring compatibility problems

🐼例子 #

在线例子(Online demo) (Web效果可能有偏差,真实效果请以手机端为准)

🐺效果图 #

NotificationAttached
NotificationAttached
LoadingText
LoadingText

🐮快速使用 #

1. pubspec.yaml文件里添加依赖 #

dependencies:
     bot_toast: ^1.1.0

2. 导入BotToast库 #

import 'package:bot_toast/bot_toast.dart';

3. 初始化BotToast #

///像这样,BotToast将会自动去初始化
MaterialApp(
      title: 'BotToast Demo',
      navigatorObservers: [BotToastNavigatorObserver()],//1.注册路由观察者
      home: BotToastInit(  //2.初始化BotToast
          child: XxxxPage()
      ),
    );

4. 使用BotToast #

BotToast.showText(text:"xxxx");  //弹出一个文本框;
BotToast.showSimpleNotification(title: "init"); //弹出简单通知Toast
BotToast.showLoading(); //弹出一个加载动画
//弹出一个定位Toast
BotToast.showAttachedWidget(
    attachedWidget: (_) => Card(
          child: Padding(
            padding: const EdgeInsets.all(8.0),
            child: Icon(
              Icons.favorite,
              color: Colors.redAccent,
            ),
          ),
        ),
    duration: Duration(seconds: 2),
    target: Offset(520, 520));

🐧1.1.0版本说明 #

  • 主要对showAttachedWidget方法进行了增强,现在支持更多方向,定位更准确了。

  • PreferDirection.BelowPreferDirection.Upside被废弃了,可以改用表达更清晰的topCenter,和bottomCenter来代替,且效果完全一致。这两个枚举将会在下个大版本被删除!

  • showAttachedWidgetpreferDirection 只是期望的方向,实际的位置可能因为空间不足而遭到调整

  • 实际调整顺序可以拿topLeft来进行说明,如果上方空间不足则调整为bottomLeft,然后左边空间不足的话就再判断右边的空间是否充足,充足的话结果为bottomRight,不充足最终结果为bottomCenter

🐨注意事项 #

  • 如果你项目有多个[Navigator],请将该BotToastNavigatorObserver添加到[Navigator.observers]

  • [ToastBuilder]方法生成widget时,请确保生成的Widget背景不会吸收点击事件,例如[Scaffold],[Material]都会默认占满整个父空间, 并且会吸收事件(就算透明也是这种情况),具体例子可看[material.dart->_RenderInkFeatures class->hitTestSelf method] 如果真的要生成,可以考虑使用[IgnorePointer],如果没有遵守规则,将会时某些功能失效例如[allowClick]功能就会失效

  • 如果你在项目中使用了[MaterialApp.navigatorKey]参数请在改变[MaterialApp.navigatorKey]时请调用reInit重新初始化

  @override
  void initState() {
    Future.delayed(Duration(seconds: 1), //模拟点击改变GlobalKey<NavigatorState>
        (){
          setState(() {
            navigatorState=GlobalKey<NavigatorState>();
            BotToast.reInit(()=>navigatorState.currentState);
          });
        }
    );
    super.initState();
  }

更详细的实现细节请看bot_toast是怎样炼成的


🐹主要Api文档 #

区域图 #

  _________________________________
|          MainContent            |
|                                 |
|                                 |
|      ___________________        |
|     |                   |       |
|     |    ToastContent   |       |
|     |___________________|       |
|_________________________________|

通用参数说明 #

参数说明
toastBuilder生成需要显示的Widget的函数 (typedef ToastBuilder = Widget Function(CancelFunc cancelFunc);)
key代表此Toast的一个凭证,凭此key可以删除当前key所定义的Widget
groupKey代表此Toast在那个分组的key,
duration持续时间,如果为null则不会去定时关闭,如果不为null则在到达指定时间时自动关闭
crossPage是否跨页面显示,如果为true,则该Toast会跨越多个Route显示,如果为false则在当前Route发生变化时,会自动关闭该Toast,例如[Navigator.push]-[Navigator.pop]等
allowClick是否在该Toast显示时,能否正常点击触发事件
clickClose是否在点击屏幕触发事件时自动关闭该Toast
ignoreContentClick是否忽视ToastContext区域如果为true时,用户点击该ToastContext区域时,用户可以的点击事件可以正常到达到Page上,换一句话说就是透明的(即便是Toast背景颜色不是透明),如果为false,则情况反之
onlyOne表示是否该分组内是否在同一时间里只存在一个Toast,区分是哪一个组是按照[groupKey]来区分的
backgroundColorMainContent区域的背景颜色

1.BotToast.showSimpleNotification #

显示简单的通知Toast #
参数是否必须默认值说明
title标题
subTitle副标题
closeIcon关闭按钮的图标
enableSlideOfftrue是否能滑动删除
hideCloseButtonfalse是否隐藏关闭按钮
durationDuration(seconds: 2)duration说明
crossPagetruecrossPage说明
onlyOnetrueonlyOne说明

2.BotToast.showNotification #

显示一个标准的通知Toast #
参数是否必须默认值说明
leading头部
title标题
subTitle副标题
trailing尾部
contentPaddingToastContent区域的内补
durationDuration(seconds: 2)duration说明
crossPagetruecrossPage说明
onlyOnetrueonlyOne说明
enableSlideOfftrue是否能滑动删除

3.BotToast.showCustomNotification #

显示一个自定义的通知Toast #
参数是否必须默认值说明
toastBuildertoastBuilder说明
enableSlideOfftrue是否能滑动删除
durationDuration(seconds: 2)duration说明
crossPagetruecrossPage说明
onlyOnetrueonlyOne说明

4.BotToast.showAttachedWidget #

显示一个定位Toast,该方法可以在某个Widget(一般是Button)或者给定一个offset周围显示 #
参数是否必须默认值说明
attachedBuildertoastBuilder说明
targetContext目标Widget(一般是一个按钮),使用上一般会使用[Builder]包裹,来获取到BuildContext ([target]和[targetContext] 只能二选一)
target目标[Offset],该偏移是以屏幕左上角为原点来计算的 ([target]和[targetContext] 只能二选一)
preferDirection偏好方向,如果在空间允许的情况下,会偏向显示在那边
verticalOffset24垂直偏移跟[preferDirection]有关,根据不同的方向会作用在不用的方向上
enableSafeAreatrue如果为true则toast确保不会显示在app状态栏上面(意味着是安全的),false则反之
durationduration说明
onlyOnefalseonlyOne说明
allowClicktrueallowClick说明
ignoreContentClickfalseignoreContentClick说明
backgroundColorColors.transparentbackgroundColor说明

5.BotToast.showText #

显示一个标准文本Toast #
参数是否必须默认值说明
text需要显示的文本
contentColorColors.black54ToastContent区域背景颜色
borderRadiusBorderRadius.all(Radius.circular(8))ToastContent区域圆角
textStyleTextStyle(fontSize: 17, color: Colors.white)字体样式
alignAlignment(0, 0.8)ToastContent区域在MainContent区域的对齐
contentPaddingEdgeInsets.only(left: 14, right: 14, top: 5, bottom: 7)ToastContent区域的内补
backgroundColorColors.transparentbackgroundColor说明
durationDuration(seconds: 2)duration说明
onlyOnetrueonlyOne说明
crossPagetruecrossPage说明
clickClosefalseclickClose说明

6.BotToast.showCustomText #

显示一个自定义的文本Toast #
参数是否必须默认值说明
toastBuildertoastBuilder说明
durationDuration(seconds: 2)duration说明
crossPagetruecrossPage说明
onlyOnefalseonlyOne说明
clickClosefalseclickClose说明
ignoreContentClickfalseignoreContentClick说明
backgroundColorColors.transparentbackgroundColor说明

7.BotToast.showLoading #

显示一个标准的加载Toast #
参数是否必须默认值说明
durationduration说明
crossPagetruecrossPage说明
clickClosefalseclickClose说明
allowClickfalseallowClick说明
backgroundColorColors.black26backgroundColor说明

8.BotToast.showCustomLoading #

显示一个自定义的加载Toast #
参数是否必须默认值说明
toastBuildertoastBuilder说明
ignoreContentClickfalseignoreContentClick说明
clickClosefalseclickClose说明
allowClickfalseallowClick说明
crossPagefalsecrossPage说明
durationduration说明
backgroundColorColors.black26backgroundColor说明

9.BotToast.showEnhancedWidget #

显示一个增强Toast,该方法可以让Toast自带很多特性,例如定时关闭,点击屏幕自动关闭,离开当前Route关闭等等 #
参数是否必须默认值说明
toastBuildertoastBuilder说明
keykey说明
groupKeygroupKey说明
ignoreContentClickfalseignoreContentClick说明
clickClosefalseclickClose说明
onlyOnefalseonlyOne说明
allowClicktrueallowClick说明
crossPagetruecrossPage说明
closeFunc该函数参数主要目的使Toast关闭之做一些处理例如触发关闭前调用[AnimationController]来启动并等待动画后再关闭
warpWidget一个wrap函数,可以用来warp MainContent区域,例如[showCustomLoading]就包裹了一个动画让MainContent区域也具有动画
durationduration说明
backgroundColorColors.transparentbackgroundColor说明

10.BotToast.showWidget #

显示一个Widget在屏幕上,该Widget可以跨多个页面存在 #
参数是否必须默认值说明
toastBuildertoastBuilder说明
keykey说明
groupKeygroupKey说明

[0.0.1]

  • 只是显示Widget到屏幕

[0.0.2]

  • 添加Loading Toast

[1.0.0]

  • 1.支持弹出Notification Toast
  • 2.支持某个Widget 显示
  • 3.对已有的功能进行重构,增强各个方法

[1.0.0+1]

  • 更新文档及在线例子

[1.0.0+2]

  • 更新文档及在线例子

[1.0.1]

  • Toast关闭后,清理向BotToastNavigatorObserver注册的函数

[1.0.2]

  • 放宽init重复初始化检查的程度
  • 替换scheduleFrame方法为ensureVisualUpdate

[1.0.3]

  • 修复当pop所有Route再push Route会出现Bug
  • 加固了当项目使用MaterialApp.navigatorKey,能使用reInit重新初始化

[1.1.0]

  • 主要对showAttachedWidget方法进行了增强,现在支持更多方向,定位更准确了。

  • PreferDirection.BelowPreferDirection.Upside被废弃了,可以改用表达更清晰的topCenter,和bottomCenter来代替,且效果完全一致。这两个枚举将会在下个大版本被删除!

  • showAttachedWidgetpreferDirection 只是期望的方向,实际的位置可能因为空间不足而遭到调整

  • 实际调整顺序可以拿topLeft来进行说明,如果上方空间不足则调整为bottomLeft,然后左边空间不足的话就再判断右边的空间是否充足,充足的话结果为bottomRight,不充足最终结果为bottomCenter

  • 对于preferDirection=xxxCenter的情况,其交叉轴的偏移将会忽略

example/README.md

example #

cd example
flutter create .
flutter run

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  bot_toast: ^1.1.0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:bot_toast/bot_toast.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
70
Health:
Code health derived from static analysis. [more]
98
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
84
Learn more about scoring.

We analyzed this package on Aug 21, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19
  • Flutter: 1.7.8+hotfix.4

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Health suggestions

Fix lib/src/toast_widget.dart. (-2.48 points)

Analysis of lib/src/toast_widget.dart reported 5 hints:

line 124 col 25: This function has a return type of 'Future

line 333 col 41: 'Upside' is deprecated and shouldn't be used.

line 333 col 82: 'Below' is deprecated and shouldn't be used.

line 339 col 39: 'Upside' is deprecated and shouldn't be used.

line 341 col 45: 'Below' is deprecated and shouldn't be used.

Format lib/bot_toast.dart.

Run flutter format to format lib/bot_toast.dart.

Format lib/src/bot_toast_init.dart.

Run flutter format to format lib/src/bot_toast_init.dart.

Fix additional 3 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/src/key_board_safe_area.dart (Run flutter format to format lib/src/key_board_safe_area.dart.)
  • lib/src/toast.dart (Run flutter format to format lib/src/toast.dart.)
  • lib/src/toast_navigator_observer.dart (Run flutter format to format lib/src/toast_navigator_observer.dart.)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.6 1.1.7
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test