Flutter Toast 鸿蒙使用指南

最新推荐文章于 2025-12-22 11:35:37 发布

原创最新推荐文章于 2025-12-22 11:35:37 发布 · 596 阅读

17 ·

CC 4.0 BY-SA版权

文章标签：

#flutter #harmonyos #华为

1. 插件介绍

fluttertoast 是一个功能强大的 Flutter 吐司（Toast）库，它提供了两种使用方式：一种不需要 BuildContext，另一种需要 BuildContext。该插件支持在应用界面上显示临时的消息提示，可用于向用户反馈操作结果或重要信息。

主要功能特性：

两种使用模式：支持不需要 BuildContext 和需要 BuildContext 的两种使用方式
跨平台支持：适配 Android、iOS、Web 等多个平台，现在也支持 OpenHarmony
丰富的配置选项：支持自定义消息内容、显示时长、位置、背景颜色、文字颜色等
自定义 Toast：支持完全自定义 Toast 的 UI 和行为
Toast 队列：支持 Toast 消息的排队显示
灵活控制：支持移除单个 Toast 或清除整个队列

2. 插件使用

2.1 包的引入

由于这是一个自定义修改版本的三方库，需要以 Git 形式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  fluttertoast:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_fluttertoast.git"
dev_dependencies:
  fluttertoast_ohos:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_fluttertoast.git"
      path: "ohos"

配置完成后，执行以下命令获取依赖：

flutter pub get

2.2 API 的调用

fluttertoast 提供了两种使用方式，分别适用于不同的场景：

2.2.1 不需要 BuildContext 的 Toast

这种方式使用简单，不需要上下文，但功能相对有限。

import 'package:fluttertoast/fluttertoast.dart';

// 显示短时间 Toast
Fluttertoast.showToast(
  msg: "This is Short Toast",
  toastLength: Toast.LENGTH_SHORT,
  gravity: ToastGravity.BOTTOM,
  timeInSecForIosWeb: 1,
);

// 显示长时间 Toast
Fluttertoast.showToast(
  msg: "This is Long Toast",
  toastLength: Toast.LENGTH_LONG,
  fontSize: 18.0,
);

// 显示居中的 Toast
Fluttertoast.showToast(
  msg: "This is Center Short Toast",
  toastLength: Toast.LENGTH_SHORT,
  gravity: ToastGravity.CENTER,
  timeInSecForIosWeb: 1,
);

// 显示顶部的 Toast
Fluttertoast.showToast(
  msg: "This is Top Short Toast",
  toastLength: Toast.LENGTH_SHORT,
  gravity: ToastGravity.TOP,
  timeInSecForIosWeb: 1,
);

// 显示带颜色的 Toast
Fluttertoast.showToast(
  msg: "This is Colored Toast",
  toastLength: Toast.LENGTH_SHORT,
  backgroundColor: Colors.red,
  textColor: Colors.white,
);

// 取消所有 Toast
Fluttertoast.cancel();

参数说明：

参数	说明	默认值
msg	显示的消息内容（必填）	-
toastLength	Toast 显示时长（Toast.LENGTH_SHORT 或 Toast.LENGTH_LONG）	Toast.LENGTH_SHORT
gravity	Toast 显示位置（ToastGravity.TOP、CENTER 或 BOTTOM）	ToastGravity.BOTTOM
timeInSecForIosWeb	iOS 和 Web 平台上的显示时长（秒）	1
backgroundColor	背景颜色	null
textColor	文字颜色	null
fontSize	文字大小	null
webShowClose	Web 平台是否显示关闭按钮	false
webBgColor	Web 平台的背景颜色（十六进制颜色）	linear-gradient(to right, #00b09b, #96c93d)
webPosition	Web 平台的显示位置（left、center 或 right）	right

2.2.2 需要 BuildContext 的 Toast

这种方式需要上下文，但提供了更强大的功能和完全的自定义能力。

初始化

在 MaterialApp 中配置 FToastBuilder：

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

GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

void main() => runApp(
      MaterialApp(
        builder: FToastBuilder(),
        home: MyApp(),
        navigatorKey: navigatorKey,
      ),
    );

创建并初始化 FToast 实例

late FToast fToast;

@override
void initState() {
  super.initState();
  fToast = FToast();
  fToast.init(navigatorKey.currentContext!);
}

创建自定义 Toast 组件

Widget toast = Container(
  padding: const EdgeInsets.symmetric(horizontal: 24.0, vertical: 12.0),
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(25.0),
    color: Colors.greenAccent,
  ),
  child: Row(
    mainAxisSize: MainAxisSize.min,
    children: [
      Icon(Icons.check),
      SizedBox(
        width: 12.0,
      ),
      Text("This is a Custom Toast"),
    ],
  ),
);

显示自定义 Toast

// 显示自定义 Toast
_showToast() {
  fToast.showToast(
    child: toast,
    gravity: ToastGravity.BOTTOM,
    toastDuration: Duration(seconds: 2),
  );
}

// 使用 PositionedToastBuilder 自定义位置
_showBuilderToast() {
  fToast.showToast(
    child: toast,
    toastDuration: Duration(seconds: 2),
    positionedToastBuilder: (context, child) {
      return Positioned(
        child: child,
        top: 16.0,
        left: 16.0,
      );
    },
  );
}

// 显示可关闭的 Toast
_showToastCancel() {
  Widget toastWithButton = Container(
    padding: const EdgeInsets.symmetric(horizontal: 24.0, vertical: 12.0),
    decoration: BoxDecoration(
      borderRadius: BorderRadius.circular(25.0),
      color: Colors.redAccent,
    ),
    child: Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        Expanded(
          child: Text(
            "This is a Custom Toast with Close Button",
            softWrap: true,
            style: TextStyle(
              color: Colors.white,
            ),
          ),
        ),
        IconButton(
          icon: Icon(
            Icons.close,
            color: Colors.white,
          ),
          onPressed: () {
            fToast.removeCustomToast();
          },
        )
      ],
    ),
  );

  fToast.showToast(
    child: toastWithButton,
    gravity: ToastGravity.CENTER,
    toastDuration: Duration(seconds: 5),
  );
}

Toast 队列管理

// 显示多个 Toast（会排队显示）
_queueToasts() {
  fToast.showToast(
    child: toast,
    gravity: ToastGravity.CENTER,
    toastDuration: Duration(seconds: 2),
  );
  fToast.showToast(
    child: toast,
    gravity: ToastGravity.BOTTOM,
    toastDuration: Duration(seconds: 2),
  );
  // 可以继续添加更多 Toast...
}

// 移除当前显示的 Toast
_removeToast() {
  fToast.removeCustomToast();
}

// 清除所有排队的 Toast
_removeAllQueuedToasts() {
  fToast.removeQueuedCustomToasts();
}

3. 约束与限制

3.1 兼容性

在以下版本中已测试通过：

Flutter: 3.7.12-ohos-1.0.6; SDK: 5.0.0(12); IDE: DevEco Studio: 5.0.13.200; ROM: 5.1.0.120 SP3;

3.2 注意事项

不需要 BuildContext 的 Toast 在 Android 11 及以上版本有一些限制，只有 msg 和 toastLength 属性有效，其他属性会被忽略。
需要 BuildContext 的 Toast 提供了更强大的自定义能力，但需要正确配置 MaterialApp 的 builder 和 navigatorKey。
在使用 Toast 时，应注意不要过度使用，以免影响用户体验。