FloatingX Android 免权限悬浮窗，支持全局、局部悬浮，支持边缘吸附、回弹、自 @codeKK AndroidOpen Source Website

FloatingX

Introduction: Android 免权限悬浮窗，支持全局、局部悬浮，支持边缘吸附、回弹、自定义动画、位置保存、窗口化及分屏后位置修复等。Android without permission suspension window, support global, local suspension, support edge adsorption, rebound, custom animation, position saving, windowing and split-screen position repair.

More: Author ReportBugs

Tags:

English · 文档 Wiki · DeepWiki

FloatingX 一个灵活且强大的悬浮窗解决方案。

3.0 为全新重写版本，按模块拆分、按需依赖；API 与 2.x 不兼容，升级请看从 2.x 迁移。

👏 特性

支持 JetPack Compose，浮窗自带 ViewModelStore / SavedState，换页不丢
支持 系统浮窗、应用内浮窗、局部浮窗（ViewGroup / Fragment / Activity）
支持换页 不重建，浮窗位置、状态、动画跟着 Activity 走
支持 锚点定位，旋转、内容尺寸变化不跑偏
支持 边缘吸附、半隐藏、边界设置、越界不裁剪
支持 拖动区域、长按拖动，与列表滚动 冲突处理
支持自定义 显示 / 隐藏动画
支持 保存历史位置 及还原（按 tag + 屏幕方向）
支持 黑名单与白名单，指定页面禁止显示浮窗
支持 Modal 浮窗，拦截外部点击
支持 系统浮窗权限 自动 / 手动申请，被拒 自动降级 为应用内浮窗
支持宿主未就绪时调用 show / moveTo，就绪后自动执行
支持 kotlin DSL 构建，及对 Java 的友好兼容（Builder）
完善的日志系统，enableLog(tag) 即可看到 Fx 运行过程

👨‍💻‍ 依赖方式

dependencies {
    implementation "io.github.petterpx:floatingx-core:3.0.0"      // 其它模块会自动带上
    implementation "io.github.petterpx:floatingx-app:3.0.0"       // App 级全局浮窗（跟随 Activity）
    implementation "io.github.petterpx:floatingx-system:3.0.0"    // 系统级浮窗（WindowManager + 权限）
    implementation "io.github.petterpx:floatingx-scope:3.0.0"     // 局部浮窗（Activity / ViewGroup / Fragment）
    implementation "io.github.petterpx:floatingx-compose:3.0.0"   // Jetpack Compose 内容
}

只引用到的模块就行，core 会跟着带上。minSdk 21（compose 模块 23），清单里的权限和 provider 都在库里声明好了。

🚀 快速开始

val control = FloatingX.install("music") {
    layout(R.layout.fx_card)
    anchor(FxGravity.CENTER_END, dy = 120f)
    margin(top = 24f, bottom = 24f)
    adsorb(FxAdsorb.Edges(setOf(FxEdge.START, FxEdge.END), halfHide = FxHalfHide(0.3f)))
    persist(FxSpStorage(app))
    enableLog("Fx-demo")
    appHost(app) {
        // 传 Class 而非类名字符串：按 isInstance 匹配，子类一起命中
        blacklist(SplashActivity::class.java)
    }
}
control.show()

Java 写法、系统级浮窗、局部浮窗、Compose 浮窗见快速开始。