PAYATHON 2026

Compose Navigation 2.8.0+ 如何传递自定义 Parcelable?

数据小许

可以为 UserData 实现 NavType<UserData>,再通过 composable<Route.DetailsScreen>(typeMap = ...) 注册。这个 NavType 要处理对象在 Bundle 中的存取,也要负责对象与路由字符串之间的转换。仅有 @Parcelize 还不够。自定义参数类型说明

为什么需要字符串转换

Navigation 2.8.0 的 Type-Safe Navigation 支持用对象调用 navigate(),但底层仍需要将参数转换成路由字符串。Parcelable 负责在 Bundle 中存取对象,不提供路由字符串的编码和解析规则。

自定义 NavType 需要实现以下方法:

  • put():把对象写入 Bundle。
  • get():从 Bundle 读取对象。
  • serializeAsValue():把对象转换成适合放入路由的字符串。
  • parseValue():从路由参数字符串还原对象。

serializeAsValue() 默认使用 toString(),通常无法还原自定义对象,因此需要覆盖该方法。NavType API

1. 定义可序列化的 UserData

示例使用 JSON 作为路由参数的字符串格式,因此要给 UserData 同时添加 @Serializable 和 @Parcelize。其中的 id、name 仅用于演示,请替换成实际字段。

import android.os.Parcelable
import kotlinx.parcelize.Parcelize
import kotlinx.serialization.Serializable

@Serializable
@Parcelize
data class UserData(
    val id: String,
    val name: String
) : Parcelable

@Serializable
sealed class Route {
    @Serializable
    data class DetailsScreen(val userData: UserData) : Route()
}

项目需要启用 org.jetbrains.kotlin.plugin.serialization 和 kotlin-parcelize,并添加 kotlinx-serialization-json 依赖。Serialization 编译插件的版本应与项目使用的 Kotlin 版本一致。

这里的 @Serializable 来自 kotlinx.serialization,与 java.io.Serializable 无关。当前 JSON 实现需要为 UserData 添加该注解,因为 Parcelable 本身不会生成 JSON serializer。

2. 实现自定义 NavType

import android.net.Uri
import android.os.Bundle
import androidx.core.os.BundleCompat
import androidx.navigation.NavType
import kotlinx.serialization.json.Json
import kotlin.reflect.KType
import kotlin.reflect.typeOf

object UserDataNavType : NavType<UserData>(
    isNullableAllowed = false
) {
    override fun put(bundle: Bundle, key: String, value: UserData) {
        bundle.putParcelable(key, value)
    }

    override fun get(bundle: Bundle, key: String): UserData? {
        bundle.classLoader = UserData::class.java.classLoader
        return BundleCompat.getParcelable(
            bundle,
            key,
            UserData::class.java
        )
    }

    override fun serializeAsValue(value: UserData): String {
        val json = Json.encodeToString(UserData.serializer(), value)
        return Uri.encode(json)
    }

    override fun parseValue(value: String): UserData {
        return Json.decodeFromString(UserData.serializer(), value)
    }
}

val userDataTypeMap: Map<KType, NavType<*>> = mapOf(
    typeOf<UserData>() to UserDataNavType
)

在 serializeAsValue() 中调用 Uri.encode(),可以处理 JSON 中可能出现的 /、?、& 等字符。Navigation 会在调用 parseValue() 前完成 URI 解码,所以这里直接解析 JSON,无需再次调用 Uri.decode()。编码与解析示例

BundleCompat.getParcelable() 用于兼容不同 Android 版本,要求 AndroidX Core 1.10.0 或更高版本。读取自定义 Parcelable 前,需按该 API 对自定义类型的要求设置对应的 classLoader。BundleCompat API

3. 注册目的地、跳转并读取参数

在已有 NavHost 的 builder 中注册目的地,可以将注册逻辑封装成 NavGraphBuilder 扩展函数:

import androidx.compose.material3.Text
import androidx.navigation.NavController
import androidx.navigation.NavGraphBuilder
import androidx.navigation.compose.composable
import androidx.navigation.toRoute

fun NavGraphBuilder.detailsDestination() {
    composable<Route.DetailsScreen>(
        typeMap = userDataTypeMap
    ) { backStackEntry ->
        val route = backStackEntry.toRoute<Route.DetailsScreen>()
        val userData = route.userData

        Text(text = userData.name)
    }
}

fun openDetails(navController: NavController, userData: UserData) {
    navController.navigate(
        Route.DetailsScreen(userData = userData)
    )
}

在 NavHost 的 builder 中调用 detailsDestination(),并在按钮点击等导航事件中调用 openDetails(navController, userData)。

typeMap 的键是参数类型 typeOf<UserData>(),不是路由类型 typeOf<Route.DetailsScreen>(),也不是参数名 "userData"。Navigation Compose API

读取参数时使用具体目的地类型 toRoute<Route.DetailsScreen>()。NavBackStackEntry.toRoute() 会使用目的地已注册的参数类型,无需再次传入 typeMap。Type-Safe Navigation 用法

在 ViewModel 中读取时的区别

通过 SavedStateHandle.toRoute() 读取参数时,需要显式传入相同的 typeMap:

import androidx.lifecycle.SavedStateHandle
import androidx.lifecycle.ViewModel
import androidx.navigation.toRoute

class DetailsViewModel(
    savedStateHandle: SavedStateHandle
) : ViewModel() {
    val userData: UserData = savedStateHandle
        .toRoute<Route.DetailsScreen>(typeMap = userDataTypeMap)
        .userData
}

SavedStateHandle.toRoute() 的自定义类型映射参数在 Navigation 2.8.0 中可用。Navigation 发布记录

注意事项

上面的实现针对非空 UserData,因此使用 isNullableAllowed = false。如果参数改为 UserData?,还需要实现 NavType<UserData?>,定义 null 的编码和解析方式,并将映射键改为 typeOf<UserData?>();仅修改布尔值是不够的。

不要直接用 NavType.ParcelableType(UserData::class.java) 替代上述实现。它支持 Parcelable 存取,但其 parseValue() 会抛出 UnsupportedOperationException,不能直接用于这里的路由字符串解析。ParcelableType API

如果无法为 UserData 添加 @Serializable,需要自行提供适用的 serializer 或使用可序列化的参数模型;上面调用 UserData.serializer() 的代码不能直接套用。

对于体积较大或持续变化的业务对象,通常更适合只传递 userId,由目标页面从数据层加载对象。路由中传入的对象是跳转时的数据快照,后续数据更新不会自动同步到该参数。复杂数据传递建议

备注:内容仅供参考。