跳至主要內容

Tauri 外掛程式

外掛程式可讓您連接至 Tauri 應用程式生命週期並引入新的指令。

使用外掛程式​

若要使用外掛程式，只需將外掛程式執行個體傳遞至應用程式的 plugin 方法

fn main() {
  tauri::Builder::default()
    .plugin(my_awesome_plugin::init())
    .run(tauri::generate_context!())
    .expect("failed to run app");
}

撰寫外掛程式​

外掛程式是 Tauri API 的可重複使用延伸功能，可解決常見問題。它們也是整理程式碼庫的便利方式！

如果您打算與他人分享您的外掛程式，我們提供了一個現成的範本！只要安裝 Tauri 的 CLI，然後執行

npm run tauri plugin init -- --name awesome

API 套件​

預設情況下，外掛程式的使用者可以這樣呼叫提供的指令

import { invoke } from '@tauri-apps/api'
invoke('plugin:awesome|do_something')

其中 awesome 將會替換成您的外掛程式名稱。

然而，這並不方便，因此外掛程式通常會提供所謂的API 套件，一個提供方便存取指令的 JavaScript 套件。

一個範例是 tauri-plugin-store，它提供一個方便的類別結構來存取儲存體。您可以這樣建立一個附有 JavaScript API 套件的 tauri 外掛程式

npm run tauri plugin init -- --name awesome --api

撰寫外掛程式​

使用 tauri::plugin::Builder，您可以定義與定義應用程式相似的外掛程式

use tauri::{
  plugin::{Builder, TauriPlugin},
  Runtime,
};

// the plugin custom command handlers if you choose to extend the API:

#[tauri::command]
// this will be accessible with `invoke('plugin:awesome|initialize')`.
// where `awesome` is the plugin name.
fn initialize() {}

#[tauri::command]
// this will be accessible with `invoke('plugin:awesome|do_something')`.
fn do_something() {}

pub fn init<R: Runtime>() -> TauriPlugin<R> {
  Builder::new("awesome")
    .invoke_handler(tauri::generate_handler![initialize, do_something])
    .build()
}

外掛程式可以設定和維護狀態，就像您的應用程式一樣

use tauri::{
  plugin::{Builder, TauriPlugin},
  AppHandle, Manager, Runtime, State,
};

#[derive(Default)]
struct MyState {}

#[tauri::command]
// this will be accessible with `invoke('plugin:awesome|do_something')`.
fn do_something<R: Runtime>(_app: AppHandle<R>, state: State<'_, MyState>) {
  // you can access `MyState` here!
}

pub fn init<R: Runtime>() -> TauriPlugin<R> {
  Builder::new("awesome")
    .invoke_handler(tauri::generate_handler![do_something])
    .setup(|app_handle| {
      // setup plugin specific state here
      app_handle.manage(MyState::default());
      Ok(())
    })
    .build()
}

慣例​

  • 此板條箱匯出一個 init 方法來建立外掛程式。
  • 外掛程式應具有明確的名稱，並加上 tauri-plugin- 前綴。
  • 在 Cargo.toml/package.json 中包含 tauri-plugin 關鍵字。
  • 以英文撰寫外掛程式的文件。
  • 新增一個展示外掛程式的範例應用程式。

進階​

您可以實作 tauri::plugin::Plugin，而不是依賴 tauri::plugin::Builder::build 回傳的 tauri::plugin::TauriPlugin 結構。這讓您可以完全控制相關資料。

請注意，除了 name 函式外，Plugin 特質上的每個函式都是選用的。

use tauri::{plugin::{Plugin, Result as PluginResult}, Runtime, PageLoadPayload, Window, Invoke, AppHandle};

struct MyAwesomePlugin<R: Runtime> {
  invoke_handler: Box<dyn Fn(Invoke<R>) + Send + Sync>,
  // plugin state, configuration fields
}

// the plugin custom command handlers if you choose to extend the API.
#[tauri::command]
// this will be accessible with `invoke('plugin:awesome|initialize')`.
// where `awesome` is the plugin name.
fn initialize() {}

#[tauri::command]
// this will be accessible with `invoke('plugin:awesome|do_something')`.
fn do_something() {}

impl<R: Runtime> MyAwesomePlugin<R> {
  // you can add configuration fields here,
  // see https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
  pub fn new() -> Self {
    Self {
      invoke_handler: Box::new(tauri::generate_handler![initialize, do_something]),
    }
  }
}

impl<R: Runtime> Plugin<R> for MyAwesomePlugin<R> {
  /// The plugin name. Must be defined and used on the `invoke` calls.
  fn name(&self) -> &'static str {
    "awesome"
  }

  /// The JS script to evaluate on initialization.
  /// Useful when your plugin is accessible through `window`
  /// or needs to perform a JS task on app initialization
  /// e.g. "window.awesomePlugin = { ... the plugin interface }"
  fn initialization_script(&self) -> Option<String> {
    None
  }

  /// initialize plugin with the config provided on `tauri.conf.json > plugins > $yourPluginName` or the default value.
  fn initialize(&mut self, app: &AppHandle<R>, config: serde_json::Value) -> PluginResult<()> {
    Ok(())
  }

  /// Callback invoked when the Window is created.
  fn created(&mut self, window: Window<R>) {}

  /// Callback invoked when the webview performs navigation.
  fn on_page_load(&mut self, window: Window<R>, payload: PageLoadPayload) {}

  /// Extend the invoke handler.
  fn extend_api(&mut self, message: Invoke<R>) {
    (self.invoke_handler)(message)
  }
}