移动开发UI组件【免费下载链接】lithoA declarative framework for building efficient UIs on Android.项目地址https://gitcode.com/gh_mirrors/li/litho点击查看免费下载Litho 是 Android 上基于声明式组件树的 UI 框架本文聚焦其官方提供的 Tooltip API——LithoTooltipController与LithoTooltip接口讲解如何在无需 View 查找view search的前提下将一个PopupWindow或自定义悬浮视图精确锚定到组件树中的任意组件上。读完本文你将掌握 Handle 锚定机制、点击与可见性触发两种接入方式、PopupWindow 快捷调用以及框架底层如何把 Handle 映射为锚点矩形坐标的完整原理。本文主体内容整理自仓库文档 docs/tooltips.md并结合 litho-core 源码与 sample、测试用例做了源码级验证与扩充。为什么需要 Litho 自己的 Tooltip API在传统 Android 开发中要在一个 View 上弹出悬浮窗通常需要拿到该 View 的实例把它作为PopupWindow.showAsDropDown(anchor)的锚点。但在 Litho 的渲染模型里绝大多数组件Component根本不会被包装成独立的 ViewLitho 会做 View 扁平化View Flattening多个组件可能共享一个宿主 View即使某个组件最终映射到了 View普通业务代码也无法直接从组件实例拿到对应的 View 引用。因此如果想对组件树中看不见摸不着的某个组件弹出工具提示就不能沿用传统思路。Litho 为此提供了LithoTooltipController工具类作为官方的 Tooltip API它允许你直接以某个 Component 为锚点弹出悬浮提示全程不需要处理 View 查找逻辑。这套 API 的全部实现位于 litho-core/src/main/java/com/facebook/litho/LithoTooltipController.kt 与 litho-core/src/main/java/com/facebook/litho/LithoTooltip.kt仓库 sample 目录中也提供了完整的 Java 与 Kotlin 可运行示例。核心 API 速览LithoTooltip 接口 与 LithoTooltipControllerLithoTooltip自定义悬浮内容的唯一接口LithoTooltip是一个只含单个抽象方法的接口在源码中声明为 Kotlinfun interface即函数式接口// litho-core/src/main/java/com/facebook/litho/LithoTooltip.kt fun interface LithoTooltip { fun showLithoTooltip(container: View?, anchorBounds: Rect, xOffset: Int, yOffset: Int) }实现者需要实现showLithoTooltip方法方法参数含义如下参数含义container包裹锚点 Component 的宿主 ViewLithoView或其子宿主anchorBounds锚点组件相对宿主 View 的边界矩形Rect坐标系以宿主 View 左上角为原点xOffset/yOffset相对默认位置的横向、纵向偏移量用于微调悬浮提示位置值得注意源码注释明确要求不要直接调用该方法它只应该由 Litho 框架即LithoTooltipController调用以确保传入的参数正确无误业务代码应始终经由LithoTooltipController暴露的方法触发。正因为框架只依赖这一个方法你完全可以用自定义 View、动画层、乃至自定义绘制逻辑来实现自己的悬浮提示而不必局限于PopupWindow。LithoTooltipController锚定与触发的统一入口LithoTooltipController在源码中是一个 Kotlinobject单例所有方法均带JvmStaticJava 与 Kotlin 均可直接调用。当前版本提供的主要 API 分为三组1. 锚定到根组件Root ComponentshowTooltipOnRootComponent(c, popupWindow, xOffset, yOffset)从根组件左下角开始按指定偏移展示给定PopupWindowshowTooltipOnRootComponent(c, lithoTooltip)与showTooltipOnRootComponent(c, lithoTooltip, xOffset, yOffset)以自定义LithoTooltip实现锚定到根组件。2. 锚定到指定 Handle推荐showTooltipOnHandle(c, lithoTooltip, handle, xOffset 0, yOffset 0)以自定义LithoTooltip实现锚定到某个Handle标识的组件偏移量默认 0showTooltipOnHandle(c, popupWindow, handle, xOffset, yOffset)PopupWindow快捷重载免去手写LithoTooltip实现showTooltipOnHandle(c, handle, showTooltip: (container, anchorBounds) - Unit)直接传入 lambda 回调由你自行完成绘制适合无偏移需求的场景。3. 基于 Key 的旧接口已标记废弃showTooltip(context, popupWindow, anchorKey, xOffset, yOffset)等一系列基于anchorKey字符串定位锚点的 API 已被Deprecated标注源码中的废弃提示统一指向showTooltipOnHandle(...)系列。新代码请一律使用 Handle 版本详见下文。用 Handle 标识锚点组件机制与用法找到作为锚点的组件是这套 API 的核心问题。当前设计给出的答案是在锚点组件上挂一个Handle实例。Handle类定义在 litho-core/src/main/java/com/facebook/litho/Handle.kt源码注释明确指出它的用途唯一标识组件用于触发外部事件包括显示LithoTooltip或触发OnTrigger事件。其内部持有stateUpdater与该 handle 关联的StateUpdater用于在多组件树场景下定位正确的组件树例如 Section 列表中的子项触发父级组件的工具提示mountedViewReferenceMountedViewReference引用记录挂载该组件的视图信息。挂载 Handle 有两种语法Java / LayoutSpec 写法在构建组件时调用Component.handle(...)即 litho-core/src/main/java/com/facebook/litho/Component.java 中定义的public T handle(Nullable Handle handle)Kotlin KComponent 写法使用 litho-core/src/main/java/com/facebook/litho/KComponent.kt 中定义的inline fun handle(handle: Handle, crossinline componentLambda: () - Component): Component它会把 handle 设置到 lambda 返回的组件上handle(anchorHandle) { Text(text Tooltip anchor, ...) }另外Kotlin 的ComponentScope还提供了useHandle(vararg inputs: Any?): Handle这个 Hook同样定义在 Handle.kt它基于useCached实现当首次调用或传入的 inputs 发生变化时返回新的、缓存后的Handle实例适合在 KComponent 中声明式地管理 handle 生命周期。实战一Java LayoutSpec 中实现点击触发 可见触发下面是文档 docs/tooltips.md 给出的完整示例当组件可见时、以及当用户点击某个 Text 时分别弹出锚定在另一个 Text 上的工具提示。该示例与仓库 sample 中的 TooltipTriggerExampleComponentSpec.java 结构一致是可直接运行的参考实现LayoutSpec public class TooltipTriggerExampleComponentSpec { OnCreateLayout static Component onCreateLayout(ComponentContext c) { final Handle anchorHandle new Handle(); return Column.create(c) .child( Text.create(c) .text(Click to Trigger show tooltip) .clickHandler(TooltipTriggerExampleComponent.onClick(c, anchorHandle))) .child(Text.create(c).text(Tooltip anchor).handle(anchorHandle)) .visibleHandler(TooltipTriggerExampleComponent.onVisible(c, anchorHandle)) .build(); } OnEvent(ClickEvent.class) static void onClick(ComponentContext c, Param Handle anchorHandle) { TooltipTriggerExampleComponentSpec.showToolTip(c, anchorHandle); } OnEvent(VisibleEvent.class) static void onVisible(ComponentContext c, Param Handle anchorHandle) { // Show a tooltip when the component becomes visible. // NB: Incremental mount must be enabled for the component to receive visibility callbacks. TooltipTriggerExampleComponentSpec.showToolTip(c, anchorHandle); } static void showToolTip(ComponentContext c, Handle anchorHandle) { final LithoTooltip tooltip /* Provide an implementation of LithoTooltip or PopupWindow */; LithoTooltipController.showTooltipOnHandle(c, tooltip, anchorHandle); } }要点拆解锚点声明第二行Text.create(c).text(Tooltip anchor).handle(anchorHandle)把同一个Handle实例挂到目标 Text 上它就是悬浮提示的锚点点击触发通过.clickHandler(...)绑定ClickEvent事件回调中调用showToolTip(c, anchorHandle)可见性触发通过.visibleHandler(...)绑定VisibleEvent。注意示例注释中的提示必须开启增量挂载Incremental Mount组件才能收到可见性回调触发落地showToolTip中把LithoTooltip实现或PopupWindow与 handle 一起交给LithoTooltipController.showTooltipOnHandle。sample 中还展示了如何用 Litho 自身的LithoView构建一个PopupWindow内容粉底白字样式可参考 TooltipTriggerExampleComponentSpec.java 中的createTooltip方法先LithoView.create(c, Column...build())生成内容视图再包一层PopupWindow。实战二PopupWindow 快捷方式免写 LithoTooltip 实现如果悬浮内容就是普通的PopupWindow则完全不必自己实现LithoTooltip。LithoTooltipController.showTooltipOnHandle(c, popupWindow, handle, xOffset, yOffset)这个重载会在内部自动完成适配——源码实现本质上是把showAsDropDown包装成了LithoTooltip函数式接口// litho-core/src/main/java/com/facebook/litho/LithoTooltipController.kt节选 showTooltipOnHandle( c, { container, anchorBounds, x, y - popupWindow.showAsDropDown(container, anchorBounds.left x, anchorBounds.bottom y) }, handle, xOffset, yOffset)也就是说默认行为是以锚点组件左下角为基准、叠加指定的 xOffset/yOffset 后把 PopupWindow 作为下拉dropdown展示。文档中的可见性触发示例随之简化为OnEvent(VisibleEvent.class) static void onVisible( ComponentContext c, Prop PopupWindow tooltip, State Handle anchorHandle) { LithoTooltipController.showTooltipOnHandle(c, tooltip, anchorHandle); }注意此处的anchorHandle是State配合OnCreateInitialState初始化anchorHandle.set(new Handle())才能保证每次布局重建时 handle 实例稳定、且最终挂载到了组件上。仓库 sample 的 Java 版本正是这样组织的。实战三Kotlin KComponent 写法sample 中的 TooltipTriggerExampleKComponent.kt 给出了同功能的 KComponent 实现语法上更简洁class TooltipTriggerExampleKComponent : KComponent() { override fun ComponentScope.render(): Component? { // 用 useCached 缓存 handle 实例保证重建时稳定 val anchorHandle useCached { Handle() } return Column(alignItems YogaAlign.CENTER) { child( Text( text Click to trigger/show tooltip, defStyleAttr android.R.attr.buttonStyle, style Style.padding(horizontal 20.dp, vertical 25.dp).onClick { showToolTip(anchorHandle) })) child( handle(anchorHandle) { Text( text Tooltip anchor, style Style.margin(top 50.dp).onVisible { showToolTip(anchorHandle) }) }) } } private fun ComponentScope.showToolTip(anchorHandle: Handle) { LithoTooltipController.showTooltipOnHandle( context, createTooltip(Example Tooltip), anchorHandle, 0, 0) } private fun ComponentScope.createTooltip(tooltipText: String) PopupWindow( LithoView.create( context, Column(style Style.padding(all 15.dp).backgroundColor(LITHO_PINK)) { child(Text(text tooltipText, textColor Color.WHITE)) }), LinearLayout.LayoutParams.WRAP_CONTENT, LinearLayout.LayoutParams.WRAP_CONTENT, true) ... }可以看到handle(anchorHandle) { ... }声明式地把 handle 挂到锚点组件上点击onClick与可见性onVisible回调共享同一个 handle触发路径与 Java 版完全一致。底层原理Handle 是如何变成锚点矩形的要理解这套 API需要追踪一条完整链路组件挂载 → 布局计算记录 Handle 与矩形 → 控制器查表并回调。第一步布局阶段记录Handle → 锚点矩形每次布局计算时LithoReducer.kt 会遍历渲染树节点对每个带有 Key 或 Handle 的组件记录其绝对边界// litho-core/src/main/java/com/facebook/litho/LithoReducer.kt节选 if (delegateKey ! null || delegate.hasHandle()) { val copyRect Rect(rect) if (delegateKey ! null) { reductionState.componentKeyToBounds[delegateKey] copyRect } if (delegate.hasHandle()) { val handle: Handle? delegate.handle if (handle ! null) { reductionState.componentHandleToBounds[handle] copyRect } } }其中rect来自contentRenderTreeNode?.getAbsoluteBounds(Rect())即组件在挂载坐标系中的绝对边界。这些映射最终存放在ReductionState的componentHandleToBounds字段见 ReductionState.kt并经由 LayoutState.kt 暴露为componentHandleToBounds: MapHandle, Rect供外部查询。第二步控制器查表定位锚点当调用showTooltipOnHandle(c, tooltip, handle, xOffset, yOffset)时见 LithoTooltipController.kt控制器的执行流程是通过handle.mountedViewReference找到挂载视图并要求它是LithoView从LithoView的mountedLayoutState取出componentHandleToBounds映射表用传入的 handle 查表得到anchorBounds: Rect调用lithoTooltip.showLithoTooltip(lithoView, anchorBounds, xOffset, yOffset)完成展示。第三步健壮性保障主线程断言控制器内部调用assertMainThread()保证所有 tooltip 操作发生在主线程LithoTooltipController.kt无效 Handle 上报如果查不到该 handle 对应的锚点组件会通过ComponentsReporter.emitMessage以ERROR级别上报LithoTooltipController:InvalidHandle错误信息形如Cannot find a component with handle ... to use as anchor便于在日志系统中快速定位无效 Key 上报旧的基于 Key 的showTooltip路径同样有对应的LithoTooltipController:InvalidKey错误上报Cannot find a component with key ... to use as anchor。测试验证锚定行为与边界坐标仓库在 litho-it/src/test/com/facebook/litho/LithoTooltipControllerTest.kt 中提供了完整的单元测试覆盖了三类锚点形态测试用例验证内容shows tooltip on Text Spec在Text上挂 handle渲染后调用控制器断言container非空且anchorBounds.top/left为 10对应margin(10.px)的偏移shows tooltip on Row锚点升级为Row容器同样验证边界矩形正确10px marginshows tooltip on KComponent锚点是一个完整的 KComponent100x100 的 Image验证anchorBounds的 left/top/right/bottom 分别等于 0/0/100/100测试中使用了RecordingLithoTooltip记录每次showLithoTooltip(container, anchorBounds, xOffset, yOffset)的调用参数从而精确断言框架传给自定义实现的数据是否正确。这些用例也印证了一个关键事实无论锚点组件是否真正映射为独立 View控制器都能通过 Handle 拿到它在宿主视图中的矩形坐标——这正是这套 API 区别于传统 View 锚定方案的本质。适用范围与已知限制文档 docs/tooltips.md 末尾明确指出当前 API 只支持 View 类悬浮提示View tooltips。也就是说展示层内容目前以PopupWindow或自定义LithoTooltip实现内部仍需挂载在宿主 View 上为主如果未来有需求框架不排除增加 Component 级 tooltip 支持的可能但这一点目前尚未落地设计时需自行评估。此外若采用VisibleEvent触发可见性提示务必确认已开启增量挂载Incremental Mount否则组件不会收到可见性回调该约束在文档与 sample 注释中均有明确标注。参考资料官方文档原文docs/tooltips.md控制器实现litho-core/src/main/java/com/facebook/litho/LithoTooltipController.kt接口定义litho-core/src/main/java/com/facebook/litho/LithoTooltip.ktHandle 与 useHandle Hooklitho-core/src/main/java/com/facebook/litho/Handle.ktHandle 挂载语法Kotlinlitho-core/src/main/java/com/facebook/litho/KComponent.ktJava 示例sample/src/main/java/com/facebook/samples/litho/java/triggers/TooltipTriggerExampleComponentSpec.javaKotlin 示例sample/src/main/java/com/facebook/samples/litho/kotlin/triggers/TooltipTriggerExampleKComponent.kt测试用例litho-it/src/test/com/facebook/litho/LithoTooltipControllerTest.kt赞分享移动开发UI组件【免费下载链接】lithoA declarative framework for building efficient UIs on Android.项目地址https://gitcode.com/gh_mirrors/li/litho点击查看免费下载相关推荐iced 框架 Tooltip 指南基于光标位置的悬浮提示实现与源码原理iced 框架 Tooltip 指南基于光标位置的悬浮提示实现与源码原理 导读 Tooltip悬浮提示是 GUI 中悬停即提示的基础交互组件。本文以前端跨平台UI组件桌面应用PrimeNG Angular SpeedDial 组件完全指南悬浮按钮弹层菜单的实现与定制PrimeNG Angular SpeedDial 组件完全指南悬浮按钮弹层菜单的实现与定制 SpeedDial快速拨号是 PrimeNG 提供的一种悬前端UI组件radix-vue Tooltip 组件实战指南悬浮提示的延迟控制、碰撞感知与无障碍设计radix vue Tooltip 组件实战指南悬浮提示的延迟控制、碰撞感知与无障碍设计 导读 Tooltip工具提示是鼠标悬停或键盘聚焦在某个元素上时弹前端UI组件设计系统上一篇Texture 文档站点本地搭建指南基于 Jekyll 与 GitHub Pages 构建与预览 docs 文档站下一篇visx/react-spring 动画组件实战指南为 visx 坐标轴与网格线注入 react-spring 过渡动画创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
