深度連結

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 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 提供。若要測試 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 將會開啟您的行動應用程式。

用法

深度連結外掛程式在 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 事件會以 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 啟動器。

在運行時註冊深度連結可能是較佳的選擇，因此 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 指令。