为目标创建深层链接

在 Android 中，深层链接是指将用户直接定向到应用内特定目的地的链接。

借助 Navigation 组件，您可以创建两种不同类型的深层链接：显式深层链接和隐式深层链接。

创建显式深层链接

显式深层链接是深层链接的一个实例，该实例使用 PendingIntent 将用户定向到应用内的特定位置。例如，您可以在通知或应用 widget 中显示显式深层链接。

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

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

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 在其他 activity 中，则您必须在创建深层链接建立工具时指定其组件名称：

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、intent 操作和 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>

您还可以使用 Navigation Editor 创建指向某个目的地的隐式深层链接，如下所示：

  1. 在 Navigation Editor 的 Design 标签页中，选择深层链接的目的地。
  2. 点击 Attributes 面板 Deep Links 部分中的 +。

  3. 在随后显示的 Add Deep Link 对话框中，输入深层链接的信息。

    请注意以下几点：

    • 没有架构的 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 匹配。Navigation 组件通过将占位符名称与已定义的参数（为深层链接目的地所定义）相匹配，尝试将占位值解析为相应的类型。如果没有定义具有相同名称的参数，对参数值使用默认的 String 类型。您可以使用 .* 通配符匹配 0 个或多个字符。
    • 可以使用查询参数占位符代替路径参数，也可以将查询参数占位符与路径参数结合使用。例如，http://www.example.com/users/{id}?myarg={myarg} 与 http://www.example.com/users/4?myarg=28 匹配。
    • 使用默认值或可为 null 的值所定义的变量的查询参数占位符无需匹配。例如，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 匹配。例如，即使 URI 模式中未定义 extraneousParam，http://www.example.com/users/{id} 也与 http://www.example.com/users/4?extraneousParam=7 匹配。

  4. （可选）选中 Auto Verify 可要求 Google 验证您是相应 URI 的所有者。如需了解详情，请参阅验证 Android 应用链接。

  5. 点击 Add。所选目的地上方会显示链接图标 ，用于表示该目的地具有深层链接。

  6. 点击 Code 标签页，以切换到 XML 视图。已向相应目的地添加嵌套的 <deepLink> 元素：

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

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

<?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>

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

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

  • 如果该标志已设置，任务返回堆栈就会被清除，并被替换为相应的深层链接目的地。与显式深层链接一样，当嵌套图表时，每个嵌套级别的起始目的地（即层次结构中每个 <navigation> 元素的起始目的地）也会添加到相应堆栈中。也就是说，当用户从深层链接目的地按下返回按钮时，他们会返回到相应的导航堆栈，就像从入口点进入您的应用一样。
  • 如果该标记未设置，您仍会位于触发隐式深层链接时所在的上一个应用的任务堆栈中。在这种情况下，如果按下返回按钮，您会返回到上一个应用；如果按下向上按钮，就会在导航图中的父级目的地上启动应用的任务。

处理深层链接

使用 Navigation 时，强烈建议您始终使用默认launchMode：standard。使用 standard 启动模式时，Navigation 会调用 handleDeepLink() 来处理 Intent 中的任何显式或隐式深层链接，从而自动处理深层链接。但是，如果在使用备用 singleTop 等备选 launchMode 时重复使用了相应 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);
}

其他资源

如需详细了解 Navigation，请参阅下面列出的资源：

示例

Codelab

视频