Linking
Linking
提供了一个通用的接口来与传入和传出的 App 链接进行交互。
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.
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.
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.
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).
Built-in URL Schemes
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.
Scheme | 说明 | iOS | Android |
---|---|---|---|
mailto | Open mail app, eg: mailto: support@expo.io | ✅ | ✅ |
tel | Open phone app, eg: tel:+123456789 | ✅ | ✅ |
sms | Open SMS app, eg: sms:+123456789 | ✅ | ✅ |
https / http | Open web browser app, eg: https://expo.io | ✅ | ✅ |
基本用法
启用 Deep Links
If you want to enable deep links in your app, please the below guide:
- Android
- iOS
要了解更多如何在 Android 上支持深度链接的说明,请参阅Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.
如果要在现有的 MainActivity 中监听传入的 intent,那么需要在AndroidManifest.xml
中将 MainActivity 的launchMode
设置为singleTask
。相关解释可参考<activity>
文档。
<activity
android:name=".MainActivity"
android:launchMode="singleTask">
注意: 对于 iOS 来说,如果要在 App 启动后也监听传入的 App 链接,那么首先需要在项目中链接
RCTLinking
,具体步骤请参考手动链接这篇文档,然后需要在AppDelegate.m
中增加以下代码:
// 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];
}
// iOS 8.x 或更低版本
#import <React/RCTLinkingManager.h>
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
return [RCTLinkingManager application:application openURL:url
sourceApplication:sourceApplication annotation:annotation];
}
如果你的 app 用了 Universal Links,需要正确的把下述代码添加进去:
- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity
restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
return [RCTLinkingManager application:application
continueUserActivity:userActivity
restorationHandler:restorationHandler];
}
处理 Deep Links
There are two ways to handle URLs that open your app.
1. If the app is already open, the app is foregrounded and a Linking 'url' event is fired
You can handle these events with Linking.addEventListener('url', callback)
-- it calls callback({ url })
with the linked URL
2. If the app is not already open, it is opened and the url is passed in as the initialURL
You can handle these events with Linking.getInitialURL()
-- it returns a Promise that resolves to the URL, if there is one.
示例
Open Links and Deep Links (Universal Links)
- javascript
- typescript
Open Custom Settings
- javascript
- typescript
获取 Deep Link
- javascript
- typescript
发送 Intents (Android)
- javascript
- typescript
文档
方法
addEventListener()
static addEventListener(
type: 'url',
handler: (event: {url: string}) => void,
): EmitterSubscription;
Add a handler to Linking changes by listening to the url
event type and providing the handler.
canOpenURL()
static canOpenURL(url: string): Promise<boolean>;
Determine whether or not an installed app can handle a given URL.
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.
The Promise
will reject on Android if it was impossible to check if the URL can be opened or when targetting 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:
Name | Type | Description |
---|---|---|
url Required | string | The URL to open. |
For web URLs, the protocol (
"http://"
,"https://"
) must be set accordingly!
This method has limitations on iOS 9+. From the official Apple documentation:
- 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.As of iOS 9, your app also needs to provide the
LSApplicationQueriesSchemes
key insideInfo.plist
orcanOpenURL()
will always resolve tofalse
.
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.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>;
If the app launch was triggered by an app link, it will give the link url, otherwise it will give null
.
To support deep linking on Android, refer https://developer.android.com/training/app-indexing/deep-linking.html#handling-intents
getInitialURL may return
null
while debugging is enabled. 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>;
Try to open the given url
with any of the installed apps.
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.
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:
Name | Type | Description |
---|---|---|
url Required | string | The URL to open. |
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.
For web URLs, the protocol (
"http://"
,"https://"
) must be set accordingly!
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>;
Launch an Android intent with extras.
Parameters:
Name | Type |
---|---|
action Required | string |
extras | Array<{key: string, value: string | number | boolean}> |