深度链接

GitHub npm crates.io

API 参考

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

支持的平台

此插件需要 Rust 版本至少为 **1.77.2**

平台	级别	备注
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 访客绑定

   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 提供服务。为了测试 localhost，您可以使用自签名 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 将打开您的移动应用程序。

用法

deep-link 插件在 JavaScript 和 Rust 中均可用。

监听深度链接

JavaScript

当深度链接在您的应用程序运行时触发时，将调用onOpenUrl回调。要检测您的应用程序是否通过深度链接打开，请在应用程序启动时使用getCurrent。

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

const startUrls = await getCurrent();
if (startUrls) {
  // App was likely started via a deep link
  // Note that getCurrent's return value will also get updated every time onOpenUrl gets triggered.
}

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

Rust

当深度链接在应用程序运行时触发时，将调用插件的on_open_url闭包。要检测您的应用程序是否通过深度链接打开，请在应用程序启动时使用get_current。

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| {
            // Note that get_current's return value will also get updated every time on_open_url gets triggered.
            let start_urls = app.deep_link().get_current()?;
            if let Some(urls) = start_urls {
                // app was likely started by a deep link
                println!("deep link URLs: {:?}", urls);
            }

            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 事件会触发一个 URL 列表，这些 URL 被要求与 macOS API 兼容以用于深度链接，但在大多数情况下，您的应用程序只会收到单个 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 启动器才能将 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 命令读取已打开的深度链接

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

• 允许获取当前

权限表

标识符	描述
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 命令，不进行任何预配置范围。