快速开始

快速开始

本页讲清楚两件事：依赖哪几个模块，以及四种宿主各自最少写几行能跑起来。 每种宿主的详细用法在各自的页面里。

模块与依赖

模块	用途	minSdk	传导给使用方的下限
floatingx-core	状态机、锚点定位、手势、feature、注册表、FxControl	21	androidx.core 1.13.1 → compileSdk ≥ 34
floatingx-app	AppHost：跟随前台 Activity 的全局浮窗	21	同 core
floatingx-system	SystemHost：WindowManager 窗口、悬浮窗权限、键盘适配	21	同 core
floatingx-scope	ViewGroupHost / FragmentHost：局部浮窗（androidx.fragment 为 compileOnly）	21	同 core
floatingx-compose	compose {} 内容、FxComposeOwner、stateFlow() / positionFlow()	23	compose-ui 1.11.4 → compileSdk ≥ 35、lifecycle 2.10.0

所有模块的 Kotlin metadata 跟随 Kotlin 2.2，使用方 Kotlin ≥ 2.1。

Gradle

dependencies {
    implementation "io.github.petterpx:floatingx-core:3.0.0"      // 其它模块都会自动带上，只用 core 自定义 Host 时才需要单独引
    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 会被其它四个模块以 api 传递带上，通常不必单独声明；其余按需。不用系统浮窗就不会引入 WindowManager 相关代码，不用 Compose 就不会引入 Compose 依赖。

不需要配置 AndroidManifest

app / system 模块自带清单：floatingx-app 用一个 ContentProvider 在进程启动时注册 Activity 跟踪器， 所以 install 写在任何时机都能拿到当前前台 Activity；floatingx-system 已声明 SYSTEM_ALERT_WINDOW 权限与透明的权限申请页，接入方不需要自己配置任何东西。

版本要求

• minSdk 21：core / app / system / scope 四个模块。
• minSdk 23：floatingx-compose（Compose 自身的下限）。
• compileSdk ≥ 34（core 传导），用到 floatingx-compose 时 compileSdk ≥ 35。
• Kotlin ≥ 2.1、Java 17 工具链。

四种宿主的最小上手

App 级全局浮窗

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

黑白名单、filter、挂载点、theme、Java Builder 见 App 级全局浮窗。

系统级浮窗

FloatingX.install("sys") {
    layout(R.layout.fx_input)
    anchor(FxGravity.TOP_START, dx = 24f, dy = 200f)
    adsorb(FxAdsorb.Edges(setOf(FxEdge.START, FxEdge.END)))
    systemHost(app) {
        permission(FxPermissionStrategy.auto())          // 默认：自动弹页申请
        // 权限被拒时降级为 App 级浮窗（相当于 2.x 的 SYSTEM_AUTO）
        fallback(AppHost.builder(app).build())
    }
}.show()

权限三策略、降级、layoutParams 定制、键盘 / 返回键、在 Service 里安装见 系统级浮窗。

局部浮窗

// Activity：挂在 android.R.id.content 上（必须在 setContentView 之后调用）
val actFx = fxScope("scope-act") {
    layout(R.layout.fx_card)
    anchor(FxGravity.BOTTOM_END)
    persist(FxSpStorage(this@ScopeHostActivity))
}
actFx.show()

挂到任意 ViewGroup、Fragment 内使用、Java 入口见 局部浮窗。

Compose

FloatingX.install("compose") {
    compose { control ->
        val vm: CounterViewModel = viewModel()                        // 归浮窗自己的 ViewModelStore
        var count by rememberSaveable { mutableIntStateOf(0) }        // 容器 detach 也不丢
        val state by control.stateFlow().collectAsState()             // FxState
        val pos by control.positionFlow().collectAsState()            // 内容左上角的屏幕坐标
        Surface(shape = CircleShape, modifier = Modifier.size(110.dp)) {
            Column(Modifier.clickable { count++; vm.clicks++ }) {
                Text("count $count")
                Text("${pos.x.toInt()},${pos.y.toInt()} $state")
            }
        }
    }
    anchor(FxGravity.CENTER_START, dy = -100f)
    appHost(app)
}.show()

FxComposeOwner、跨页存活、stateFlow() / positionFlow() 见 Compose 浮窗。

下一步

锚点 / margin / 越界 / safeArea / 吸附 / 手势 / 动画 / modal / 持久化等配置项在 配置项； FxControl / FxListener / FloatingX 注册表的方法速查在 API 速查。

---

返回 Home · 相关：配置项 · API 速查 · 从 2.x 迁移