插件开发
插件能够钩入 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 add
和plugin ios add
来启动移动库项目并指导您进行所需的更改。
移动插件开发
插件可以运行使用Kotlin(或Java)和Swift编写的本地移动代码。默认插件模板包含一个使用Kotlin的Android库项目和Swift包。它包含一个示例移动命令,展示了如何从Rust代码中触发其执行。
有关为移动设备开发插件的更多信息,请参阅移动插件开发指南。
插件配置
在使用插件的Tauri应用程序中,插件配置在tauri.conf.json
中进行指定,其中plugin-name
是插件名称
{ "build": { ... }, "tauri": { ... }, "plugins": { "plugin-name": { "timeout": 30 } }}
插件配置在Builder
中设置,并在运行时解析。以下是使用Config
结构指定插件配置的示例
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:插件正在初始化
- on_navigation:WebView正在尝试执行导航
- on_webview_ready:正在创建新窗口
- on_event:事件循环事件
- on_drop:插件正在被销毁
对于移动插件,还有额外的生命周期事件。
setup
- 当:插件正在初始化
- 原因:注册移动插件、管理状态、运行后台任务
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
将取消导航。
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
- 当:已创建新窗口
- 原因:为每个窗口执行初始化脚本
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
- 当:事件循环事件
- 原因:处理核心事件,例如窗口事件、菜单事件和请求退出应用程序
使用此生命周期钩子,您可以通知任何事件循环事件。
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
。
use tauri::plugin::Builder;
Builder::new("<plugin-name>") .on_drop(|app| { // plugin has been destroyed... })
公开 Rust API
项目在desktop.rs
和mobile.rs
中定义的插件API作为具有与插件相同名称的结构体(大驼峰式命名法)导出到用户。当插件设置时,将创建此结构体的一个实例,并作为状态管理,以便用户可以在任何时候通过插件中定义的扩展特质(例如AppHandle
、App
或Window
)的实例检索它。
例如,全局快捷键插件
定义了一个可以通过使用GlobalShortcutExt
特质的global_shortcut
方法读取的GlobalShortcut
结构。
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命令的更多详细信息,请阅读命令指南。
此命令展示如何通过依赖注入访问AppHandle
和Window
实例,并接受两个输入参数(on_progress
和url
)。
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()
调用中进行挂钩。
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文件的。每个文件可以为权限列表、权限集合和插件默认权限定义列表。
权限
权限描述了插件命令的权限。它可以允许或拒绝一系列命令,并关联命令特定的和全局作用域。
"$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
插件允许启动的。
#[derive(Debug, schemars::JsonSchema)]pub struct Entry { pub binary: String,}
命令作用域
插件消费者可以在其能力文件中定义特定命令的作用域(请参阅文档)。您可以使用tauri::ipc::CommandScope
结构读取命令特定的作用域。
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!()}
全局作用域
当一个权限没有定义允许或拒绝的任何命令时,它被视为作用域权限,并且它应仅为插件定义全局作用域。
[[permission]]identifier = "allow-spawn-node"description = "This scope permits spawning the `node` binary."
[[permission.scope.allow]]binary = "node"
您可以使用tauri::ipc::GlobalScope
结构读取全局作用域。
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"
在您的构建脚本中,添加以下代码
#[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使用多个命令,或者如果一组命令之间存在逻辑联系,您应该定义一个包含它们的权限集。
"$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
插件是没有用的。
"$schema" = "schemas/schema.json"[default]description = "Allows making HTTP requests"permissions = ["allow-request"]
自动生成的权限
为您的每个命令定义权限的最简单方法是使用在 build.rs
文件中定义的插件构建脚本中的自动生成选项。在 COMMANDS
常量内部,以 snake_case(应与命令函数名匹配)定义命令列表,Tauri 将自动生成 allow-$commandname
和 deny-$commandname
权限。
以下示例生成了 allow-upload
和 deny-upload
权限
const COMMANDS: &[&str] = &["upload"];
fn main() { tauri_plugin::Builder::new(COMMANDS).build();}
有关更多信息,请参阅 权限概述 文档。
管理状态
插件可以以与 Tauri 应用程序相同的方式管理状态。有关更多信息,请参阅 状态管理指南。
© 2025 Tauri 贡献者。CC-BY / MIT