Skip to main content

Linking

Linking 为你提供了一个与传入和传出应用链接进行交互的通用界面。

¥Linking gives you a general interface to interact with both incoming and outgoing app links.

每个链接（URL）都有一个 URLScheme，有些网站以 https:// 或 http:// 为前缀，http 是 URLScheme。我们简称它为计划。

¥Every Link (URL) has a URL Scheme, some websites are prefixed with https:// or http:// and the http is the URL Scheme. Let's call it scheme for short.

除了 https 之外，你可能还熟悉 mailto 方案。当你打开带有 mailto 方案的链接时，你的操作系统将打开已安装的邮件应用。类似地，还有调用调用和发送短信的方案。请阅读下面有关 内置网址 方案的更多信息。

¥In addition to https, you're likely also familiar with the mailto scheme. When you open a link with the mailto scheme, your operating system will open an installed mail application. Similarly, there are schemes for making phone calls and sending SMS. Read more about built-in URL schemes below.

与使用 mailto 方案一样，可以使用自定义 url 方案链接到其他应用。例如，当你从 Slack 收到 Magic Link 电子邮件时，“启动 Slack”按钮是一个带有 href 的锚标记，如下所示：slack://secret/magic-login/other-secret。与 Slack 一样，你可以告诉操作系统你想要处理自定义方案。当 Slack 应用打开时，它会收到用于打开它的 URL。这通常称为深度链接。阅读有关如何 获取深层链接 到你的应用的更多信息。

¥Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a Magic Link email from Slack, the Launch Slack button is an anchor tag with an href that looks something like: slack://secret/magic-login/other-secret. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to get the deep link into your app.

自定义 URL 方案并不是在移动设备上打开应用的唯一方法。你不想在电子邮件的链接中使用自定义 URL 方案，因为这样链接在桌面上会被破坏。相反，你希望使用常规 https 链接，例如 https://www.myapp.io/records/1234546。在移动设备上，你希望该链接打开你的应用。Android 将其称为深层链接（通用链接 - iOS）。

¥Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular https links such as https://www.myapp.io/records/1234546. and on mobile you want that link open your app. Android calls it Deep Links (Universal Links - iOS).

内置 URL 方案​

¥Built-in URL Schemes

正如简介中提到的，每个平台上都存在一些用于核心功能的 URL 方案。以下是一个非详尽的列表，但涵盖了最常用的方案。

¥As mentioned in the introduction, there are some URL schemes for core functionality that exist on every platform. The following is a non-exhaustive list, but covers the most commonly used schemes.

方案描述iOS安卓
mailto打开邮件应用，例如：mailto：support@expo.io✅✅
tel打开手机应用，例如：调用：+123456789✅✅
sms打开短信应用，例如：sms:+123456789✅✅
https/http打开网络浏览器应用，例如：https://expo.io✅✅

¥Enabling Deep Links

仅包含原生代码的项目

The following section only applies to projects with native code exposed. If you are using the managed Expo workflow, see the guide on Linking in the Expo documentation for the appropriate alternative.

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

¥If you want to enable deep links in your app, please read the below guide:

有关如何在 Android 上添加深度链接支持的说明，请参阅 为应用内容启用深层链接 - 为你的深层链接添加意图过滤器。

¥For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

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

¥If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.

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

¥Handling Deep Links

有两种方法可以处理打开应用的 URL。

¥There are two ways to handle URLs that open your app.

1. 如果应用已打开，则应用将处于前台并触发 Linking 'url' 事件​

¥ If the app is already open, the app is foregrounded and a Linking 'url' event is fired

你可以使用 Linking.addEventListener('url', callback) 处理这些事件 - 它使用链接的 URL 调用 callback({url})

¥You can handle these events with Linking.addEventListener('url', callback) - it calls callback({url}) with the linked URL

2. 如果应用尚未打开，则会将其打开，并将 url 作为初始 URL 传入​

¥ If the app is not already open, it is opened and the url is passed in as the initialURL

你可以使用 Linking.getInitialURL() 处理这些事件 - 它返回一个解析为 URL 的 Promise（如果有的话）。

¥You can handle these events with Linking.getInitialURL() - it returns a Promise that resolves to the URL, if there is one.

示例​

¥Example

¥Open Links and Deep Links (Universal Links)

打开自定义设置​

¥Open Custom Settings

¥Get the Deep Link

发送意图 (Android)​

¥Send Intents (Android)

参考

¥Reference

方法​

¥Methods

addEventListener()​

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

通过监听 url 事件类型并提供处理程序，将处理程序添加到链接更改。

¥Add a handler to Linking changes by listening to the url event type and providing the handler.

canOpenURL()​

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

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

¥Determine whether or not an installed app can handle a given URL.

该方法返回一个 Promise 对象。当确定给定的 URL 是否可以处理时，promise 就被解析，第一个参数是是否可以打开。

¥The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

如果无法检查 URL 是否可以打开，或者在针对 Android 11（SDK 30）时未在 AndroidManifest.xml 中指定相关意图查询，则 Promise 将在 Android 上拒绝。类似地，在 iOS 上，如果你没有在 Info.plist 内的 LSApplicationQueriesSchemes 键中添加特定方案，则 Promise 将被拒绝（见下文）。

¥The Promise will reject on Android if it was impossible to check if the URL can be opened or when targeting Android 11 (SDK 30) if you didn't specify the relevant intent queries in AndroidManifest.xml. Similarly on iOS, the promise will reject if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

参数：

¥Parameters:

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

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

¥For web URLs, the protocol ("http://", "https://") must be set accordingly!

此方法在 iOS 9+ 上有限制。来自 苹果官方文档：

¥This method has limitations on iOS 9+. From the official Apple documentation:

  • 如果你的应用链接到早期版本的 iOS，但在 iOS 9.0 或更高版本中运行，则你最多可以调用此方法 50 次。达到该限制后，后续调用始终解析为 false。如果用户重新安装或升级应用，iOS 会重置限制。

    ¥If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always resolve to false. If the user reinstalls or upgrades the app, iOS resets the limit.

从 iOS 9 开始，你的应用还需要在 Info.plist 中提供 LSApplicationQueriesSchemes 密钥，否则 canOpenURL() 将始终解析为 false。

¥As of iOS 9, your app also needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL() will always resolve to false.

当面向 Android 11 (SDK 30) 时，你必须指定要在 AndroidManifest.xml 中处理的方案的意图。常见意图列表可在 此处 中找到。

¥When targeting Android 11 (SDK 30) you must specify the intents for the schemes you want to handle in AndroidManifest.xml. A list of common intents can be found here.

例如，要处理 https 方案，需要将以下内容添加到你的清单中：

¥For example to handle https schemes the following needs to be added to your manifest:

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

getInitialURL()​

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

如果应用启动是由应用链接触发的，则会给出链接 url，否则会给出 null。

¥If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

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

¥To support deep linking on Android, refer https://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

当远程 JS 调试处于活动状态时，getInitialURL 可能会返回 null。禁用调试器以确保它通过。

¥getInitialURL may return null when Remote JS Debugging is active. Disable the debugger to ensure it gets passed.

openSettings()​

static openSettings(): Promise<void>;

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

¥Open the Settings app and displays the app’s custom settings, if it has any.

openURL()​

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

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

¥Try to open the given url with any of the installed apps.

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

¥You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "https://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

该方法返回一个 Promise 对象。如果用户确认打开对话框或 url 自动打开，则 promise 得到解决。如果用户取消打开的对话框或该 url 没有注册的应用，则 promise 将被拒绝。

¥The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

参数：

¥Parameters:

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

如果系统不知道如何打开指定的 URL，则此方法将失败。如果你传入非 http(s) URL，最好先检查 canOpenURL()。

¥This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check canOpenURL() first.

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

¥For web URLs, the protocol ("http://", "https://") must be set accordingly!

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

¥This method may behave differently in a simulator e.g. "tel:" links are not able to be handled in the iOS simulator as there's no access to the dialer app.

sendIntent()
Android
​

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

启动带有附加功能的 Android 意图。

¥Launch an Android intent with extras.

参数：

¥Parameters:

名称类型
操作
必填
string
extrasArray<{key: string, value: string ｜ number ｜ boolean}>