패키지, 저장소 및 앱 카테고리 검색

GitHub 저장소kngLv/flutter_floating

flutter_floating

Flutter 권한 없이 플로팅 윈도우, 가볍고 유연하며 기능이 완전한 Flutter 플로팅 윈도우 컴포넌트입니다. Flutter Permissionless Floating Window, a lightweight, flexible, and fully functional Flutter floating window component.

flutter_floating 프로젝트 이미지
스타
82
포크
28
최근 푸시(UTC)
2026. 1. 22.
프로젝트 상태
활성

원본 README

아래는 영문 원문 스냅샷입니다. 최신 내용은 GitHub에서 확인하세요.

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 ⭐️!

L.k GitHub avatar
GitHub 작성자

L.k ↗

언어DartSwiftHTMLKotlinObjective-C

분류

이 저장소가 배포한 패키지

사용 중인 의존성

의존성 목록 5 개

프로젝트에 맞는 저장소를 선택하려면?

사용 목적에 따라 검색하고 개발 활동을 비교한 뒤 원본 저장소에서 요구 사항을 확인하세요.

  1. 이름, 작성자 또는 설명으로 검색하고 기술 주제로 범위를 좁힙니다.
  2. 스타, 포크, 최근 푸시를 함께 비교하세요. 스타는 관심의 지표이며 품질을 보장하지 않습니다.
  3. 사용하기 전에 GitHub에서 README, 라이선스, Issues를 확인하세요.

출처 및 관리

“A repository is the most basic element of GitHub.”

GitHub Docs — About repositories ↗