pub struct Builder<R: Runtime, C: DeserializeOwned = ()> { /* private fields */ }
Expand description
Builds a TauriPlugin
.
This Builder offers a more concise way to construct Tauri plugins than implementing the Plugin trait directly.
Conventions
When using the Builder Pattern it is encouraged to export a function called init
that constructs and returns the plugin.
While plugin authors can provide every possible way to construct a plugin,
sticking to the init
function convention helps users to quickly identify the correct function to call.
use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
pub fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.build()
}
When plugins expose more complex configuration options, it can be helpful to provide a Builder instead:
use tauri::{plugin::{Builder as PluginBuilder, TauriPlugin}, Runtime};
pub struct Builder {
option_a: String,
option_b: String,
option_c: bool
}
impl Default for Builder {
fn default() -> Self {
Self {
option_a: "foo".to_string(),
option_b: "bar".to_string(),
option_c: false
}
}
}
impl Builder {
pub fn new() -> Self {
Default::default()
}
pub fn option_a(mut self, option_a: String) -> Self {
self.option_a = option_a;
self
}
pub fn option_b(mut self, option_b: String) -> Self {
self.option_b = option_b;
self
}
pub fn option_c(mut self, option_c: bool) -> Self {
self.option_c = option_c;
self
}
pub fn build<R: Runtime>(self) -> TauriPlugin<R> {
PluginBuilder::new("example")
.setup(move |app_handle| {
// use the options here to do stuff
println!("a: {}, b: {}, c: {}", self.option_a, self.option_b, self.option_c);
Ok(())
})
.build()
}
}
Implementations§
source§impl<R: Runtime, C: DeserializeOwned> Builder<R, C>
impl<R: Runtime, C: DeserializeOwned> Builder<R, C>
sourcepub fn invoke_handler<F>(self, invoke_handler: F) -> Self
pub fn invoke_handler<F>(self, invoke_handler: F) -> Self
Defines the JS message handler callback. It is recommended you use the tauri::generate_handler to generate the input to this method, as the input type is not considered stable yet.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
#[tauri::command]
async fn foobar<R: Runtime>(app: tauri::AppHandle<R>, window: tauri::Window<R>) -> Result<(), String> {
println!("foobar");
Ok(())
}
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.invoke_handler(tauri::generate_handler![foobar])
.build()
}
sourcepub fn js_init_script(self, js_init_script: String) -> Self
pub fn js_init_script(self, js_init_script: String) -> Self
Sets the provided JavaScript to be run after the global object has been created, but before the HTML document has been parsed and before any other script included by the HTML document is run.
Since it runs on all top-level document and child frame page navigations,
it’s recommended to check the window.location
to guard your script from running on unexpected origins.
The script is wrapped into its own context with (function () { /* your script here */ })();
,
so global variables must be assigned to window
instead of implicitly declared.
Note that calling this function multiple times overrides previous values.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
const INIT_SCRIPT: &str = r#"
if (window.location.origin === 'https://tauri.app') {
console.log("hello world from js init script");
window.__MY_CUSTOM_PROPERTY__ = { foo: 'bar' };
}
"#;
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.js_init_script(INIT_SCRIPT.to_string())
.build()
}
sourcepub fn setup<F>(self, setup: F) -> Self
pub fn setup<F>(self, setup: F) -> Self
Define a closure that runs when the plugin is registered.
This is a convenience function around setup_with_config, without the need to specify a configuration object.
The closure gets called before the setup_with_config closure.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, Runtime, Manager};
use std::path::PathBuf;
#[derive(Debug, Default)]
struct PluginState {
dir: Option<PathBuf>
}
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.setup(|app_handle| {
app_handle.manage(PluginState::default());
Ok(())
})
.build()
}
sourcepub fn setup_with_config<F>(self, setup_with_config: F) -> Self
pub fn setup_with_config<F>(self, setup_with_config: F) -> Self
Define a closure that runs when the plugin is registered, accepting a configuration object set on tauri.conf.json > plugins > yourPluginName
.
If your plugin is not pulling a configuration object from tauri.conf.json
, use setup.
The closure gets called after the setup closure.
Examples
#[derive(serde::Deserialize)]
struct Config {
api_url: String,
}
fn init<R: tauri::Runtime>() -> tauri::plugin::TauriPlugin<R, Config> {
tauri::plugin::Builder::<R, Config>::new("api")
.setup_with_config(|_app_handle, config| {
println!("config: {:?}", config.api_url);
Ok(())
})
.build()
}
tauri::Builder::default().plugin(init());
sourcepub fn on_page_load<F>(self, on_page_load: F) -> Self
pub fn on_page_load<F>(self, on_page_load: F) -> Self
Callback invoked when the webview performs a navigation to a page.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.on_page_load(|window, payload| {
println!("Loaded URL {} in window {}", payload.url(), window.label());
})
.build()
}
sourcepub fn on_webview_ready<F>(self, on_webview_ready: F) -> Self
pub fn on_webview_ready<F>(self, on_webview_ready: F) -> Self
Callback invoked when the webview is created.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.on_webview_ready(|window| {
println!("created window {}", window.label());
})
.build()
}
sourcepub fn on_event<F>(self, on_event: F) -> Self
pub fn on_event<F>(self, on_event: F) -> Self
Callback invoked when the event loop receives a new event.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, RunEvent, Runtime};
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.on_event(|app_handle, event| {
match event {
RunEvent::ExitRequested { api, .. } => {
// Prevents the app from exiting.
// This will cause the core thread to continue running in the background even without any open windows.
api.prevent_exit();
}
// Ignore all other cases.
_ => {}
}
})
.build()
}
sourcepub fn on_drop<F>(self, on_drop: F) -> Self
pub fn on_drop<F>(self, on_drop: F) -> Self
Callback invoked when the plugin is dropped.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("example")
.on_drop(|app| {
println!("plugin has been dropped and is no longer running");
// you can run cleanup logic here
})
.build()
}
sourcepub fn register_uri_scheme_protocol<N: Into<String>, H: Fn(&AppHandle<R>, &HttpRequest) -> Result<HttpResponse, Box<dyn Error>> + Send + Sync + 'static>(
self,
uri_scheme: N,
protocol: H
) -> Self
pub fn register_uri_scheme_protocol<N: Into<String>, H: Fn(&AppHandle<R>, &HttpRequest) -> Result<HttpResponse, Box<dyn Error>> + Send + Sync + 'static>( self, uri_scheme: N, protocol: H ) -> Self
Registers a URI scheme protocol available to all webviews. Leverages setURLSchemeHandler on macOS, AddWebResourceRequestedFilter on Windows and webkit-web-context-register-uri-scheme on Linux.
Known limitations
URI scheme protocols are registered when the webview is created. Due to this limitation, if the plugin is registed after a webview has been created, this protocol won’t be available.
Arguments
uri_scheme
The URI scheme to register, such asexample
.protocol
the protocol associated with the given URI scheme. It’s a function that takes an URL such asexample://localhost/asset.css
.
Examples
use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
fn init<R: Runtime>() -> TauriPlugin<R> {
Builder::new("myplugin")
.register_uri_scheme_protocol("myscheme", |app, req| {
tauri::http::ResponseBuilder::new().body(Vec::new())
})
.build()
}
sourcepub fn build(self) -> TauriPlugin<R, C>
pub fn build(self) -> TauriPlugin<R, C>
Builds the TauriPlugin.