Skip to content
Tauri 中文网
开发指南 参考手册 Nodejs.cn 旗下网站

深度链接

GitHub npm crates.io
API Reference

将你的 Tauri 应用设置为 URL 的默认处理程序。

¥Set your Tauri application as the default handler for an URL.

支持的平台

¥Supported Platforms

This plugin requires a Rust version of at least 1.77.2

Platform Level Notes
windows
linux
macos

Runtime deep link registration is not supported
android

Runtime deep link registration is not supported
ios

Runtime deep link registration is not supported

设置

¥Setup

安装深层链接插件即可开始使用。

¥Install the deep-link plugin to get started.

使用项目的包管理器添加依赖：

¥Use your project’s package manager to add the dependency:

npm run tauri add deep-link

设置

¥Setting up

Android

对于 应用链接，你需要一个具有 .well-known/assetlinks.json 端点的服务器，该服务器必须以给定的格式返回文本响应：

¥For app links, you need a server with a .well-known/assetlinks.json endpoint that must return a text response in the given format:

.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "$APP_BUNDLE_ID",
      "sha256_cert_fingerprints": [
        $CERT_FINGERPRINT
      ]
    }
  }
]

其中 $APP_BUNDLE_ID 是在 tauri.conf.json > identifier 上定义的值，- 替换为 _，$CERT_FINGERPRINT 是应用签名证书的 SHA256 指纹列表，有关更多信息，请参阅 验证 Android 应用链接。

¥Where $APP_BUNDLE_ID is the value defined on tauri.conf.json > identifier with - replaced with _ and $CERT_FINGERPRINT is a list of SHA256 fingerprints of your app’s signing certificates, see verify Android applinks for more information.

iOS

对于 通用链接，你需要一个具有 .well-known/apple-app-site-association 端点的服务器，该服务器必须以给定的格式返回 JSON 响应：

¥For universal links, you need a server with a .well-known/apple-app-site-association endpoint that must return a JSON response in the given format:

.well-known/apple-app-site-association
{
  "applinks": {
    "details": [
      {
        "appIDs": ["$DEVELOPMENT_TEAM_ID.$APP_BUNDLE_ID"],
        "components": [
          {
            "/": "/open/*",
            "comment": "Matches any URL whose path starts with /open/"
          }
        ]
      }
    ]
  }
}

:::note 注意

响应 Content-Type 标头必须是 application/json。

¥The response Content-Type header must be application/json.

.well-known/apple-app-site-association 端点必须通过 HTTPS 提供服务。要测试本地主机，你可以使用自签名 TLS 证书并将其安装在 iOS 模拟器上，也可以使用 ngrok 等服务。

¥The .well-known/apple-app-site-association endpoint must be served over HTTPS. To test localhost you can either use a self-signed TLS certificate and install it on the iOS simulator or use services like ngrok.

:::

其中 $DEVELOPMENT_TEAM_ID 是在 tauri.conf.json > tauri > bundle > iOS > developmentTeam 或 TAURI_APPLE_DEVELOPMENT_TEAM 环境变量上定义的值，$APP_BUNDLE_ID 是在 tauri.conf.json > identifier 上定义的值。

¥Where $DEVELOPMENT_TEAM_ID is the value defined on tauri.conf.json > tauri > bundle > iOS > developmentTeam or the TAURI_APPLE_DEVELOPMENT_TEAM environment variable and $APP_BUNDLE_ID is the value defined on tauri.conf.json > identifier.

要验证你的域是否已正确配置为公开应用关联，你可以运行以下命令，将 <host> 替换为你的实际主机：

¥To verify if your domain has been properly configured to expose the app associations, you can run the following command, replacing <host> with your actual host:

Terminal window
curl -v https://app-site-association.cdn-apple.com/a/v1/<host>

有关更多信息，请参阅 applinks.details。

¥See applinks.details for more information.

桌面

¥Desktop

在 Linux 和 Windows 上，深层链接作为命令行参数传递给新的应用进程。如果你希望有一个唯一的应用实例接收事件，则深层链接插件与 单个实例 插件集成。

¥On Linux and Windows deep links are delivered as a command line argument to a new app process. The deep link plugin has integration with the single instance plugin if you prefer having a unique app instance receiving the events.

  • 首先，你必须将 deep-link 功能添加到单实例插件中：

    ¥First you must add the deep-link feature to the single instance plugin:

src-tauri/Cargo.toml
[target."cfg(any(target_os = \"macos\", windows, target_os = \"linux\"))".dependencies]
tauri-plugin-single-instance = { version = "2.0.0", features = ["deep-link"] }

  • 然后配置单实例插件，该插件应始终是你注册的第一个插件：

    ¥Then configure the single instance plugin which should always be the first plugin you register:

src-tauri/lib.rs
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    let mut builder = tauri::Builder::default();


    #[cfg(desktop)]
    {
        builder = builder.plugin(tauri_plugin_single_instance::init(|_app, argv, _cwd| {
          println!("a new app instance was opened with {argv:?} and the deep link event was already triggered");
          // when defining deep link schemes at runtime, you must also check `argv` here
        }));
    }


    builder = builder.plugin(tauri_plugin_deep_link::init());
}

用户可以通过将 URL 作为参数包含进来来手动触发虚假深层链接。Tauri 将命令行参数与配置的方案进行匹配以缓解这种情况，但你仍应检查 URL 是否符合你期望的格式。

¥The user could trigger a fake deep link manually by including the URL as argument. Tauri matches the command line argument against the configured schemes to mitigate this, but you should still check if the URL matches the format you expect.

这意味着 Tauri 仅处理静态配置的方案的深层链接，并且必须使用 Env::args_os 手动检查在运行时注册的方案。

¥This means Tauri only handles deep links for schemes that were statically configured, and schemes registered at runtime must be manually checked using Env::args_os.

配置

¥Configuration

在 tauri.conf.json > plugins > deep-link 下，配置要与应用关联的域（移动）和方案（桌面）：

¥Under tauri.conf.json > plugins > deep-link, configure the domains (mobile) and schemes (desktop) you want to associate with your application:

tauri.conf.json
{
  "plugins": {
    "deep-link": {
      "mobile": [
        { "host": "your.website.com", "pathPrefix": ["/open"] },
        { "host": "another.site.br" }
      ],
      "desktop": {
        "schemes": ["something", "my-tauri-app"]
      }
    }
  }
}

通过上述配置，something://* 和 my-tauri-app://* URL 与你的桌面应用相关联，在移动设备上，https://another.site.br/* 和 https://your.website.com/open/* URL 将打开你的移动应用。

¥With the above configuration, the something://* and my-tauri-app://* URLs are associated with your desktop application, and on mobile the https://another.site.br/* and https://your.website.com/open/* URLs will open your mobile app.

使用

¥Usage

深层链接插件在 JavaScript 和 Rust 中都可用。

¥The deep-link plugin is available in both JavaScript and Rust.

监听深层链接

¥Listening to Deep Links

当深层链接触发你的应用打开时，将执行 onOpenUrl 回调：

¥When a deep link triggers your app to be opened, the onOpenUrl callback is executed:

import { onOpenUrl } from '@tauri-apps/plugin-deep-link';
// when using `"withGlobalTauri": true`, you may use
// const { onOpenUrl } = window.__TAURI__.deepLink;


await onOpenUrl((urls) => {
  console.log('deep link:', urls);
});

:::note 注意

打开 URL 事件由请求与 macOS 深层链接 API 兼容的 URL 列表触发，但在大多数情况下，你的应用只会收到一个 URL。

¥The open URL event is triggered with a list of URLs that were requested to be compatible with the macOS API for deep links, but in most cases your app will only receive a single URL.

:::

在运行时注册桌面深层链接

¥Registering Desktop Deep Links at Runtime

configuration 部分描述了如何为你的应用定义静态深层链接方案。

¥The configuration section describes how to define static deep link schemes for your application.

在 Linux 和 Windows 上，还可以通过 register Rust 函数在运行时将方案与你的应用关联。

¥On Linux and Windows it is possible to also associate schemes with your application at runtime via the register Rust function.

在下面的代码片段中，我们将在运行时注册 my-app 方案。首次执行应用后，操作系统将使用我们的应用打开 my-app://* URL：

¥In the following snippet, we will register the my-app scheme at runtime. After executing the app for the first time, the operating system will open my-app://* URLs with our application:

src-tauri/src/lib.rs
use tauri_plugin_deep_link::DeepLinkExt;


#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            #[cfg(desktop)]
            app.deep_link().register("my-app")?;
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

:::note 注意

在运行时注册深层链接对于在 Linux 和 Windows 上进行开发很有用，因为默认情况下，深层链接仅在安装应用时注册。

¥Registering the deep links at runtime can be useful for developing on Linux and Windows as by default the deep link is only registered when your app is installed.

安装 AppImage 可能很复杂，因为它需要 AppImage 启动器。

¥Installing an AppImage can be complicated as it requires an AppImage launcher.

在运行时注册深层链接可能是首选，因此 Tauri 还包含一个辅助函数，用于在运行时强制注册所有静态配置的深层链接。调用此函数还可确保深层链接已注册为开发模式：

¥Registering the deep links at runtime might be preferred, so Tauri also includes a helper function to force register all statically configured deep links at runtime. Calling this function also ensures the deep links is registered for development mode:

#[cfg(any(target_os = "linux", all(debug_assertions, windows)))]
{
  use tauri_plugin_deep_link::DeepLinkExt;
  app.deep_link().register_all()?;
}

:::

测试

¥Testing

测试应用的深层链接时有一些注意事项。

¥There are some caveats to test deep links for your application.

桌面

¥Desktop

深层链接仅在桌面上安装的应用时触发。在 Linux 和 Windows 上，你可以使用 register_all Rust 函数来规避此问题，该函数注册所有已配置的方案以触发当前可执行文件：

¥Deep links are only triggered for installed applications on desktop. On Linux and Windows you can circumvent this using the register_all Rust function, which registers all configured schemes to trigger the current executable:

src-tauri/src/lib.rs
use tauri_plugin_deep_link::DeepLinkExt;


#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            #[cfg(any(windows, target_os = "linux"))]
            {
                use tauri_plugin_deep_link::DeepLinkExt;
                app.deep_link().register_all()?;
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

:::note 注意

在 Linux 上安装支持深层链接的 AppImage 需要 AppImage 启动器将 AppImage 与操作系统集成。使用 register_all 功能，你可以开箱即用地支持深层链接，而无需用户使用外部工具。

¥Installing an AppImage that supports deep links on Linux requires an AppImage launcher to integrate the AppImage with the operating system. Using the register_all function you can support deep links out of the box, without requiring your users to use external tools.

当 AppImage 移动到文件系统中的其他位置时，深层链接将失效，因为它利用了可执行文件的绝对路径，这使得在运行时注册方案变得更加重要。

¥When the AppImage is moved to a different location in the file system, the deep link is invalidated since it leverages an absolute path to the executable, which makes registering the schemes at runtime even more important.

有关更多信息，请参阅 在运行时注册桌面深层链接 部分。

¥See the Registering Desktop Deep Links at Runtime section for more information.

:::

:::caution 提醒

在 macOS 上无法在运行时注册深层链接，因此只能在打包的应用上测试深层链接，该应用必须安装在 /Applications 目录中。

¥Registering deep links at runtime is not possible on macOS, so deep links can only be tested on the bundled application, which must be installed in the /Applications directory.

:::

Windows

要在 Windows 上触发深层链接，你可以在浏览器中打开 <scheme>://url 或在终端中运行以下命令：

¥To trigger a deep link on Windows you can either open <scheme>://url in the browser or run the following command in the terminal:

Terminal window
start <scheme>://url

Linux

要在 Linux 上触发深层链接，你可以在浏览器中打开 <scheme>://url 或在终端中运行 xdg-open：

¥To trigger a deep link on Linux you can either open <scheme>://url in the browser or run xdg-open in the terminal:

Terminal window
xdg-open <scheme>://url

iOS

要在 iOS 上触发应用链接，你可以在浏览器中打开 https://<host>/path URL。对于模拟器，你可以利用 simctl CLI 直接从终端打开链接：

¥To trigger an app link on iOS you can open the https://<host>/path URL in the browser. For simulators you can leverage the simctl CLI to directly open a link from the terminal:

Terminal window
xcrun simctl openurl booted https://<host>/path

Android

要在 Android 上触发应用链接，你可以在浏览器中打开 https://<host>/path URL。对于模拟器，你可以利用 adb CLI 直接从终端打开链接：

¥To trigger an app link on Android you can open the https://<host>/path URL in the browser. For emulators you can leverage the adb CLI to directly open a link from the terminal:

Terminal window
adb shell am start -a android.intent.action.VIEW -d https://<host>/path <bundle-identifier>

权限

¥Permissions

默认情况下，所有潜在危险的插件命令和范围都会被阻止，无法访问。你必须修改 capabilities 配置中的权限才能启用这些权限。

¥By default all potentially dangerous plugin commands and scopes are blocked and cannot be accessed. You must modify the permissions in your capabilities configuration to enable these.

有关更详细的说明，请参阅 功能概述。

¥See the Capabilities Overview for more information and the step by step guide to use plugin permissions.

src-tauri/capabilities/default.json
{
  "$schema": "../gen/schemas/mobile-schema.json",
  "identifier": "mobile-capability",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": [
    // Usually you will need core:event:default to listen to the deep-link event
    "core:event:default",
    "deep-link:default"
  ]
}

Default Permission

Allows reading the opened deep link via the get_current command

This default permission set includes the following:

  • allow-get-current

Permission Table

Identifier Description

deep-link:allow-get-current

Enables the get_current command without any pre-configured scope.

deep-link:deny-get-current

Denies the get_current command without any pre-configured scope.

deep-link:allow-is-registered

Enables the is_registered command without any pre-configured scope.

deep-link:deny-is-registered

Denies the is_registered command without any pre-configured scope.

deep-link:allow-register

Enables the register command without any pre-configured scope.

deep-link:deny-register

Denies the register command without any pre-configured scope.

deep-link:allow-unregister

Enables the unregister command without any pre-configured scope.

deep-link:deny-unregister

Denies the unregister command without any pre-configured scope.

Tauri v2.5 中文网 - 粤ICP备13048890号
Nodejs.cn 旗下网站