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

flutter_floating 표지
패키지 상세v2.0.2

flutter_floating

Flutter 권한 없이 떠다니는 창, 가볍고 유연하며 완전히 기능하는 Flutter 플로팅 윈도우 컴포넌트입니다.

AndroidiOSWebmacOSWindowsLinux
30일 다운로드
2천
좋아요
46
Pub 점수
130

패키지 설치

flutter pub add flutter_floating

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

Flutter Floating은 Flutter 애플리케이션에서 권한 없이 플로팅 창을 가능하게 하는 가볍고 유연한 패키지입니다. 개발자는 드래그 가능하고 크기 조절이 가능하며 사용자 정의 가능한 오버레이 창을 만들 수 있으며, 여러 플랫폼에서 다른 앱 콘텐츠 위에 표시할 수 있습니다. 계산기, 메모, 채팅 위젯과 같은 지속적인 UI 요소가 필요한 도구에 적합하며 특별한 시스템 권한 없이 작동합니다. 이 패키지는 Android, iOS, Web, macOS, Windows, Linux를 지원하여 크로스플랫폼 개발에 매우 유용합니다.

사용 사례

  • 지속적인 화면 도구
  • 빠른 액세스 오버레이
  • 플로팅 노트 작성 인터페이스
  • 실시간 데이터 모니터링
  • 미니어처 앱 컴포넌트

주요 기능

  • 드래그 및 크기 조정 가능한 창
  • 크로스 플랫폼 지원
  • 시스템 권한이 필요하지 않습니다
  • 사용자 정의 가능한 외관
  • 가볍고 성능이 뛰어남
  • 기존 앱과의 간편한 통합

적합한 대상

  • 유틸리티 앱을 개발하는 개발자
  • 생산성 도구의 제작자
  • 다중 플랫폼 배포를 목표로 하는 팀
  • 항상 보이는 UI 요소가 필요한 앱

고려 사항

  • 일부 전체 화면 모드와 충돌할 수 있습니다
  • 저사양 장치에 대한 성능 영향
  • 시스템 수준의 창 동작에 대한 제한된 제어
  • UI 혼잡을 피하기 위해 신중한 설계가 필요합니다

원본 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 개

소스 저장소

이 패키지를 사용하는 프로젝트

아직 데이터가 없습니다.