Tauri教程-进阶篇-第二节 命令机制

“如果结果不如你所愿，就在尘埃落定前奋力一搏。”——《夏目友人帐》
“有些事不是看到了希望才去坚持，而是因为坚持才会看到希望。”——《十宗罪》
“维持现状意味着空耗你的努力和生命。”——纪伯伦

Tauri 技术教程 * 第五章 Tauri的进阶教程
第二节 命令机制

一. 概述

本章节中我们将了解在前端项目中，如何调用Rust端的代码。

Tauri 提供了一个简单但功能强大的command系统，用于从 Web 应用调用 Rust 函数。命令可以接受参数并返回值。它们还可以返回错误和async。

二. 命令机制

Tauri 提供了一个命令功能，用于以类型安全的方式访问 Rust 函数，以及一个动态的事件系统。本章节我们先了解下他们的概念，然后了解它的工作内容和方式。

1. 命令 Command

Tauri 提供了一个简单但功能强大的command系统，用于从 Web 应用调用 Rust 函数。命令可以接受参数并返回值。它们还可以返回错误和async。

2. 基本概念

1. 命令注释

定义的命令需要采用 注释#[tauri::command] 进行修饰。如下：

#[tauri::command]
fn my_custom_command() {println!("I was invoked from JavaScript!");
}

命令的构成由：

• 注释

• Rust函数基本构成

  这里要注意：命令名称必须全局唯一。

2. 构造函数注入

通过构建函数进行注入，tauri::generate_handler 如下：

tauri::generate_handler![my_custom_command]

3. Invoke 函数

invoke函数的获取方式有2种

• api 方式获取

  import { invoke } from ‘@tauri-apps/api/core’;

• 全局命令获取

  1. 在tauri.conf.json 中配置 app.withGlobalTauri 为true；
  2. const invoke = window.TAURI.core.invoke;

前端调用方式：

invoke('my_custom_command');

4. 参数定义

参数定义的方式如下：

#[tauri::command]
fn my_custom_command(invoke_message: String) {println!("I was invoked from JavaScript, with this message: {}", invoke_message);
}

调用方式如下：

invoke('my_custom_command', { invokeMessage: 'Hello!' });

这里注意下：前端参数的名称与后端参数的名称：

后端是invoke_message，前端是json 需要是：invokeMessage，如果你需要保持一致可以采用snake_case 属性进行指定，如下：

#[tauri::command(rename_all = "snake_case")]
fn my_custom_command(invoke_message: String) {}invoke('my_custom_command', { invoke_message: 'Hello!' });

5. 返回值定义

返回值的定义：实例如下，和普通的函数定义没有区别

#[tauri::command]
fn my_custom_command() -> String {"Hello from Rust!".into()
}

在前端处理时，invoke 函数返回的是一个 promise，使用方式如下：

invoke('my_custom_command').then((message) => console.log(message));

返回大批量数据或者文件流时，需要结合 tauri::ipc::Response 来使用，方式如下：

use tauri::ipc::Response;
#[tauri::command]
fn read_file() -> Response {let data = std::fs::read("/path/to/file").unwrap();tauri::ipc::Response::new(data)
}

3. 异常处理

在Tauri 编程中，异常或者错误的处理需要 实现serde::Serialize，在程序开发中我闷可以使用Result 来返回处理信息，也可以自定义错误来返回处理信息，下面我闷来演示下，如何使用这2种方式

• Result 的处理

  #[tauri::command]
  fn login(user: String, password: String) -> Result<String, String> {if user == "tauri" && password == "tauri" {// resolveOk("logged_in".to_string())} else {// rejectErr("invalid credentials".to_string())}
  }
  

• 自定义错误类型,这里我们使用thiserror库辅助构建

  #[derive(Debug, thiserror::Error)]
  enum Error {#[error(transparent)]Io(#[from] std::io::Error),#[error("failed to parse as string: {0}")]Utf8(#[from] std::str::Utf8Error),
  }#[derive(serde::Serialize)]
  #[serde(tag = "kind", content = "message")]
  #[serde(rename_all = "camelCase")]
  enum ErrorKind {Io(String),Utf8(String),
  }impl serde::Serialize for Error {fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>whereS: serde::ser::Serializer,{let error_message = self.to_string();let error_kind = match self {Self::Io(_) => ErrorKind::Io(error_message),Self::Utf8(_) => ErrorKind::Utf8(error_message),};error_kind.serialize(serializer)}
  }#[tauri::command]
  fn read() -> Result<Vec<u8>, Error> {let data = std::fs::read("/path/to/file")?;Ok(data)
  }
  

  此时我们在前端使用Invoke的catch 捕获时就会得到一个 { kind: ‘io’ | ‘utf8’, message: string }`错误对象：

  type ErrorKind = {kind: 'io' | 'utf8';message: string;
  };invoke('read').catch((e: ErrorKind) => {});
  

4. 异步操作

异步操作也是我们在交互种普遍采用的一种方式，那么在tauri中我们怎么去实现它，

开启的方式比较简单，只需要在命令需要异步运行，将其声明为async，如下：

#[tauri::command]
async fn my_custom_command(value: String) -> String {.......
}

在 async 操作需要注意

异步命令使用 在单独的异步任务上执行，没有async 的命令将在主线程上执行

异步返回类型的定义：

在返回类型的定义时，推荐大家采用Result<a,b>的方式来进行处理；

• Result<String, ()>返回一个字符串，并且没有错误。
• Result<(), ()>返回null。
• Result<bool, Error>返回布尔值或错误。

代码示例：

// Result<String, ()>
#[tauri::command]
async fn my_custom_command(value: &str) -> Result<String, ()> {some_async_function().await;Ok(format!(value))
}

前端的处理方式：没有什么区别

invoke('my_custom_command', { value: 'Hello, Async!' }).then(() =>console.log('Completed!')
);

5. 数据传输

在Tauri 项目开发中，我们会遇到流的操作，关于如何操作流，Tauri 提供了通道技术，用于应对流传输的数据机制。即： tauri::ipc::Channel；例如下载进度、子进程输出和 WebSocket 消息。

使用起来也是比较简单的，下面我们来看一个下载的示例代码

在Rest中定义下载命令

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();
}

以上示例中我们定义了2个内容：

• DownloadEvent

  枚举类，里面包含了下载文件的信息（地址 大小 id），进度

• download

  接受2个参数，一个下载地址，一个事件处理

前端代码：

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: 'xxxxxx',onEvent,
});

6. 命令交互

在定义的命令中，我们可以访问 WebviewWindow AppHandle 状态 原始请求对象，下面我们来具体看下如何去使用他们

1. 访问 WebviewWindow

#[tauri::command]
async fn my_custom_command(webview_window: tauri::WebviewWindow) {println!("WebviewWindow: {}", webview_window.label());
}

2. 访问 WebviewWindow

#[tauri::command]
async fn my_custom_command(app_handle: tauri::AppHandle) {let app_dir = app_handle.path_resolver().app_dir();use tauri::GlobalShortcutManager;app_handle.global_shortcut_manager().register("CTRL + U", move || {});
}

3. 访问状态

状态我们会在后续的状态管理中详细了解它，这里我们先了解操作它的方式，在状态管理中我闷还会在进行探讨。

Tauri 通过 tauri::Builder.manage 来绑定和管理状态，使用时科通过tauri::State 处理绑定的状态即可

如下：

// 定义一个状态信息
struct MyState(String);#[tauri::command]
fn my_custom_command(state: tauri::State<MyState>) {  // 使用assert_eq!(state.0 == "some state value", true);
}#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {tauri::Builder::default()// 绑定并管理.manage(MyState("some state value".into())).invoke_handler(tauri::generate_handler![my_custom_command]).run(tauri::generate_context!()).expect("error while running tauri application");
}

4. 访问 请求对象

在请求处理中，有时我们需要访问包含原始主体有效信息和请求标头的完整对象，可以通过tauri::ipc::Request对象进行处理

#[tauri::command]
fn upload(request: tauri::ipc::Request) -> Result<(), Error> {// request.body()  request.headers()// upload...Ok(())
}

在前端，你可以调用invoke()来发送原始请求体，

__TAURI__.core.invoke('upload', {}, {headers: {Authorization: 'apikey',},
});

7. 命令抽取

在项目开发中，我们不可能将所有的命令都定义在主程序中，这样不利于开发管理，也不利于修改，通常我们会将命令单独提取为一个文件或者多个文件，在主程序中使用他们，以达到开发分工的情况，提升开发效率和维护便捷性。

• 定义一个command.rs 在 src-tauri src 目录下

  #[tauri::command]
  fn cmd_a() -> String {"Command a".to_string()
  }#[tauri::command]
  fn cmd_b() -> String {"asdsa".to_string()
  }// Learn more about Tauri commands at https://tauri.app/develop/calling-rust/
  #[tauri::command]
  pub fn greet(name: &str) -> String {format!("Hello, {}! You've been greeted from Rust!", name)
  }

• 在main 中 配置

  mod command;#[cfg_attr(mobile, tauri::mobile_entry_point)]
  pub fn run() {tauri::Builder::default().....invoke_handler(tauri::generate_handler![command::greet]).....
  }