跳至主要內容

整合至現有專案

如果你已經有現有的網頁專案，本指南將引導你將 Tauri 整合到你的專案中，無論它是基於 Node.js（例如 Svelte、React、Vue 或 Angular）或基於 Rust（例如 Yew 或 Dominator）。

資訊

在我們繼續之前，請確保你已完成 先決條件 以建立一個運作中的開發環境。

儘管 Tauri 與幾乎任何前端框架相容，我們將在本指南中使用 React 專案，該專案是使用 create-react-app 建立的。我們假設你從類似於以下的專案結構開始

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

建立 Rust 專案​

每個 Tauri 應用程式的核心都是一個 Rust 二進位檔，它透過一個名為 tauri 的 Rust 箱子來管理視窗、網頁視圖，以及呼叫作業系統。這個專案由 Cargo 管理，這是 Rust 的官方套件管理員和通用建置工具。

我們的 Tauri CLI 在幕後使用 Cargo，因此你很少需要直接與它互動。Cargo 有許多未透過我們的 CLI 公開的更多有用功能，例如測試、程式碼檢查和格式化，因此請參閱他們的 官方文件 以了解更多資訊。

安裝 Tauri CLI

如果你尚未安裝 Tauri CLI，你可以使用以下命令之一來安裝。不確定要使用哪一個？查看 常見問題解答條目。

npm install --save-dev @tauri-apps/cli
要讓 npm 正確偵測 Tauri，你需要將它新增到 package.json 檔案中的「scripts」區段
package.json
"scripts": {
  "tauri": "tauri"
}

要建立一個預先設定為使用 Tauri 的最小 Rust 專案，請開啟終端機並執行以下命令

npm run tauri init

它會引導你完成一系列問題

  1. 你的應用程式名稱是什麼？
    這將會是你最終套件的名稱，以及作業系統會如何稱呼你的應用程式。你可以在這裡使用任何你想要的。名稱

  2. 視窗標題應該是什麼？
    這將會是預設主視窗的標題。你可以在這裡使用任何你想要的標題。

  3. 你的網路資產 (HTML/CSS/JS) 相對於即將建立的 <current dir>/src-tauri/tauri.conf.json 檔案位於何處？
    這是 Tauri 在針對生產環境進行建置時，會從中載入你的前端資產的路徑。
    對於本指南中的專案範例，路徑為 ../build。請注意，如果你使用的是不同的架構，路徑可能會有所不同，例如 ../dist。

  4. 你的開發伺服器的 URL 是什麼？
    這可以是 URL 或檔案路徑，Tauri 會在開發期間載入。
    對於本指南中的專案範例，URL 為 http://localhost:3000。請注意，如果你使用的是不同的架構，URL 可能會有所不同（甚至可能是目錄）。

  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 板條箱、應用程式的元資料，以及更多內容。有關完整參考，請參閱 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 函式是進入點，也是程式執行時第一個被呼叫的函式。

  • 圖示
    您很可能想要為應用程式使用炫麗的圖示！為了讓您快速上手，我們包含了一組預設圖示。您應該在發布應用程式前將這些圖示替換掉。進一步了解 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

現在，您可以從函式庫匯入 `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-apps/api` JavaScript 套件的情況下從前端與 Tauri 互動，您需要在 `tauri.conf.json` 檔案中啟用 withGlobalTauri

tauri.conf.json
{
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devPath": "http://localhost: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 處理程序間通訊指南。