Skip to content

App 级全局浮窗

Jump to bottom
petterp edited this page Aug 30, 2026 · 1 revision

App 级全局浮窗（AppHost）

floatingx-app 提供的 AppHost：浮窗跟随当前前台 Activity，按 tag 进注册表全局存在。 本页讲黑白名单、挂载点、主题、Java 入口。

是什么

AppHost 把浮窗容器挂到当前前台 Activity 上。换页时不是销毁重建，而是把同一个容器静默 reparent 到新页面 —— engine 状态、feature、动画、内容 view 都不重来，位置也不跳。

floatingx-app 用清单里声明的 ContentProvider 在进程启动时就注册好 Activity 跟踪器， 所以 install 写在 Application.onCreate、某个页面的 onCreate、甚至 Service 里都能拿到当前前台 Activity，不需要手动 setContext。

被黑白名单 / filter 拒绝的页面上，浮窗整体卸下（onHostLost）；回到允许显示的页面时自动挂回来， 显示意图与状态都保留，不需要业务方重新 show()。

完整示例

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()

appHost(app) { … } 花括号里就是 AppHost.Builder，下面几节的开关都写在这里。

黑白名单与 filter

appHost(app) {
    blacklist(SplashActivity::class.java)          // Class：按 isInstance 匹配，子类一起命中
    blacklist("com.x.YActivity")                   // String：类全名精确匹配
    whitelist(MainActivity::class.java)            // 配了白名单，就只在白名单页显示
    filter { activity -> !activity.isFinishing }   // 自定义规则，可多次调用
}
入口 匹配方式
blacklist(vararg Class<out Activity>) 按 isInstance 匹配，父类写一次，子类一起命中（#221）
blacklist(vararg String) 类全名精确匹配
whitelist(vararg Class<out Activity>) / whitelist(vararg String) 配了白名单就只在白名单页显示
filter(AppActivityFilter) 自定义规则；可多次调用，全部通过才显示（fun interface，Java 可写 lambda）

挂载点

appHost(app) { attachTo(AppAttachTarget.CONTENT) }
取值 含义
AppAttachTarget.DECOR 默认。挂 Window 的 DecorView，拖动范围是真正的「全屏」，不受状态栏 / 导航栏 / AppBar 影响
AppAttachTarget.CONTENT 挂 android.R.id.content，浮窗只覆盖内容区

需要把浮窗限制在应用视图范围内时才改成 CONTENT。

主题

App 级浮窗的内容用 Application context 创建，而 Material 组件（MaterialCardView 等）需要 Material 主题，直接用 Application context 会崩。给 host 指定一个主题即可：

appHost(app) { theme(R.style.Theme_App) }

当前挂在哪个 Activity

val activity = control.attachedActivity   // floatingx-app 提供的 FxControl 扩展属性；未挂载时为 null

Java Builder

FxConfig config = FxConfig.builder(FxContent.layout(R.layout.fx_card))
        .anchor(FxGravity.BOTTOM_START, 24f, 120f)
        .margin(16f, 16f, 16f, 16f)
        .adsorb(new FxAdsorb.Edges(EnumSet.of(FxEdge.START, FxEdge.END), new FxHalfHide(0.3f), true))
        .gesture(FxGesture.LongPressToDrag)
        .storage(new FxSpStorage(app))
        .enableLog("Fx-java")
        .build();
AppHost host = AppHost.builder(app)
        .blacklist(SplashActivity.class)
        .filter(activity -> !activity.isFinishing())
        .build();
FxControl control = FloatingX.install("java-app", config, host);
control.show();

Kotlin 的 DSL 入口标了 @JvmSynthetic，Java 侧走 FxConfig.Builder + AppHost.Builder； AppActivityFilter 是 fun interface，可以直接写 lambda。

返回 Home · 相关：快速开始 · 配置项 · 系统级浮窗

FloatingX

文档

English

Clone this wiki locally