跳转到内容
Tauri
指南 参考 博客 发布

从 Rust 调用前端

本文档包含关于如何从 Rust 代码与应用程序前端通信的指南。要了解如何从前端与 Rust 代码通信，请参阅从前端调用 Rust。

Tauri 应用程序的 Rust 端可以通过利用 Tauri 事件系统、使用通道或直接评估 JavaScript 代码来调用前端。

事件系统

Tauri 提供了一个简单的事件系统，您可以使用它在 Rust 和前端之间进行双向通信。

事件系统设计用于需要少量数据流式传输或需要实现多消费者多生产者模式（例如，推送通知系统）的情况。

事件系统并非为低延迟或高吞吐量情况而设计。有关为流式传输数据优化的实现，请参阅通道部分。

Tauri 命令和 Tauri 事件之间的主要区别在于，事件没有强类型支持，事件有效载荷始终是 JSON 字符串，这使得它们不适合较大的消息，并且不支持功能系统来精细控制事件数据和通道。

AppHandle 和 WebviewWindow 类型实现了事件系统 traits Listener 和 Emitter。

事件可以是全局的（传递给所有监听器）或 webview 特定的（仅传递给与给定标签匹配的 webview）。

全局事件

要触发全局事件，您可以使用 Emitter#emit 函数

src-tauri/src/lib.rs
use tauri::{AppHandle, Emitter};


#[tauri::command]
fn download(app: AppHandle, url: String) {
  app.emit("download-started", &url).unwrap();
  for progress in [1, 15, 50, 80, 100] {
    app.emit("download-progress", progress).unwrap();
  }
  app.emit("download-finished", &url).unwrap();
}

Webview 事件

要将事件触发到特定 webview 注册的监听器，您可以使用 Emitter#emit_to 函数

src-tauri/src/lib.rs
use tauri::{AppHandle, Emitter};


#[tauri::command]
fn login(app: AppHandle, user: String, password: String) {
  let authenticated = user == "tauri-apps" && password == "tauri";
  let result = if authenticated { "loggedIn" } else { "invalidCredentials" };
  app.emit_to("login", "login-result", result).unwrap();
}

也可以通过调用 Emitter#emit_filter 将事件触发到 webview 列表。在以下示例中，我们将 open-file 事件发送到 main 和 file-viewer webview

src-tauri/src/lib.rs
use tauri::{AppHandle, Emitter, EventTarget};


#[tauri::command]
fn open_file(app: AppHandle, path: std::path::PathBuf) {
  app.emit_filter("open-file", path, |target| match target {
    EventTarget::WebviewWindow { label } => label == "main" || label == "file-viewer",
    _ => false,
  }).unwrap();
}

事件有效载荷

事件有效载荷可以是任何 可序列化 类型，该类型也实现了 Clone。让我们通过使用对象在每个事件中发出更多信息来增强下载事件示例

src-tauri/src/lib.rs
use tauri::{AppHandle, Emitter};
use serde::Serialize;


#[derive(Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct DownloadStarted<'a> {
  url: &'a str,
  download_id: usize,
  content_length: usize,
}


#[derive(Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct DownloadProgress {
  download_id: usize,
  chunk_length: usize,
}


#[derive(Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct DownloadFinished {
  download_id: usize,
}


#[tauri::command]
fn download(app: AppHandle, url: String) {
  let content_length = 1000;
  let download_id = 1;


  app.emit("download-started", DownloadStarted {
    url: &url,
    download_id,
    content_length
  }).unwrap();


  for chunk_length in [15, 150, 35, 500, 300] {
    app.emit("download-progress", DownloadProgress {
      download_id,
      chunk_length,
    }).unwrap();
  }


  app.emit("download-finished", DownloadFinished { download_id }).unwrap();
}

监听事件

Tauri 提供了 API 来监听 webview 和 Rust 接口上的事件。

在前端监听事件

@tauri-apps/api NPM 包提供了 API 来监听全局和 webview 特定的事件。

  • 监听全局事件

    import { listen } from '@tauri-apps/api/event';
    

    type DownloadStarted = {
      url: string;
      downloadId: number;
      contentLength: number;
    };
    

    listen<DownloadStarted>('download-started', (event) => {
      console.log(
        `downloading ${event.payload.contentLength} bytes from ${event.payload.url}`
      );
    });

  • 监听 webview 特定的事件

    import { getCurrentWebviewWindow } from '@tauri-apps/api/webviewWindow';
    

    const appWebview = getCurrentWebviewWindow();
    appWebview.listen<string>('logged-in', (event) => {
      localStorage.setItem('session-token', event.payload);
    });

listen 函数会使事件监听器在应用程序的整个生命周期内保持注册状态。要停止监听事件，您可以使用 unlisten 函数，该函数由 listen 函数返回

import { listen } from '@tauri-apps/api/event';


const unlisten = await listen('download-started', (event) => {});
unlisten();

此外，Tauri 提供了一个实用函数，用于精确监听一次事件

import { once } from '@tauri-apps/api/event';
import { getCurrentWebviewWindow } from '@tauri-apps/api/webviewWindow';


once('ready', (event) => {});


const appWebview = getCurrentWebviewWindow();
appWebview.once('ready', () => {});

在 Rust 上监听事件

全局和 webview 特定的事件也会传递给在 Rust 中注册的监听器。

  • 监听全局事件

    src-tauri/src/lib.rs
    use tauri::Listener;
    

    #[cfg_attr(mobile, tauri::mobile_entry_point)]
    pub fn run() {
      tauri::Builder::default()
        .setup(|app| {
          app.listen("download-started", |event| {
            if let Ok(payload) = serde_json::from_str::<DownloadStarted>(&event.payload()) {
              println!("downloading {}", payload.url);
            }
          });
          Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
    }

  • 监听 webview 特定的事件

    src-tauri/src/lib.rs
    use tauri::{Listener, Manager};
    

    #[cfg_attr(mobile, tauri::mobile_entry_point)]
    pub fn run() {
      tauri::Builder::default()
        .setup(|app| {
          let webview = app.get_webview_window("main").unwrap();
          webview.listen("logged-in", |event| {
            let session_token = event.data;
            // save token..
          });
          Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
    }

listen 函数会使事件监听器在应用程序的整个生命周期内保持注册状态。要停止监听事件，您可以使用 unlisten 函数

// unlisten outside of the event handler scope:
let event_id = app.listen("download-started", |event| {});
app.unlisten(event_id);


// unlisten when some event criteria is matched
let handle = app.handle().clone();
app.listen("status-changed", |event| {
  if event.data == "ready" {
    handle.unlisten(event.id);
  }
});

此外，Tauri 提供了一个实用函数，用于精确监听一次事件

app.once("ready", |event| {
  println!("app is ready");
});

在这种情况下，事件监听器会在其第一次触发后立即取消注册。

通道

事件系统旨在成为应用程序中全局可用的简单双向通信。在底层，它直接评估 JavaScript 代码，因此可能不适合发送大量数据。

通道旨在快速并传递有序数据。它们在内部用于流式传输操作，例如下载进度、子进程输出和 WebSocket 消息。

让我们重写我们的下载命令示例以使用通道而不是事件系统

src-tauri/src/lib.rs
use tauri::{AppHandle, ipc::Channel};
use serde::Serialize;


#[derive(Clone, Serialize)]
#[serde(rename_all = "camelCase", tag = "event", content = "data")]
enum DownloadEvent<'a> {
  #[serde(rename_all = "camelCase")]
  Started {
    url: &'a str,
    download_id: usize,
    content_length: usize,
  },
  #[serde(rename_all = "camelCase")]
  Progress {
    download_id: usize,
    chunk_length: usize,
  },
  #[serde(rename_all = "camelCase")]
  Finished {
    download_id: usize,
  },
}


#[tauri::command]
fn download(app: AppHandle, url: String, on_event: Channel<DownloadEvent>) {
  let content_length = 1000;
  let download_id = 1;


  on_event.send(DownloadEvent::Started {
    url: &url,
    download_id,
    content_length,
  }).unwrap();


  for chunk_length in [15, 150, 35, 500, 300] {
    on_event.send(DownloadEvent::Progress {
      download_id,
      chunk_length,
    }).unwrap();
  }


  on_event.send(DownloadEvent::Finished { download_id }).unwrap();
}

调用 download 命令时，您必须创建通道并将其作为参数提供

import { invoke, Channel } from '@tauri-apps/api/core';


type DownloadEvent =
  | {
      event: 'started';
      data: {
        url: string;
        downloadId: number;
        contentLength: number;
      };
    }
  | {
      event: 'progress';
      data: {
        downloadId: number;
        chunkLength: number;
      };
    }
  | {
      event: 'finished';
      data: {
        downloadId: number;
      };
    };


const onEvent = new Channel<DownloadEvent>();
onEvent.onmessage = (message) => {
  console.log(`got download event ${message.event}`);
};


await invoke('download', {
  url: 'https://raw.githubusercontent.com/tauri-apps/tauri/dev/crates/tauri-schema-generator/schemas/config.schema.json',
  onEvent,
});

评估 JavaScript

要直接在 webview 上下文中执行任何 JavaScript 代码，您可以使用 WebviewWindow#eval 函数

src-tauri/src/lib.rs
use tauri::Manager;


tauri::Builder::default()
  .setup(|app| {
    let webview = app.get_webview_window("main").unwrap();
    webview.eval("console.log('hello from Rust')")?;
    Ok(())
  })

如果待评估的脚本不是那么简单，并且必须使用来自 Rust 对象的数据，我们建议使用 serialize-to-javascript crate。

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