How to solve deprecation of TooltipDefaults.rememberRichTooltipPositionProvider()

近日，Jetpack Compose 官方在 Material 3 库中正式标记 TooltipDefaults.rememberRichTooltipPositionProvider() 为弃用状态（Deprecated）。这一变动直接影响大量使用 RichTooltip（富文本工具提示）组件的开发者。本文详细解读弃用原因及完整迁移方案，帮助开发者平滑过渡。

背景：为什么弃用？

在 Compose Material 3 的早期版本中，TooltipDefaults.rememberRichTooltipPositionProvider() 专门用于为 RichTooltip 提供定位逻辑，与普通 Tooltip 的 rememberTooltipPositionProvider() 形成两条独立的 API 路径。这种设计目的在于区分富文本工具提示和基础工具提示的增强功能，但实际维护中发现，两者在定位算法上高度重叠，冗余的 API 不仅增加了学习成本，也导致开发者频繁混淆。

Google 团队在 Compose 1.6.0 及后续版本中决定统一 API 入口，将功能合并到基础 rememberTooltipPositionProvider() 中，通过参数配置即可实现同样的富文本定位效果。这一决策符合 Compose “极简且可组合” 的设计哲学。

主要变化：新 API 替代方案

弃用后，开发者应使用统一的 TooltipDefaults.rememberTooltipPositionProvider() 方法，并传入适当的 tooltipType 参数来指定是否为富文本工具提示。具体签名如下：

@Composable
fun rememberTooltipPositionProvider(
    tooltipType: TooltipType = TooltipType.Plain,
    alignment: TooltipAlignment = TooltipAlignment.Popup,
    ... // 其他可选参数
)

其中： - TooltipType.Plain：对应原基础工具提示（默认）。 - TooltipType.Rich：对应原富文本工具提示。

此外，原 rememberRichTooltipPositionProvider() 中的 arrowEnabled、offset 等个性化参数已被整合进新的公共参数集中，并以更一致的方式设置。

迁移步骤详解

1. 更新 Compose BOM 版本

确保项目使用 Compose BOM 版本 2024.06.00 或更高（稳定版），例如：

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.06.00"))
}

2. 替换方法调用

旧代码：

val positionProvider = rememberRichTooltipPositionProvider(
    alignment = TooltipAlignment.Center,
    arrowEnabled = true
)

新代码：

val positionProvider = TooltipDefaults.rememberTooltipPositionProvider(
    tooltipType = TooltipType.Rich,
    alignment = TooltipAlignment.Center
)

注意：新 API 中 arrowEnabled 已被移除，因为富工具提示默认显示箭头。若需强制隐藏，需额外设置 showArrow = false。

3. 调整 Tooltip 状态管理

RichTooltipState 依然保留，但建议与新的 rememberTooltipPositionProvider 配合使用。若之前直接使用 rememberRichTooltipState() 创建状态，无需改动。只需将位置提供者替换即可。

4. 测试与验证

运行应用，检查工具提示的弹出位置、箭头显示及富文本渲染是否正常。特别关注不同屏幕尺寸和布局下的适配效果。

常见问题与最佳实践

Q：弃用后旧代码还能用吗？
短期内仍可编译，但会显示编译警告。建议在下一个主要版本更新前完成迁移，以便适配未来的 API 移除。

Q：是否影响 Plain Tooltip 的使用？
不影响。Plain Tooltip 只需省略 tooltipType 参数或显式传入 TooltipType.Plain，代码保持不变。

Q：新增参数对性能是否有影响？
无显著影响。Compose 的重组机制保证了参数变化时仅重新计算位置，不会导致额外开销。

最佳实践： - 尽量复用 rememberTooltipPositionProvider，避免在可组合项内重复创建。 - 如需全局统一定位风格，可封装自定义可组合函数，内部调用 rememberTooltipPositionProvider 并固定参数。 - 配合 TooltipBox 使用时，确保传递给 positionProvider 的实例唯一，防止重组闪烁。

总结

TooltipDefaults.rememberRichTooltipPositionProvider() 的弃用是 Compose 工具提示 API 走向统一的重要一步。开发者应主动拥抱变化，及时迁移到统一的 rememberTooltipPositionProvider() 方法，并通过 tooltipType 参数区分富文本与基础工具提示。这不仅简化代码，还能获得未来版本中更一致的维护支持。

迁移过程只需替换方法签名并调整少数参数，总体工作量较小。建议团队将此项更新纳入下一次技术债务清理的待办清单，保持代码与现代 Compose 实践同步。

本文基于 Compose Material 3 1.3.0 版本编写，具体 API 细节请参考官方发布说明。