Voyager 中处理带 @Serializable 参数屏幕的保存问题

问题背景

在使用 Voyager 导航框架时，开发者可能会遇到一个常见问题：当屏幕类包含带有 @Serializable 注解的参数时，在 Android 设备上按下 Home 键会导致应用崩溃。这是因为 Android 系统在保存和恢复 Activity 状态时，默认使用 Parcelable 机制，而 Kotlin 的 @Serializable 注解并不直接兼容这一机制。

错误分析

典型的错误日志会显示 BadParcelableException，指出系统无法序列化包含 @Serializable 注解类的屏幕对象。例如，当屏幕类定义如下时：

class IllustDetailScreen(private val illust0: Illust) : Screen

@Serializable
data class Illust(
    val id: Int,
    val title: String,
)

系统会抛出异常，因为 Android 的保存机制期望所有可保存对象都实现 Parcelable 接口，而 @Serializable 并不自动提供这一实现。

解决方案

1. 使用 moko-parcelize 库

对于需要跨平台兼容的情况，推荐使用 moko-parcelize 库。这个库提供了多平台（包括 Android 和 iOS）的 @Parcelize 注解实现。

首先，在 build.gradle 中添加依赖：

implementation("dev.icerock.moko:parcelize:0.9.0")

然后修改你的类和数据结构：

@Parcelize
class IllustDetailScreen(private val illust0: Illust) : Screen, Parcelable

@Parcelize
@Serializable
data class Illust(
    val id: Int,
    val title: String,
): Parcelable

2. 处理特殊数据类型

如果你的数据类中包含 Kotlin 标准库中的特殊类型（如 kotlinx.datetime.Instant 或 kotlinx.datetime.LocalDateTime），moko-parcelize 也提供了支持。你需要为这些类型编写自定义的 Parceler 实现。

例如，对于 Instant 类型：

object InstantParceler : Parceler<Instant> {
    override fun create(parcel: Parcel): Instant {
        return Instant.fromEpochMilliseconds(parcel.readLong())
    }

    override fun Instant.write(parcel: Parcel, flags: Int) {
        parcel.writeLong(toEpochMilliseconds())
    }
}

@Parcelize
@Serializable
data class Event(
    val time: Instant,
    @IgnoredOnParcel
    val description: String
) : Parcelable {
    companion object : Parcelable.Creator<Event> {
        override fun createFromParcel(parcel: Parcel): Event {
            val time = InstantParceler.create(parcel)
            val description = parcel.readString() ?: ""
            return Event(time, description)
        }

        override fun newArray(size: Int): Array<Event?> {
            return arrayOfNulls(size)
        }
    }
}

3. 替代方案：ViewModel SavedState

另一种解决方案是使用 ViewModel 的 SavedState 功能。这种方法将状态保存与导航分离，更适合复杂场景：

class IllustDetailViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    private val illust: Illust by savedStateHandle.getStateFlow("illust", Illust(0, ""))

    // ViewModel逻辑...
}

class IllustDetailScreen(private val illustId: Int) : Screen {
    @Composable
    override fun Content() {
        val viewModel: IllustDetailViewModel = getViewModel()
        // 使用viewModel中的状态
    }
}

最佳实践建议

1. 简单场景：对于简单的数据结构和跨平台需求，优先使用 moko-parcelize
2. 复杂数据类型：对于包含特殊类型的数据结构，实现自定义 Parceler
3. 大型应用：考虑使用 ViewModel SavedState 来管理复杂状态
4. 性能考虑：避免在导航参数中传递大型对象，考虑使用 ID 或轻量级引用

总结

在 Voyager 中处理带 @Serializable 参数的屏幕保存问题时，关键在于理解 Android 的状态保存机制和 Kotlin 多平台序列化的差异。通过合理选择解决方案，可以确保应用在各种场景下都能正确保存和恢复状态，提供流畅的用户体验。