搜索插件、代码仓与 APP 分类

flutter_floating 封面
插件详情v2.0.2

flutter_floating

Flutter 无权限浮窗,一个轻量、灵活且功能完整的 Flutter 浮窗组件。

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
2000
喜欢数
46
Pub 分数
130

安装插件

flutter pub add flutter_floating

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

Flutter Floating 是一个轻量且灵活的包,可在 Flutter 应用中实现无需权限的浮动窗口。它允许开发者创建可拖动、可调整大小且可自定义的覆盖窗口,这些窗口可以在其他应用内容之上显示,并支持多个平台。非常适合需要持久 UI 元素(如计算器、便签或聊天小部件)的工具,且无需特殊系统权限即可运行。该包支持 Android、iOS、Web、macOS、Windows 和 Linux,使其在跨平台开发中具有高度的通用性。

适合场景

  • 持久的屏幕工具
  • 快速访问叠加层
  • 浮动便签式笔记界面
  • 实时数据监控
  • 微型应用组件

主要特点

  • 可拖动和可调整大小的窗口
  • 跨平台支持
  • 无需系统权限
  • 可自定义外观
  • 轻量且高效
  • 与现有应用轻松集成

适合对象

  • 开发实用应用程序的开发者
  • 生产力工具的创作者
  • 针对多平台部署的团队
  • 需要始终可见的用户界面元素的应用程序

使用建议

  • 可能与某些全屏模式冲突
  • 对低端设备的性能影响
  • 对系统级窗口行为的控制有限
  • 需要精心设计以避免用户界面杂乱

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

pub version license pub downloads stars issues

flutter_floating

轻量且可全局管理的 Flutter 悬浮窗组件,支持拖拽、吸附、位置缓存、多指交互与屏幕旋转适配,适合悬浮工具、快捷入口与悬浮播放器等场景。

快速预览:

在线预览(Web Demo) · 建议先运行 example/ 查看完整示例


English documentation

If you prefer English, see the translated docs:

为什么选择本库

  • 轻量无侵入:仅通过 FloatingOverlay 或 FloatingManager 即可在页面或全局插入悬浮窗。
  • 场景覆盖广:支持吸附/回弹、位置缓存、禁止滑动区域、多指交互、运行时显示/隐藏与旋转适配。
  • 易于调试:每个悬浮窗可开启日志分组,方便排查位置与事件问题。

一行安装

在 pubspec.yaml 中添加:

dependencies:
  flutter_floating: newVersion

然后运行:

flutter pub get

主要特性(按场景说明)

  • 全局/页面双模式:可通过 FloatingManager 全局管理多个悬浮窗,或在单页面内以 Stack 插入。
  • 灵活吸附与回弹:可配置吸附方向、吸附距离(支持负值超出屏幕)、吸附速度与自动吸附开关。
  • 位置控制与缓存:通过代码调整偏移,支持启用/禁用位置缓存(打开/关闭保持位置)。
  • 完善事件回调:按下/移动/抬起/移动结束/打开/关闭等回调,便于埋点或自定义交互。
  • 可配置可拖拽性与隐藏策略:运行时切换是否允许拖动、动态隐藏/显示、动画期间位置自适配。
  • 运行中可手动设置偏移位置,吸附位置,以及吸附边缘切换等等
  • 禁止滑动区域支持:可指定顶部/底部或自定义区域为不可拖动区域。
  • 自适应屏幕旋转与窗口变化:在旋转或窗口尺寸变化时保证位置合理。

快速开始(最小示例)

全局 floating
late FloatingOverlay floating = FloatingOverlay(
  const FloatingIcon(),
  slideType: FloatingEdgeType.onRightAndTop,
  right: -20,
  params: FloatingParams(snapToEdgeSpace: -20),
  top: 100,
);

@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) {
    floating.open(context);
  });
}

//关闭
floating.close()

//销毁
floating.dispose()
单页面使用

将在页面内创建并自动打开一个悬浮窗:

late FloatingOverlay floating = FloatingOverlay(
  const FloatingIcon(),
  slideType: FloatingEdgeType.onRightAndTop,
  right: -20,
  params: FloatingParams(snapToEdgeSpace: -20),
  top: 100,
);

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: Stack(
      fit: StackFit.expand,
      children: [floating.getFloating()],
    ),
  );
}

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

全局创建及管理

floatingManager.createFloating(
    "key_1",
    FloatingOverlay(
      const FloatingIcon(),
      slideType: FloatingEdgeType.onRightAndTop,
      right: -20,
      params: FloatingParams(snapToEdgeSpace: -20),
      top: 100,
    ),
);

//获取
floatingManager.getFloating("key_1");
//关闭
floatingManager.closeFloating("key_1");
//销毁
floatingManager.disposeFloating("key_1");
//....

更多示例请查看仓库 example/。

API 快速索引

  • FloatingOverlay:页面内浮窗封装,创建/打开/关闭/定位单个悬浮窗的入口(适合局部使用)。
  • FloatingManager:全局管理器,用于创建、获取、关闭和销毁全局悬浮窗(通过 key 管理)。
  • FloatingCommonController:通用控制器,提供显示/隐藏、移动、设置位置、吸附与动画控制等 API,适合代码层面动态控制悬浮窗行为。
  • FloatingParams:配置参数集合,控制吸附、缓存、透明度、边距、回弹与可拖拽性等行为。
  • FloatingListener:事件回调容器,便于将多个回调以对象形式注册到悬浮窗上。

示例:添加监听器

var listener = FloatingEventListener()
  ..openListener = () => print('open')
  ..closeListener = () => print('close')
  ..downListener = (x, y) => print('down: \$x,\$y')
  ..moveListener = (x, y) => print('move: \$x,\$y')
  ..upListener = (x, y) => print('up: \$x,\$y')
  ..moveEndListener = (x, y) => print('move end: \$x,\$y');

floatingOne.addFloatingListener(listener);

运行示例(本地)

  1. 克隆仓库并进入 example/:
git clone https://github.com/kngLv/flutter_floating.git
cd flutter_floating/example
flutter pub get
flutter run -d <device>
  1. 在线预览(Web): https://knglv.github.io/flutter_floating/web/

常见问题

常见问题以及解决办法

兼容性

  • Flutter >= 2.10(请以 pubspec.yaml 中的环境为准)
  • 支持平台:Android / iOS / web / macOS(取决于示例与平台实现)

日志与调试

创建悬浮窗时通过 FloatingParams.isShowLog 控制是否打印分组日志,便于按悬浮窗 key 查看行为。

贡献

欢迎 Issues、PR 与示例改进。建议:

  • 提交 Issue 时附上截图/录屏与最小复现代码。
  • PR 请基于 main 分支并附加简要说明与 demo(若改动行为请同步更新 example)。

联系与许可

作者:LvKang(邮箱:lv345_y@163.com)

许可:MIT(详见仓库 LICENSE)


感谢你使用 flutter_floating,如果它帮到了你,欢迎点个 Star ⭐️!

所属分类

依赖

依赖清单 1 项

源码仓库

使用此插件的项目

暂无相关数据。