跳转到内容
Tauri

插件开发

插件能够钩入 Tauri 生命周期,公开依赖于 webview API 的 Rust 代码,使用 Rust、Kotlin 或 Swift 代码处理命令,还有很多其他功能。

Tauri 提供了一个具有 webview 功能的窗口系统,一种在 Rust 进程和 webview 之间发送消息的方式,以及一个事件系统,以及几个工具来提升开发体验。按照设计,Tauri 核心不包含对每个人都不需要的功能。相反,它提供了一种机制,可以将外部功能添加到 Tauri 应用程序中,这称为插件。

Tauri 插件由一个 Cargo 包和可选的 NPM 包组成,该包为其命令和事件提供 API 绑定。此外,插件项目可以包括一个 Android 库项目和 iOS 的 Swift 包。您可以在移动插件开发指南中了解更多有关为 Android 和 iOS 开发插件的信息。

命名规则

Tauri 插件有一个前缀,后跟插件名称。插件名称在插件的配置中指定,位于tauri.conf.json > plugins

默认情况下,Tauri 会将您的插件包前缀为tauri-plugin-。这有助于您的插件被 Tauri 社区发现,并使用 Tauri CLI。在初始化新的插件项目时,您必须提供它的名称。生成的包名将是 tauri-plugin-{plugin-name},而 JavaScript NPM 包名将是 tauri-plugin-{plugin-name}-api(尽管我们建议如果可能的话使用 NPM scope)。Tauri 对 NPM 包的命名约定是@scope-name/plugin-{plugin-name}

初始化插件项目

要启动一个全新的插件项目,运行plugin new命令。如果您不需要NPM包,可以使用--no-api命令行标志。如果希望初始化带有Android和/或iOS支持的插件,请使用--android和/或--ios标志。

安装后,您可以运行以下命令来创建插件项目

npx @tauri-apps/cli plugin new [name]

这将在tauri-plugin-[name]目录中初始化插件,并且根据使用的命令行标志,生成的项目将如下所示

. tauri-plugin-[name]/
├── src/ - Rust code
│ ├── commands.rs - Defines the commands the webview can use
| ├── desktop.rs - Desktop implementation
| ├── error.rs - Default error type to use in returned results
│ ├── lib.rs - Re-exports appropriate implementation, setup state...
│ ├── mobile.rs - Mobile implementation
│ └── models.rs - Shared structs
├── permissions/ - This will host (generated) permission files for commands
├── android - Android library
├── ios - Swift package
├── guest-js - Source code of the JavaScript API bindings
├── dist-js - Transpiled assets from guest-js
├── Cargo.toml - Cargo crate metadata
└── package.json - NPM package metadata

如果您有一个现有的插件并希望为其添加Android或iOS功能,可以使用plugin android addplugin ios add来启动移动库项目并指导您进行所需的更改。

移动插件开发

插件可以运行使用Kotlin(或Java)和Swift编写的本地移动代码。默认插件模板包含一个使用Kotlin的Android库项目和Swift包。它包含一个示例移动命令,展示了如何从Rust代码中触发其执行。

有关为移动设备开发插件的更多信息,请参阅移动插件开发指南

插件配置

在使用插件的Tauri应用程序中,插件配置在tauri.conf.json中进行指定,其中plugin-name是插件名称

{
"build": { ... },
"tauri": { ... },
"plugins": {
"plugin-name": {
"timeout": 30
}
}
}

插件配置在Builder中设置,并在运行时解析。以下是使用Config结构指定插件配置的示例

src/lib.rs
use tauri::plugin::{Builder, Runtime, TauriPlugin};
use serde::Deserialize;
// Define the plugin config
#[derive(Deserialize)]
struct Config {
timeout: usize,
}
pub fn init<R: Runtime>() -> TauriPlugin<R, Config> {
// Make the plugin config optional
// by using `Builder::<R, Option<Config>>` instead
Builder::<R, Config>::new("<plugin-name>")
.setup(|app, api| {
let timeout = api.config().timeout;
Ok(())
})
.build()
}

生命周期事件

插件可以挂钩到多个生命周期事件

对于移动插件,还有额外的生命周期事件

setup

  • :插件正在初始化
  • 原因:注册移动插件、管理状态、运行后台任务
src/lib.rs
use tauri::{Manager, plugin::Builder};
use std::{collections::HashMap, sync::Mutex, time::Duration};
struct DummyStore(Mutex<HashMap<String, String>>);
Builder::new("<plugin-name>")
.setup(|app, api| {
app.manage(DummyStore(Default::default()));
let app_ = app.clone();
std::thread::spawn(move || {
loop {
app_.emit("tick", ());
std::thread::sleep(Duration::from_secs(1));
}
});
Ok(())
})

on_navigation

  • :WebView正在尝试执行导航
  • 原因:验证导航或跟踪URL更改

返回false将取消导航。

src/lib.rs
use tauri::plugin::Builder;
Builder::new("<plugin-name>")
.on_navigation(|window, url| {
println!("window {} is navigating to {}", window.label(), url);
// Cancels the navigation if forbidden
url.scheme() != "forbidden"
})

on_webview_ready

  • :已创建新窗口
  • 原因:为每个窗口执行初始化脚本
src/lib.rs
use tauri::plugin::Builder;
Builder::new("<plugin-name>")
.on_webview_ready(|window| {
window.listen("content-loaded", |event| {
println!("webview content has been loaded");
});
})

on_event

  • :事件循环事件
  • 原因:处理核心事件,例如窗口事件、菜单事件和请求退出应用程序

使用此生命周期钩子,您可以通知任何事件循环事件

src/lib.rs
use std::{collections::HashMap, fs::write, sync::Mutex};
use tauri::{plugin::Builder, Manager, RunEvent};
struct DummyStore(Mutex<HashMap<String, String>>);
Builder::new("<plugin-name>")
.setup(|app, _api| {
app.manage(DummyStore(Default::default()));
Ok(())
})
.on_event(|app, event| {
match event {
RunEvent::ExitRequested { api, .. } => {
// user requested a window to be closed and there's no windows left
// we can prevent the app from exiting:
api.prevent_exit();
}
RunEvent::Exit => {
// app is going to exit, you can cleanup here
let store = app.state::<DummyStore>();
write(
app.path().app_local_data_dir().unwrap().join("store.json"),
serde_json::to_string(&*store.0.lock().unwrap()).unwrap(),
)
.unwrap();
}
_ => {}
}
})

on_drop

  • :插件正在被销毁
  • 原因:在插件被销毁时执行代码

有关更多信息,请参阅Drop

src/lib.rs
use tauri::plugin::Builder;
Builder::new("<plugin-name>")
.on_drop(|app| {
// plugin has been destroyed...
})

公开 Rust API

项目在desktop.rsmobile.rs中定义的插件API作为具有与插件相同名称的结构体(大驼峰式命名法)导出到用户。当插件设置时,将创建此结构体的一个实例,并作为状态管理,以便用户可以在任何时候通过插件中定义的扩展特质(例如AppHandleAppWindow)的实例检索它。

例如,全局快捷键插件定义了一个可以通过使用GlobalShortcutExt特质的global_shortcut方法读取的GlobalShortcut结构。

src-tauri/src/lib.rs
use tauri_plugin_global_shortcut::GlobalShortcutExt;
tauri::Builder::default()
.plugin(tauri_plugin_global_shortcut::init())
.setup(|app| {
app.global_shortcut().register(...);
Ok(())
})

添加命令

命令在commands.rs文件中定义。它们是常规的Tauri应用程序命令。它们可以直接访问AppHandle和Window实例、访问状态,并以与应用程序命令相同的方式输入。有关Tauri命令的更多详细信息,请阅读命令指南

此命令展示如何通过依赖注入访问AppHandleWindow实例,并接受两个输入参数(on_progressurl)。

src/commands.rs
use tauri::{command, ipc::Channel, AppHandle, Runtime, Window};
#[command]
async fn upload<R: Runtime>(app: AppHandle<R>, window: Window<R>, on_progress: Channel, url: String) {
// implement command logic here
on_progress.send(100).unwrap();
}

要将命令暴露给webview,您必须在lib.rs中的invoke_handler()调用中进行挂钩。

src/lib.rs
Builder::new("<plugin-name>")
.invoke_handler(tauri::generate_handler![commands::upload])

webview-src/index.ts中定义一个绑定函数,以便插件用户可以轻松地在JavaScript中调用此命令。

import { invoke, Channel } from '@tauri-apps/api/core'
export async function upload(url: string, onProgressHandler: (progress: number) => void): Promise<void> {
const onProgress = new Channel<number>()
onProgress.onmessage = onProgressHandler
await invoke('plugin:<plugin-name>|upload', { url, onProgress })
}

务必在测试之前构建TypeScript代码。

命令权限

默认情况下,您的命令对于前端是不可访问的。如果您尝试执行其中一个,您将收到拒绝错误拒绝。为了真正暴露命令,您还需要定义允许每个命令的权限。

权限文件

权限是在permissions目录中定义为JSON或TOML文件的。每个文件可以为权限列表、权限集合和插件默认权限定义列表。

权限

权限描述了插件命令的权限。它可以允许或拒绝一系列命令,并关联命令特定的和全局作用域。

permissions/start-server.toml
"$schema" = "schemas/schema.json"
[[permission]]
identifier = "allow-start-server"
description = "Enables the start_server command."
commands.allow = ["start_server"]
[[permission]]
identifier = "deny-start-server"
description = "Denies the start_server command."
commands.deny = ["start_server"]
范围

作用域允许插件定义对个别命令的更深层次的限制。每个权限可以定义一组作用域对象列表,该列表定义了对特定命令或对插件全局的允许或拒绝。

让我们定义一个示例结构,该结构将保存一组二进制文件的范围数据,这些二进制文件是shell插件允许启动的。

src/scope.rs
#[derive(Debug, schemars::JsonSchema)]
pub struct Entry {
pub binary: String,
}
命令作用域

插件消费者可以在其能力文件中定义特定命令的作用域(请参阅文档)。您可以使用tauri::ipc::CommandScope结构读取命令特定的作用域。

src/commands.rs
use tauri::ipc::CommandScope;
use crate::scope::Entry;
async fn spawn<R: tauri::Runtime>(app: tauri::AppHandle<R>, command_scope: CommandScope<'_, Entry>) -> Result<()> {
let allowed = command_scope.allows();
let denied = command_scope.denies();
todo!()
}
全局作用域

当一个权限没有定义允许或拒绝的任何命令时,它被视为作用域权限,并且它应仅为插件定义全局作用域。

permissions/spawn-node.toml
[[permission]]
identifier = "allow-spawn-node"
description = "This scope permits spawning the `node` binary."
[[permission.scope.allow]]
binary = "node"

您可以使用tauri::ipc::GlobalScope结构读取全局作用域。

src/commands.rs
use tauri::ipc::GlobalScope;
use crate::scope::Entry;
async fn spawn<R: tauri::Runtime>(app: tauri::AppHandle<R>, scope: GlobalScope<'_, Entry>) -> Result<()> {
let allowed = scope.allows();
let denied = scope.denies();
todo!()
}
架构

作用域条目需要schemars依赖来生成JSON架构,以便插件消费者了解作用域的格式,并在他们的IDE中进行代码补全。

要定义架构,首先将依赖项添加到您的Cargo.toml文件中。

# we need to add schemars to both dependencies and build-dependencies because the scope.rs module is shared between the app code and build script
[dependencies]
schemars = "0.8"
[build-dependencies]
schemars = "0.8"

在您的构建脚本中,添加以下代码

build.rs
#[path = "src/scope.rs"]
mod scope;
const COMMANDS: &[&str] = &[];
fn main() {
tauri_plugin::Builder::new(COMMANDS)
.global_scope_schema(schemars::schema_for!(scope::Entry))
.build();
}
权限集

权限集是一组单个权限,有助于用户以更高的抽象级别管理您的插件。例如,如果单个API使用多个命令,或者如果一组命令之间存在逻辑联系,您应该定义一个包含它们的权限集。

permissions/websocket.toml
"$schema" = "schemas/schema.json"
[[set]]
identifier = "allow-websocket"
description = "Allows connecting and sending messages through a WebSocket"
permissions = ["allow-connect", "allow-send"]
默认权限

默认权限是一个特殊的权限集,其标识符为 default。建议您默认启用所需的命令。例如,没有允许 request 命令的 http 插件是没有用的。

permissions/default.toml
"$schema" = "schemas/schema.json"
[default]
description = "Allows making HTTP requests"
permissions = ["allow-request"]

自动生成的权限

为您的每个命令定义权限的最简单方法是使用在 build.rs 文件中定义的插件构建脚本中的自动生成选项。在 COMMANDS 常量内部,以 snake_case(应与命令函数名匹配)定义命令列表,Tauri 将自动生成 allow-$commandnamedeny-$commandname 权限。

以下示例生成了 allow-uploaddeny-upload 权限

src/commands.rs
const COMMANDS: &[&str] = &["upload"];
fn main() {
tauri_plugin::Builder::new(COMMANDS).build();
}

有关更多信息,请参阅 权限概述 文档。

管理状态

插件可以以与 Tauri 应用程序相同的方式管理状态。有关更多信息,请参阅 状态管理指南


© 2025 Tauri 贡献者。CC-BY / MIT