深层链接
将您的 Tauri 应用程序设置为 URL 的默认处理器。
支持的平台
此插件需要至少 1.77.2 版本的 Rust
平台 | 级别 | 备注 |
---|---|---|
Windows | ||
Linux | ||
Macos | | 运行时深层链接注册不受支持 |
Android | | 运行时深层链接注册不受支持 |
iOS | | 运行时深层链接注册不受支持 |
设置
安装深层链接插件开始使用。
使用项目包管理器添加依赖
npm run tauri add deep-link
yarn run tauri add deep-link
pnpm tauri add deep-link
deno task tauri add deep-link
bun tauri add deep-link
cargo tauri add deep-link
-
在
src-tauri
文件夹中运行以下命令,将插件添加到项目的Cargo.toml
依赖中 -
修改
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");} -
使用您首选的 JavaScript 包管理器安装 JavaScript Guest 绑定
npm install @tauri-apps/plugin-deep-linkyarn add @tauri-apps/plugin-deep-linkpnpm add @tauri-apps/plugin-deep-linkdeno add npm:@tauri-apps/plugin-deep-linkbun add @tauri-apps/plugin-deep-link
设置
Android
对于 应用链接,您需要一个带有 .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 applinks
iOS
对于 通用链接,您需要一个带有 .well-known/apple-app-site-association
端点的服务器,该端点必须返回预设格式的 JSON 响应
{ "applinks": { "details": [ { "appIDs": ["$DEVELOPMENT_TEAM_ID.$APP_BUNDLE_ID"], "components": [ { "/": "/open/*", "comment": "Matches any URL whose path starts with /open/" } ] } ] }}
其中 $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
功能添加到单实例插件中
[target."cfg(any(target_os = \"macos\", windows, target_os = \"linux\"))".dependencies]tauri-plugin-single-instance = { version = "2.0.0", features = ["deep-link"] }
- 然后配置单实例插件,这应该是您注册的第一个插件
#[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
下配置您想与应用程序关联的域名(移动端)和方案(桌面端)
{ "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。
监听深层链接
当深链接触发您的应用程序打开时,将执行 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);});
当深链接触发应用程序打开时,将调用 on_open_url
闭包
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");}
运行时注册桌面深层链接
配置部分描述了如何定义应用程序的静态深链接方案。
在 Linux 和 Windows 上,您还可以通过 register
Rust 函数在运行时将方案与应用程序关联。
在以下片段中,我们将运行时注册 my-app
方案。启动应用程序后,操作系统将使用应用程序打开 my-app://*
URL。
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 上,您可以使用 register_all
Rust 函数来绕过此限制,该函数将所有配置的协议注册为触发当前可执行文件
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");}
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
配置中的权限才能启用这些命令。
{ "$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
权限表
标识符 | 描述 |
---|---|
|
启用 get_current 命令,不需要任何预配置的作用域。 |
|
拒绝 get_current 命令,不需要任何预配置的作用域。 |
|
启用 is_registered 命令,不需要任何预配置的作用域。 |
|
拒绝 is_registered 命令,不需要任何预配置的作用域。 |
|
启用 register 命令,不需要任何预配置的作用域。 |
|
拒绝 register 命令,不需要任何预配置的作用域。 |
|
启用 unregister 命令,不需要任何预配置的作用域。 |
|
拒绝 unregister 命令,不需要任何预配置的作用域。 |
© 2025 Tauri 贡献者. CC-BY / MIT