Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

支持深层链接

从 1.2.0 版开始，Navigation 3 支持使用 DeepLinkRequest 和 DeepLinkMatcher 类深层链接到应用中的目的地。

如需在应用中支持深层链接，请完成以下步骤：

在 AndroidManifest.xml 中定义 intent 过滤器，以指定应用可以处理哪些 URI。
创建 DeepLinkMatcher 实例，以将传入请求映射到导航键。
在 activity 的 onCreate 或 onNewIntent 方法中匹配传入请求，并相应地更新返回堆栈。

创建 `DeepLinkRequest`

DeepLinkRequest 表示传入的深层链接。它包含一个 DeepLinkUri 和可选的 RequestExtras，其中包含其他信息，例如 intent 操作或 MIME 类型。

// Create a request with a String URI
val request = DeepLinkRequest(uri = "https://www.example.com/home")

// Create a request from a DeepLinkUri
val deepLinkUri = DeepLinkUri("https://www.example.com/home")
val requestFromUri = DeepLinkRequest(uri = deepLinkUri)

// Create a request with a URI and action
val requestWithAction = DeepLinkRequest(
    uri = "https://www.example.com/home",
    extras = DeepLinkRequest.actionExtra("android.intent.action.VIEW")
)

// Create a request with URI, action and mimeType
val requestWithMimeType = DeepLinkRequest(
    uri = "https://www.example.com/image",
    extras = requestExtras {
        put(DeepLinkRequest.ActionExtrasKey, "android.intent.action.VIEW")
        put(DeepLinkRequest.Companion.MimeTypeExtrasKey, "image/png")
    }
)DeepLinkSnippets.kt

提供 `DeepLinkRequest` 项额外服务

如需存储与深层链接相关的其他信息，请使用 RequestExtras 类。为了使定义和实例化 extra 具有类型安全性，该库提供了 RequestExtrasKey 接口和 requestExtras DSL。

此外，该库还提供了两个 extra 键和关联的辅助程序：

MimeTypeExtrasKey：用于存储 MIME 类型 String。
ActionExtrasKey（仅限 Android）：用于存储 Intent 的操作 String。

val extras: RequestExtras = requestExtras {
    put(DeepLinkRequest.Companion.MimeTypeExtrasKey, "application/json")
    put(DeepLinkRequest.ActionExtrasKey, Intent.ACTION_VIEW)
}

// Access typed values using the get operator
val mimeType: String? = extras[DeepLinkRequest.Companion.MimeTypeExtrasKey]
val action: String? = extras[DeepLinkRequest.ActionExtrasKey]

// Create extras using helper functions and combine them
val mimeTypeExtras: RequestExtras = DeepLinkRequest.mimeTypeExtra("application/json")
val combinedExtras: RequestExtras = extras + DeepLinkRequest.actionExtra(Intent.ACTION_VIEW)DeepLinkSnippets.kt

如需定义自己的自定义 extra，请使用类型化泛型实现 RequestExtrasKey 接口：

// Define a custom typed key:
object CampaignIdExtrasKey : RequestExtrasKey<String>

val customExtras: RequestExtras = requestExtras {
    put(CampaignIdExtrasKey, "123")
}

val campaignId: String? = customExtras[CampaignIdExtrasKey]DeepLinkSnippets.kt

您还可以使用 emptyRequestExtras() 构建空实例，或使用 + (plus) 和 - (minus) 运算符组合 extra。

通过 `Intent` 创建 `DeepLinkRequest`

在 Android 上，您可以直接通过 Intent 创建 DeepLinkRequest。以这种方式构建时，DeepLinkRequest 的构建方式如下：

uri 是从 intent 的 data 字段中复制的。
如果不是 null，则 MIME 类型和操作 extra 会根据相应的 intent 字段进行设置。
所有具有非 null 值的 intent.extras 都会在 DeepLinkRequest.IntentExtrasKey 中保存为 SavedState。
使用 extras 参数提供的任何其他 extra 都会添加。

object CampaignIdExtrasKey : RequestExtrasKey<String>

val intent = Intent(Intent.ACTION_VIEW).apply {
    data = Uri.parse("https://www.example.com/item/42")
    type = "application/json"
    putExtra("user_id", "123")
}

val request = DeepLinkRequest(
    intent = intent,
    extras = requestExtras {
        put(CampaignIdExtrasKey, "spring_promo")
    }
)

// The resulting DeepLinkRequest contains:
val uri = request.uri // "https://www.example.com/item/42"
val action = request.extras[DeepLinkRequest.ActionExtrasKey] // "android.intent.action.VIEW"
val mimeType = request.extras[DeepLinkRequest.Companion.MimeTypeExtrasKey] // "application/json"
val intentExtras: SavedState? =
    request.extras[DeepLinkRequest.IntentExtrasKey]
val userId: String? = intentExtras?.read { getStringOrNull("user_id") } // "123"
val campaignId: String? = request.extras[CampaignIdExtrasKey] // "spring_promo"DeepLinkSnippets.kt

创建 `DeepLinkMatcher` 实例

DeepLinkMatcher 会将传入的 DeepLinkRequest 实例映射到可添加到应用返回堆栈的导航键。Navigation 3 提供了三个内置匹配器：UriDeepLinkMatcher 用于基于模式的 URI 匹配，StaticKeyDeepLinkMatcher 用于基本链接，BackStackMatcher 用于构建合成返回堆栈。该库还支持自定义匹配器，以应对内置匹配器未涵盖的用例。

如需了解详情，请参阅创建 DeepLinkMatcher。

添加 intent 过滤器

如需让深层链接能够启动您的 activity，您必须在应用的 AndroidManifest.xml 中定义匹配的 <intent-filter> 元素。如需了解详情，请参阅为传入链接添加 intent 过滤器。

匹配传入请求

创建 DeepLinkMatcher 实例后，您可以在 activity 中匹配传入请求。

如需匹配传入请求，请完成以下步骤：

实例化 DeepLinkMatcher 实例。
明确或使用多重绑定整理所有 DeepLinkMatcher 实例。
根据传入的 Intent 创建 DeepLinkRequest。
将请求与所有匹配器进行匹配，并找到最佳匹配项。
根据比赛结果创建返回堆栈。

// 1. Instantiate your DeepLinkMatcher instances.
val homeMatcher = StaticKeyDeepLinkMatcher(HomeKey, listOf(DeepLinkMatcher.actionFilter(Intent.ACTION_VIEW)))

val userProfileMatcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/users/{id}"),
    serializer<UserProfileKey>()
).withBackStack { matchResult ->
    listOf(HomeKey, matchResult.key)
}

val telMatcher = TelDeepLinkMatcher()

// 2. Collate all of your DeepLinkMatcher instances.
//    Note: Collating matchers with different generic types requires wildcards,
//    erasing the specific generic types.
val deepLinkMatchers: List<DeepLinkMatcher<*, *>> = listOf(
    homeMatcher,
    userProfileMatcher,
    telMatcher
)

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...

        // 3. Create a DeepLinkRequest from the incoming Intent
        val request = DeepLinkRequest(intent = intent)

        // 4. Match the request against all matchers and find the best match.
        //    Because DeepLinkMatcher.MatchResult implements Comparable, you can
        //    use maxOrNull() to find the best match.
        val matchResult = deepLinkMatchers
            .mapNotNull { it.match(request) } // List<DeepLinkMatcher.MatchResult<*>>
            .maxOrNull() // DeepLinkMatcher.MatchResult<*>?

        // 5. Create the back stack from the match result (or fall back to a default).
        val backStack: List<NavKey> = when (matchResult) {
            // If no match is found, use the default back stack (e.g., HomeKey)
            null -> listOf(HomeKey)
            // If a BackStackMatchResult is found, use the back stack from the result
            is BackStackMatchResult<*, *> -> {
                // Because star-projected matchers erase the key type, cast the back stack to List<NavKey>.
                @Suppress("UNCHECKED_CAST")
                matchResult.backStack as List<NavKey>
            }
            // Otherwise, use the key from the match result to make a single-item back stack
            else -> listOf(matchResult.key as NavKey)
        }
    }
}DeepLinkSnippets.kt

支持深层链接 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

创建 DeepLinkRequest

提供 DeepLinkRequest 项额外服务

通过 Intent 创建 DeepLinkRequest

创建 DeepLinkMatcher 实例