Voyager导航库中解决屏幕重复压栈的IllegalArgumentException异常

问题背景

在使用Voyager导航库进行多屏幕管理时，开发者可能会遇到java.lang.IllegalArgumentException: Key PlayerScreen:transition was used multiple times异常。这种情况通常发生在尝试将同一个屏幕实例多次压入导航栈时，系统无法区分这些相同屏幕实例的标识。

核心原理

Voyager的导航栈管理机制要求每个屏幕实例必须具有唯一标识。默认情况下，系统会使用类名作为屏幕标识的基础。当同一个屏幕类被多次实例化并压入栈时，如果没有显式指定区分标识，就会导致键值冲突。

解决方案

要为相同类型的屏幕实例创建唯一标识，可以通过以下方式实现：

1. 自定义屏幕键值：在屏幕类的构造函数中添加唯一性参数
2. 使用key属性：在导航时显式指定唯一键

// 方法1：通过构造函数传递唯一ID
class PlayerScreen(
    private val mediaId: String
) : Screen {
    override val key: String = "${javaClass.simpleName}:$mediaId"
}

// 使用时
navigator.push(PlayerScreen("unique_media_id_123"))

// 方法2：直接覆盖key属性
navigator.push(
    PlayerScreen().withKey("PlayerScreen_${System.currentTimeMillis()}")
)

最佳实践建议

1. 业务标识优先：尽量使用业务相关的唯一标识（如媒体ID、用户ID等），而非随机值
2. 键值格式化：建议采用类名:唯一标识的格式，便于调试和维护
3. 状态恢复考虑：确保键值在配置变更后仍能保持一致性
4. 避免时间戳：除非必要，不建议使用时间戳作为唯一标识，可能影响状态恢复

深入理解

这种设计模式体现了导航库的两个重要原则：

1. 栈内实例唯一性原则：导航栈中的每个实例必须可唯一识别
2. 状态可恢复性原则：通过稳定键值确保屏幕状态能够正确保存和恢复

理解这些原则有助于开发者更好地设计屏幕导航流程，避免类似问题的发生。