深度链接

GitHub npm crates.io

API 参考

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

支持的平台

此插件至少需要 1.77.2 版本的 Rust

平台	级别	注释
windows
linux
macos		不支持运行时深度链接注册
android		不支持运行时深度链接注册
ios		不支持运行时深度链接注册

设置

安装 deep-link 插件以开始使用。

自动

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

npm

npm run tauri add deep-link

yarn

yarn run tauri add deep-link

pnpm

pnpm tauri add deep-link

deno

deno task tauri add deep-link

bun

bun tauri add deep-link

cargo

cargo tauri add deep-link

手动

1. 在 src-tauri 文件夹中运行以下命令，将插件添加到 Cargo.toml 项目的依赖项中

   cargo add tauri-plugin-deep-link@2.0.0

2. 修改 lib.rs 以初始化插件

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .plugin(tauri_plugin_deep_link::init())
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. 使用您首选的 JavaScript 包管理器安装 JavaScript Guest 绑定

   npm

   npm install @tauri-apps/plugin-deep-link

   yarn

   yarn add @tauri-apps/plugin-deep-link

   pnpm

   pnpm add @tauri-apps/plugin-deep-link

   deno

   deno add npm:@tauri-apps/plugin-deep-link

   bun

   bun add @tauri-apps/plugin-deep-link

设置

Android

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

.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 应用链接。

iOS

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

.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/"
          }
        ]
      }
    ]
  }
}

注意

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

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

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

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

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

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

桌面

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

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

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"] }

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

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 是否与您期望的格式匹配。

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

配置

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

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 将打开您的移动应用程序。

用法

深度链接插件在 JavaScript 和 Rust 中均可用。

监听深度链接

JavaScript

当深度链接触发您的应用程序打开时，将执行 onOpenUrl 回调

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);
});

Rust

当深度链接触发您的应用程序打开时，将调用 on_open_url 闭包

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| {
            app.deep_link().on_open_url(|event| {
                println!("deep link URLs: {:?}", event.urls());
            });
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

注意

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

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

配置 部分描述了如何为您的应用程序定义静态深度链接方案。

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

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

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");
}

注意

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

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

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

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

测试

测试应用程序的深度链接存在一些注意事项。

桌面

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

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");
}

注意

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

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

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

注意

在 macOS 上无法在运行时注册深度链接，因此深度链接只能在捆绑的应用程序上进行测试，该应用程序必须安装在 /Applications 目录中。

Windows

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

start <scheme>://url

Linux

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

xdg-open <scheme>://url

iOS

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

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

Android

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

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

权限

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

有关更多信息，请参见 功能概述 和 使用插件权限的逐步指南。

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"
  ]
}

默认权限

允许通过 get_current 命令读取打开的深度链接

此默认权限集包括以下内容

• allow-get-current

权限表

标识符	描述
deep-link:allow-get-current	启用 get_current 命令，无需任何预配置的作用域。
deep-link:deny-get-current	禁用 get_current 命令，无需任何预配置的作用域。
deep-link:allow-is-registered	启用 is_registered 命令，无需任何预配置的作用域。
deep-link:deny-is-registered	禁用 is_registered 命令，无需任何预配置的作用域。
deep-link:allow-register	启用 register 命令，无需任何预配置的作用域。
deep-link:deny-register	禁用 register 命令，无需任何预配置的作用域。
deep-link:allow-unregister	启用 unregister 命令，无需任何预配置的作用域。
deep-link:deny-unregister	禁用 unregister 命令，无需任何预配置的作用域。