链接

Linking 为你提供了一个通用接口，用于与应用的入站和出站链接进行交互。

每个链接（URL）都有一个 URL Scheme，一些网站会以 https:// 或 http:// 开头，其中 http 就是 URL Scheme。这里我们简称它为 scheme。

除了 https 之外，你可能也熟悉 mailto scheme。当你打开一个使用 mailto scheme 的链接时，你的操作系统会打开已安装的邮件应用。同样地，也有用于拨打电话和发送短信的 scheme。下面可以阅读更多关于内置 URL scheme 的内容。

和使用 mailto scheme 类似，也可以通过自定义 url scheme 链接到其他应用。例如，当你从 Slack 收到一封 Magic Link 邮件时，Launch Slack 按钮是一个锚点标签，其 href 看起来大概像这样：slack://secret/magic-login/other-secret。和 Slack 一样，你可以告诉操作系统你想处理某个自定义 scheme。当 Slack 应用打开时，它会接收到用于打开它的 URL。这通常被称为深度链接。更多关于如何将深度链接引入你的应用的信息，请阅读相关内容。

自定义 URL scheme 并不是在移动设备上打开应用的唯一方式。例如，如果你想给某人发送一条邮件，让其在移动设备上打开链接，使用自定义 URL scheme 并不理想，因为用户可能会在桌面端打开邮件，而那里的链接无法工作。相反，你应该使用标准的 https 链接，例如 https://www.myapp.io/records/1234546。在移动设备上，这些链接可以配置为打开你的应用。在 Android 上，这个功能称为 Deep Links，而在 iOS 上，它被称为 Universal Links。

内置 URL Schemes

如简介中所述，每个平台都提供了一些用于核心功能的 URL scheme。以下列表并不完整，但涵盖了最常用的 scheme。

Scheme	描述	iOS	Android
mailto	打开邮件应用，例如：mailto: hello@world.dev	✅	✅
tel	打开电话应用，例如：tel:+123456789	✅	✅
sms	打开短信应用，例如：sms:+123456789	✅	✅
https / http	打开网页浏览器应用，例如：https://expo.dev	✅	✅

启用深度链接

仅适用于包含原生代码的项目

以下部分仅适用于已暴露原生代码的项目。如果你使用的是托管式 Expo 工作流，请参阅 Expo 文档中的 Linking 指南，选择合适的替代方案。

如果你想在应用中启用深度链接，请阅读下面的指南：

Android

信息

关于如何在 Android 上添加对深度链接的支持，请参阅为应用内容启用深度链接 - 为你的深度链接添加 Intent Filters。

如果你希望在现有的 MainActivity 实例中接收 intent，可以在 AndroidManifest.xml 中将 MainActivity 的 launchMode 设置为 singleTask。更多信息请参阅 <activity> 文档。

XML

<activity
  android:name=".MainActivity"
  android:launchMode="singleTask">

iOS

备注

在 iOS 上，你需要像这里的第 3 步所述，将 LinkingIOS 文件夹添加到 header search paths 中。如果你还希望在应用运行期间监听传入的应用链接，还需要在你的 *AppDelegate.m 中添加以下代码：

ObjectiveC

AppDelegate.mm

// iOS 9.x 或更高版本
#import <React/RCTLinkingManager.h>

- (BOOL)application:(UIApplication *)application
   openURL:(NSURL *)url
   options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
  return [RCTLinkingManager application:application openURL:url options:options];
}

如果你的应用正在使用 Universal Links，你还需要添加以下代码：

AppDelegate.mm

- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity
 restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
 return [RCTLinkingManager application:application
                  continueUserActivity:userActivity
                    restorationHandler:restorationHandler];
}

Swift

AppDelegate.swift

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  return RCTLinkingManager.application(app, open: url, options: options)
}

如果你的应用正在使用 Universal Links，你还需要添加以下代码：

AppDelegate.swift

func application(
  _ application: UIApplication,
  continue userActivity: NSUserActivity,
  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    return RCTLinkingManager.application(
      application,
      continue: userActivity,
      restorationHandler: restorationHandler
    )
  }

处理深度链接

有两种方式来处理打开你应用的 URL。

1. 如果应用已经打开，应用会被切到前台，并触发 Linking 的 'url' 事件

你可以使用 Linking.addEventListener('url', callback) 来处理这些事件——它会以 callback({url}) 的形式传入链接 URL。

2. 如果应用尚未打开，则会被启动，并将 url 作为 initialURL 传入

你可以使用 Linking.getInitialURL() 来处理这些事件——它会返回一个 Promise，如果存在 URL，则会解析为该 URL。

---

示例

打开链接和深度链接（Universal Links）

TypeScript

JavaScript

打开自定义设置

TypeScript

JavaScript

获取深度链接

TypeScript

JavaScript

发送 Intent（Android）

TypeScript

JavaScript

Reference

方法

addEventListener()

React TSX

static addEventListener(
  type: 'url',
  handler: (event: {url: string}) => void,
): EmitterSubscription;

通过监听 url 事件类型并提供处理函数，为 Linking 变更添加一个处理函数。

---

canOpenURL()

React TSX

static canOpenURL(url: string): Promise<boolean>;

判断已安装的应用是否可以处理给定的 URL。

该方法返回一个 Promise 对象。当确定给定的 URL 是否可被处理后，promise 会被 resolve，且第一个参数表示它是否可以被打开。

如果无法检查该 URL 是否可以打开，或者在面向 Android 11（SDK 30）时你没有在 AndroidManifest.xml 中指定相关的 intent 查询，Promise 会在 Android 上被 reject。同样地，在 iOS 上，如果你没有在 Info.plist 中的 LSApplicationQueriesSchemes 键里添加特定的 scheme（见下文），promise 也会被 reject。

参数：

名称	类型	描述
url 必填	string	要打开的 URL。

备注

对于 web URL，协议（"http://", "https://"）必须相应设置！

注意

此方法在 iOS 9+ 上有一些限制。来自 Apple 官方文档：

• 如果你的应用链接的是较早版本的 iOS，但运行在 iOS 9.0 或更高版本上，你最多可以调用此方法 50 次。达到该限制后，后续调用始终会解析为 false。如果用户重新安装或升级应用，iOS 会重置该限制。
• 从 iOS 9 开始，你的应用还需要在 Info.plist 中提供 LSApplicationQueriesSchemes 键，否则 canOpenURL() 将始终解析为 false。

信息

当面向 Android 11（SDK 30）时，你必须在 AndroidManifest.xml 中为你希望处理的 scheme 指定 intents。常见 intents 的列表可以在 这里 找到。

例如，要处理 https scheme，需要将以下内容添加到你的 manifest 中：

<manifest ...>
  <queries>
    <intent>
      <action android:name="android.intent.action.VIEW" />
      <data android:scheme="https"/>
    </intent>
  </queries>
</manifest>

---

getInitialURL()

React TSX

static getInitialURL(): Promise<string | null>;

如果应用启动是由 app link 触发的，它会返回该链接的 url；否则返回 null。

信息

要在 Android 上支持深度链接，请参阅 https://developer.android.com/training/app-indexing/deep-linking.html#handling-intents。

提示

在启用 Remote JS Debugging 时，getInitialURL 可能返回 null。请关闭调试器以确保它能够被传递。

---

openSettings()

React TSX

static openSettings(): Promise<void>;

打开设置应用，并显示该应用的自定义设置（如果有）。

---

openURL()

React TSX

static openURL(url: string): Promise<any>;

尝试使用已安装的任意应用打开给定的 url。

你可以使用其他 URL，例如位置（如 Android 上的 "geo:37.484847,-122.148386" 或 iOS 上的 "https://maps.apple.com/?ll=37.484847,-122.148386"）、联系人，或任何可由已安装应用打开的其他 URL。

该方法返回一个 Promise 对象。如果用户确认打开对话框，或者 url 自动打开，promise 会被 resolve。如果用户取消打开对话框，或者没有为该 url 注册应用，promise 会被 reject。

参数：

名称	类型	描述
url 必填	string	要打开的 URL。

备注

如果系统不知道如何打开指定的 URL，此方法将失败。如果你传入的是非 http(s) URL，最好先检查 canOpenURL()。对于 web URL，协议（"http://", "https://"）必须相应设置！

注意

此方法在模拟器中的行为可能不同，例如在 iOS 模拟器中无法处理 "tel:" 链接，因为无法访问拨号应用。

---

sendIntent()

Android

React TSX

static sendIntent(
  action: string,
  extras?: Array<{key: string; value: string | number | boolean}>,
): Promise<void>;

使用 extras 启动一个 Android intent。

参数：

名称	类型
action 必填	string
extras	Array<{key: string, value: string ｜ number ｜ boolean}>