跳至主要内容

集成到现有项目

如果您已经有了一个现有的 Web 项目，本指南将引导您将 Tauri 集成到您的项目中，无论它是基于 Node.js 的（例如 Svelte、React、Vue 或 Angular）还是基于 Rust 的（例如 Yew 或 Dominator）。

信息

在继续之前，请确保您已完成 前提条件 以拥有一个可工作的开发环境。

虽然 Tauri 几乎兼容所有前端框架，但在本指南中，我们将使用使用 create-react-app 创建的 React 项目。我们将假设您从类似于此的项目结构开始

.
│── package.json
│── public
│   ╰── index.html
╰── src
    │── App.css
    │── App.jsx
    │── index.css
    ╰── index.js

创建 Rust 项目​

每个 Tauri 应用的核心都是一个 Rust 二进制文件，它通过名为 `tauri` 的 Rust crate 管理窗口、webview 和对操作系统的调用。此项目由 Cargo 管理，Cargo 是 Rust 的官方包管理器和通用构建工具。

我们的 Tauri CLI 在后台使用 Cargo，因此您很少需要直接与它交互。Cargo 还有许多通过我们的 CLI 未公开的有用功能，例如测试、代码检查和格式化，因此请参阅其 官方文档 以了解更多信息。

安装 Tauri CLI

如果您尚未安装 Tauri CLI，您可以使用以下命令之一进行安装。不确定使用哪个？查看 常见问题解答条目。

npm install --save-dev @tauri-apps/cli@">1.0.0"
为了让 npm 正确检测 Tauri，您需要将其添加到 `package.json` 文件的 "scripts" 部分
package.json
"scripts": {
  "tauri": "tauri"
}

要构建一个预配置为使用 Tauri 的最小 Rust 项目，请打开终端并运行以下命令

npm run tauri init

它将引导您完成一系列问题

  1. 您的应用名称是什么？
    这将是您的最终包的名称，也是操作系统对您的应用的称呼。您可以在这里使用任何您想要的名称。

  2. 窗口标题是什么？
    这将是默认主窗口的标题。您可以在这里使用任何您想要的标题。

  3. 您的 Web 资源（HTML/CSS/JS）相对于 ``/src-tauri/tauri.conf.json` 文件的位置是什么？
    这是 Tauri 在构建 **生产环境** 版本时将从中加载前端资源的路径。
    对于本指南中的项目示例，这是 `../build`。请注意，如果您使用的是不同的框架，它可能会有所不同，例如 `../dist`。

  4. 您的开发服务器的 URL 是什么？
    这可以是 URL 或文件路径，Tauri 将在 开发过程中加载。.
    对于本指南中的项目示例，这是 `https://127.0.0.1:3000`。请注意，如果您使用的是不同的框架，它可能会有所不同（甚至可能是目录）。

  5. 您的前端开发命令是什么？
    这是用于启动前端开发服务器的命令。
    对于本指南中的项目示例，这是 `npm run start`（确保调整此命令以使用您选择的包管理器）。

  6. 您的前端构建命令是什么？
    这是构建前端文件的命令。
    对于本指南中的项目示例，这是 `npm run build`（确保调整此命令以使用您选择的包管理器）。
信息

如果您熟悉 Rust，您会注意到 `tauri init` 看起来和工作方式与 `cargo init` 非常相似。如果您更喜欢完全手动设置，则可以使用 `cargo init` 并添加必要的 Tauri 依赖项。

`tauri init` 命令生成一个名为 `src-tauri` 的文件夹。对于 Tauri 应用，通常将所有核心相关文件放在此文件夹中。让我们快速浏览一下此文件夹的内容

  • Cargo.toml
    Cargo 的清单文件。您可以声明您的应用依赖的 Rust crate、关于您的应用的元数据等等。有关完整参考，请参阅 Cargo 的清单格式。

  • tauri.conf.json
    此文件允许您配置和自定义 Tauri 应用的各个方面，从应用名称到允许的 API 列表。有关支持选项的完整列表以及每个选项的详细说明，请参阅 Tauri 的 API 配置。

  • src/main.rs
    这是您的 Rust 程序的入口点，也是我们引导到 Tauri 的地方。您将在其中找到两个部分

    src/main.rs
     #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

    fn main() {
    tauri::Builder::default()
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
    }

    以 `cfg! 宏` 开头的行只有一个用途：它禁用通常在 Windows 上运行捆绑应用时会弹出的命令提示符窗口。如果您在 Windows 上，请尝试注释掉它并查看会发生什么。

    `main` 函数是入口点，也是程序运行时第一个被调用的函数。

  • icons
    您可能想要一个漂亮的应用图标！为了让您快速上手，我们包含了一组默认图标。您应该在发布应用之前更换这些图标。了解有关 Tauri 的 图标特性指南 中各种图标格式的更多信息。

就是这样，您现在已将 Tauri 添加到您的现有项目中，您应该会看到一个看起来像这样的 `src-tauri` 目录

│── package.json
│── public
│   ╰── index.html
│── src
│   │── App.css
│   │── App.jsx
│   │── index.css
│   ╰── index.js
╰── src-tauri
    │── Cargo.toml
    │── build.rs
    │── icons
    │── src
    ╰── tauri.conf.json

调用命令​

Tauri 允许您使用原生功能增强您的前端。我们称这些为 命令，本质上是您可以从前端 JavaScript 调用的 Rust 函数。这使您可以以更高效的 Rust 代码处理繁重的处理或对操作系统的调用。

让我们做一个简单的例子

src-tauri/src/main.rs
#[tauri::command]
fn greet(name: &str) -> String {
   format!("Hello, {}!", name)
}

命令就像任何普通的 Rust 函数一样，附加了 `#[tauri::command]` 属性宏，允许您的函数与 JavaScript 上下文通信。

最后，我们还需要告诉 Tauri 我们新创建的命令，以便它可以相应地路由调用。这是通过结合使用 `invoke_handler()` 函数和您可以在下面看到的 `generate_handler![]` 宏来完成的

src-tauri/src/main.rs
fn main() {
  tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![greet])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

现在您可以从前端调用您的命令了！

您可以通过两种不同的方式从前端项目调用命令

  1. 使用 `@tauri-apps/api` JavaScript 库（推荐）
  2. 使用 `withGlobalTauri` 来使用预捆绑版本的 Tauri API

我们将在下面介绍两者。

使用 JavaScript 库​

为了调用我们新创建的命令，我们将使用 `@tauri-apps/api` JavaScript 库。它通过方便的 JavaScript 抽象提供了对核心功能（例如窗口、文件系统等）的访问。您可以使用您最喜欢的 JavaScript 包管理器安装它

npm install @tauri-apps/api@">1.0.0"

您现在可以从库中导入 `invoke` 函数并使用它来调用我们的命令

src/App.jsx
import logo from './logo.svg';
import './App.css';

import { invoke } from '@tauri-apps/api'

function App() {
  // now we can call our Command!
  // Right-click the application background and open the developer tools.
  // You will see "Hello, World!" printed in the console!
  invoke('greet', { name: 'World' })
  // `invoke` returns a Promise
  .then((response) => console.log(response))

  return (
    // -- snip --
  )
}

使用 `withGlobalTauri`​

要从您的前端与 Tauri 交互而不使用 `@tauri-apps/api` JavaScript 包，您需要在 `tauri.conf.json` 文件中启用 `withGlobalTauri`

tauri.conf.json
{
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devPath": "https://127.0.0.1:3000",
    "distDir": "../build",
    "withGlobalTauri": true
  },

这会将预捆绑版本的 API 函数注入到您的前端。

您现在可以修改 `App.jsx` 文件来调用您的命令

src/App.js
import logo from './logo.svg';
import './App.css';

// access the pre-bundled global API functions
const { invoke } = window.__TAURI__.tauri

function App() {
  // now we can call our Command!
  // Right-click the application background and open the developer tools.
  // You will see "Hello, World!" printed in the console!
  invoke('greet', { name: 'World' })
  // `invoke` returns a Promise
  .then((response) => console.log(response))

  return (
    // -- snip --
  )
}

运行您的应用​

您现在可以在终端中运行以下命令来启动应用的开发版本

npm run tauri dev
提示

如果您想了解有关 Rust 和 JavaScript 之间通信的更多信息，请阅读 Tauri 的 进程间通信 指南。