FloatingX
English · 文档 Wiki · DeepWiki
FloatingX 一个灵活且强大的悬浮窗解决方案。
鸿蒙原生版见 FloatingX-Harmony，使用 ArkTS / ArkUI，最低兼容 API 12。支持范围与验证状态见鸿蒙仓库。
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 浮窗见
快速开始。
📖 文档
完整文档在 GitHub Wiki（中文标题为中文页，英文标题为英文页）：
🏄♀️ 效果图
| App 级：拖动 / 吸附 / 换页跟随 |
系统级：回到桌面仍在 |
旋转：锚点保持 |
 |
 |
 |
| 尺寸变化：锚点不动（#187） |
Compose：计数跨页存活 |
局部浮窗：ViewGroup / Fragment |
 |
 |
 |
📱 Demo
app 模块是完整的示例与回归工程，./gradlew app:installDebug 即可安装，页面清单见
Demo 说明。
👍 感谢
基础 悬浮窗View 的初版实现思想源自 EnFloatingView 的
FloatingMagnetView，
并在其之上进行了彻底的重构与演变；导航栏测量部分代码来自 wenlu，并在其之上增加了更多机型适配。
关于我
欢迎关注我的公众号，期待一同进步；使用上有问题也可以加我微信 Petterpx。
评论