为目标创建深度链接

在 Android 中，深度链接是指可直接将您带到应用内特定目标位置的链接。

导航组件允许您创建两种不同类型的深度链接：显式和隐式。

创建显式深度链接

一个显式深度链接 是深度链接的单个实例，它使用 PendingIntent 将用户带到应用内的特定位置。例如，您可能会将显式深度链接作为通知或应用小部件的一部分显示。

当用户通过显式深度链接打开您的应用时，任务返回堆栈将被清除并替换为深度链接目标。当嵌套图表时，还会将每个嵌套级别的起始目标（即层次结构中每个<navigation> 元素的起始目标）添加到堆栈中。这意味着，当用户从深度链接目标按下返回按钮时，他们的导航方式与从入口点进入应用的方式一样，都会返回导航堆栈。

您可以使用 NavDeepLinkBuilder 类来构建 PendingIntent，如下例所示。请注意，如果提供的上下文不是 Activity，则构造函数将使用 PackageManager.getLaunchIntentForPackage() 作为要启动的默认活动（如果可用）。

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent();

默认情况下，NavDeepLinkBuilder 将您的显式深度链接启动到应用清单中声明的默认启动 Activity 中。如果您的 NavHost 位于另一个活动中，则必须在创建深度链接构建器时指定其组件名称。

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(DestinationActivity::class.java)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(DestinationActivity.class)
        .createPendingIntent();

如果您有 ComponentName，您可以直接将其传递给构建器。

Kotlin

val componentName = ...

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(componentName)
    .createPendingIntent()

Java

ComponentName componentName = ...;

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(componentName)
        .createPendingIntent();

如果您有现有的 NavController，您也可以通过使用 NavController.createDeepLink() 来创建深度链接。

创建隐式深度链接

一个隐式深度链接 指的是应用中的特定目标位置。当调用深度链接时（例如，当用户点击链接时），Android 然后可以打开您的应用到相应的目标位置。

深度链接可以通过 URI、意图操作和 MIME 类型进行匹配。您可以为单个深度链接指定多个匹配类型，但请注意，URI 参数匹配优先级最高，其次是操作，然后是 MIME 类型。

这是一个包含 URI、操作和 MIME 类型的深度链接示例。

<fragment android:id="@+id/a"
          android:name="com.example.myapplication.FragmentA"
          tools:layout="@layout/a">
        <deepLink app:uri="www.example.com"
                app:action="android.intent.action.MY_ACTION"
                app:mimeType="type/subtype"/>
</fragment>

您还可以使用导航编辑器为目标创建隐式深度链接，如下所示。

  1. 在导航编辑器的“设计”选项卡中，选择深度链接的目标。
  2. 点击“属性”面板“深度链接”部分中的“+”。

  3. 在出现的“添加深度链接”对话框中，输入深度链接的信息。

    注意以下几点：

    • 没有方案的 URI 被假定为 http 或 https。例如，www.google.com 同时匹配 http://www.google.com 和 https://www.google.com。
    • 形式为 {placeholder_name} 的路径参数占位符匹配一个或多个字符。例如，http://www.example.com/users/{id} 匹配 http://www.example.com/users/4。导航组件尝试通过将占位符名称与为深度链接目标定义的已定义参数 进行匹配来将占位符值解析为适当的类型。如果没有定义相同名称的参数，则对参数值使用默认 String 类型。您可以使用 .* 通配符来匹配 0 个或多个字符。
    • 可以使用查询参数占位符来代替或与路径参数结合使用。例如，http://www.example.com/users/{id}?myarg={myarg} 匹配 http://www.example.com/users/4?myarg=28。
    • 使用默认值或可空值定义的变量的查询参数占位符不需要匹配。例如，http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} 匹配 http://www.example.com/users/4?arg2=28 或 http://www.example.com/users/4?arg1=7。路径参数的情况并非如此。例如，http://www.example.com/users?arg1=7&arg2=28 不匹配上述模式，因为缺少必需的路径参数。
    • 多余的查询参数不影响深层链接 URI 匹配。例如，http://www.example.com/users/{id} 匹配 http://www.example.com/users/4?extraneousParam=7，即使 URI 模式中未定义 extraneousParam。

  4. (可选) 选中**自动验证**以要求 Google 验证您是 URI 的所有者。更多信息，请参见 验证 Android 应用链接。

  5. 点击**添加**。一个链接图标 将出现在选定目标的上方，以指示该目标具有深层链接。

  6. 点击**代码**选项卡切换到 XML 视图。一个嵌套的 <deepLink> 元素已添加到目标。

    <deepLink app:uri="https://www.google.com" />

要启用隐式深层链接，您还必须向应用的 manifest.xml 文件中添加内容。向指向现有导航图的活动添加单个 <nav-graph> 元素，如下例所示

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">

    <application ... >

        <activity name=".MainActivity" ...>
            ...

            <nav-graph android:value="@navigation/nav_graph" />

            ...

        </activity>
    </application>
</manifest>

构建项目时，导航组件会将 <nav-graph> 元素替换为生成的 <intent-filter> 元素，以匹配导航图中的所有深层链接。

触发隐式深层链接时，回退堆栈的状态取决于隐式 Intent 是否使用 Intent.FLAG_ACTIVITY_NEW_TASK 标志启动。

  • 如果设置了该标志，则任务回退堆栈将被清除并替换为深层链接目标。与 显式深层链接 一样，当 嵌套图表 时，还会将每个嵌套级别的起始目标（即，层次结构中每个 <navigation> 元素的起始目标）添加到堆栈中。这意味着当用户从深层链接目标按下返回按钮时，他们会像从入口点进入应用一样，向上导航回导航堆栈。
  • 如果没有设置该标志，您将保留在触发隐式深层链接的先前应用的任务堆栈中。在这种情况下，返回按钮将带您返回到之前的应用，而向上按钮将启动您应用的任务，位于导航图中的层次父目标。

处理深层链接

强烈建议在使用 Navigation 时始终使用默认的 launchMode `standard`。使用 `standard` 启动模式时，Navigation 会通过调用 handleDeepLink() 来自动处理 Intent 中的任何显式或隐式深层链接。但是，如果使用替代的 launchMode（如 singleTop）时重用了 Activity，则不会自动发生这种情况。在这种情况下，需要在 onNewIntent() 中手动调用 handleDeepLink()，如下例所示

Kotlin

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    navController.handleDeepLink(intent)
}

Java

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    navController.handleDeepLink(intent);
}

其他资源

要了解有关导航的更多信息，请参阅以下资源。

示例

Codelabs

视频