Skip to content

配置项

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

配置

FxConfig 不可变。Kotlin 用 FxConfigScope DSL（FloatingX.install(tag) {} 收的是 FxInstallScope，比 FxConfigScope 多一个 host）；Java 用 FxConfig.builder(FxContent.layout(id))。 装好之后用 control.update {} 基于旧配置局部修改，未显式设置的项沿用旧值。

能力一览

能力 API 说明
锚点定位 anchor(FxGravity, dx, dy) 9 个 gravity；dx/dy 是从所依附的边向内的偏移；RTL 下 START/END 自动翻转
边界留白 margin(left, top, right, bottom) 可用区四边的额外留白
安全区 safeArea = true/false 是否避开状态栏 / 导航栏 / 刘海
越界 overflow(top, bottom, left, right) 允许内容超出可用区的哪些边
边缘吸附 adsorb(FxAdsorb.Edges(edges, halfHide, rebound)) 四向可选；FxAdsorb.horizontal()/vertical()/all()/none()
半隐 FxHalfHide(start, end) 贴左 / 贴右可用不同比例
越界回弹 FxAdsorb.Edges(rebound = true) 拖动中允许暂时出界，松手回弹
拖动模式 gesture { drag = FxDrag.IMMEDIATE / AFTER_LONG_PRESS / DISABLED } 按下即拖 / 长按后拖 / 禁拖
起拖区域 gesture { dragRegion = FxRegion.child(R.id.header) } 也可 FxRegion.rect(...) 或自定义
子 view 优先级 gesture { childPriority = FxChildPriority.AUTO / PARENT / CHILD } 内容里有 RecyclerView 时，纵向手势归谁
触摸透传 gesture { touchable = false } 浮窗完全不吃触摸，点它等于点下层
点击 / 长按 gesture { click = …; longPress = …; longPressTimeout = … } 预设：FxGesture.Normal / ClickOnly / DisplayOnly / LongPressToDrag
动画 animation(FxAnimations.fade()) / scale() / 自定义 FxAnimation show / hide 动画
位置持久化 persist(FxSpStorage(context)) key 含 tag 与屏幕方向，横竖屏分别记忆；也可实现 FxStorage
黑白名单 appHost(app) { blacklist(X::class.java); whitelist(...); filter { … } } Class 版按 isInstance 匹配，子类一起命中；也支持类全名字符串
挂载点 appHost(app) { attachTo(AppAttachTarget.DECOR / CONTENT) } 默认 DecorView（拖动范围真正全屏）
Modal modal(enabled, dismissOnOutsideTouch) 浮窗显示中时拦截内容之外的触摸（隐藏后自动放行），可选点外部自动 hide（只对 app / scope 生效）
键盘 systemHost(app) { keyboard(R.id.etInput) } 系统窗口默认不可聚焦，触到这些 EditText 才临时可聚焦
返回键 systemHost(app) { onBackPressed { true } } 仅键盘弹起期间窗口可聚焦，才收得到
多浮窗 FloatingX.install(tag) {} / controls() / uninstall(tag) 全局浮窗按 tag 隔离，同 tag 再 install 会先 cancel 旧的
日志 enableLog("Fx-demo") adb logcat | grep "Fx-"；不调用则完全静默
自定义行为 addFeature(FxFeature) 容器行为插件，内置 Location / Gesture / Animation / ModalScrim

黑白名单 / 挂载点属于 App 级全局浮窗，键盘 / 返回键属于 系统级浮窗，下面只展开 host 无关的配置项。

内容

layout(R.layout.fx_card)          // 布局 id
view(someView)                    // 现成的 view
view { ctx -> DemoContent.card(ctx) }   // 按 context 现场创建（推荐：换 host / 换主题时能重建）
content(FxContent.layout(id))     // 直接给一个 FxContent

三种内容对应 FxContent.Layout / FxContent.Static / FxContent.Provider， Java 侧是 FxContent.layout(id) / FxContent.view(v) / FxContent.provider {}。 装好之后可以整体换内容或改内容里的 view，见 API 速查。

锚点与偏移

anchor(gravity, dx = 0f, dy = 0f)。存的是「贴哪条边 + 偏移」而不是左上角坐标，所以内容尺寸变化 （文字变长、展开收起）时贴着的那条边不动。dx/dy 是从所依附的边向内的偏移，单位 dp。 9 个 FxGravity：TOP_START / TOP_CENTER / TOP_END / CENTER_START / CENTER / CENTER_END / BOTTOM_START / BOTTOM_CENTER / BOTTOM_END；START / END 是逻辑方向，RTL 布局下自动翻转。

margin / safeArea / overflow

margin(top = 24f, bottom = 24f)   // 可用区四边的额外留白（Kotlin 具名参数，按需给）
safeArea = false                  // 默认 true：避开状态栏 / 导航栏 / 刘海
overflow(top = true, left = true) // 允许内容超出可用区的哪些边，默认四边都不允许

三者共同决定「可用区」：屏幕（或容器）减去 safe area，再减去 margin；overflow 放开指定边的限制。

吸附、半隐与回弹

adsorb(FxAdsorb.Edges(setOf(FxEdge.START, FxEdge.END), halfHide = FxHalfHide(0.3f), rebound = true))
adsorb(FxAdsorb.horizontal())     // 也有 vertical() / all() / none()

halfHide 给 FxHalfHide(start, end) 时贴左、贴右可用不同比例；rebound = true 允许拖动中暂时 出界、松手回弹（2.x 里这是恒开的，3.0 可关）。吸附到哪条边可以通过 FxListener.onPositionChanged(control, anchor) 拿到，见 API 速查。

手势

gesture {
    drag = FxDrag.AFTER_LONG_PRESS            // IMMEDIATE / AFTER_LONG_PRESS / DISABLED
    dragRegion = FxRegion.child(R.id.header)  // 也可 FxRegion.rect(...) 或自定义（fun interface）
    childPriority = FxChildPriority.AUTO      // AUTO / PARENT / CHILD：与可滚动子 view 的冲突策略
    touchable = true                          // false = 完全透传，点它等于点下层
    click = true
    longPress = true
    longPressTimeout = 0L                     // 0 = 用系统的 ViewConfiguration.getLongPressTimeout()
}
gesture(FxGesture.LongPressToDrag)            // 或直接用预设

预设：FxGesture.Normal（默认）/ ClickOnly / DisplayOnly / LongPressToDrag， Java 侧是 @JvmField 静态字段，要细调就 new FxGesture(...)。

动画

animation(FxAnimations.fade())     // 或 FxAnimations.scale()，都可传 duration
animation(null)                    // 关闭动画（默认就是没有）

自定义实现 FxAnimation，覆写 showAnimator(view) / hideAnimator(view) 返回 Animator。

Modal

modal(enabled = true, dismissOnOutsideTouch = false)

浮窗显示中时拦截内容之外的触摸，隐藏后自动放行；dismissOnOutsideTouch = true 时点外部自动 hide。 只对 app / scope 两类 host 生效（系统窗口的遮罩由 WindowManager 的 flags 决定）。

位置持久化

persist(FxSpStorage(app))          // 也可 persist(null) 关闭

存储 key 由框架生成为 "$tag:$orientation"，横竖屏分别记忆。也可以自己实现 FxStorage （save(key, anchor) / load(key) / clear(key)）接自己的存储。清掉记住的位置用 FxStorage.clear(key)。局部浮窗 tag 留空时不持久化，见 局部浮窗。

日志

enableLog("Fx-demo")               // 不调用则完全静默

库自己的日志 tag 是 Fx-<scope>（如 Fx-system），所以统一用 adb logcat | grep "Fx-"。

自定义行为

addFeature(MyFeature())

FxFeature 是容器行为插件，内置 Location / Gesture / Animation / ModalScrim 四个。 新增行为优先加一个 feature，而不是往内容里塞代码，写法见 架构设计。

装好之后改配置

control.update { anchor(FxGravity.BOTTOM_END); gesture { drag = FxDrag.DISABLED } }   // 局部改配置

update {} 用的是同一套 FxConfigScope DSL。完整的 FxControl 方法见 API 速查。

返回 Home · 相关：快速开始 API 速查 架构设计 App 级全局浮窗

FloatingX

文档

English

Clone this wiki locally