跳到主要內容

SvelteKit

本指南將逐步引導您使用 SvelteKit 前端框架建立您的第一個 Tauri 應用程式。

資訊

在我們繼續之前，請確認您已完成先決條件，以建立一個可用的開發環境。

Tauri 是使用任何前端框架和 Rust 核心來建置桌面應用程式的框架。每個應用程式包含兩個部分

  1. 建立視窗並對這些視窗公開原生功能的 Rust 二進位檔
  2. 您選擇用於在視窗內產生使用者介面的前端

在以下部分中，我們將首先建立前端架構、設定 Rust 專案，最後向您展示如何在兩者之間進行通訊。

以下是我們將要建置的預覽

Application Preview

建立前端​

SvelteKit 是一個 Svelte 前端，主要設計用於伺服器端渲染 (SSR)。為了讓 SvelteKit 與 Tauri 搭配使用，我們將停用 SSR 並使用 @sveltejs/adapter-static 來建立基於靜態網站產生 (SSG) 的前端。

SvelteKit 附帶一個類似於 create-tauri-app 的架構公用程式，它可以快速設定一個新的專案，並提供許多自訂選項。對於本指南，我們將選擇已啟用 ESLint 和 Prettier 的 TypeScript 範本。

npm create svelte@latest

  1. 專案名稱
    這將會是你的 JavaScript 專案名稱。對應到此公用程式將建立的資料夾名稱，但對你的應用程式沒有其他影響。你可以使用任何你想要的這裡的名稱。

  2. 應用程式範本
    我們將選擇Skeleton project作為一個 barebones 範本。如果你想使用一個更完整的 SvelteKit 範例，你可以選擇SvelteKit demo app。

  3. 類型檢查
    是否要在你的專案中透過 JSDoc 或 TypeScript 進行類型檢查。對於本指南，我們假設你選擇 TypeScript。

  4. 程式碼 linting 和格式化
    是否要使用 ESLint 進行程式碼 linting 和 Prettier 進行程式碼格式化來啟動你的專案。本指南中不會再提到這一點，但我們建議啟用這兩個選項。

  5. 瀏覽器測試
    SvelteKit 提供內建的 Playwright 支援，用於瀏覽器測試。由於 Tauri API 在 Playwright 中無法使用，我們建議不要新增它。請查看我們的WebDriver 文件，了解使用 Selenium 或 WebdriverIO 而非 Playwright 的替代方案。

SSG 模式中的 SvelteKit​

首先，我們需要安裝@sveltejs/adapter-static

npm install --save-dev @sveltejs/adapter-static

然後在 svelte.config.js 檔案中更新 adapter 匯入

svelte.config.js
import adapter from '@sveltejs/adapter-static' // This was changed from adapter-auto
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'

/** @type {import('@sveltejs/kit').Config} */
const config = {
  // Consult https://sveltekit.dev.org.tw/docs/integrations#preprocessors
  // for more information about preprocessors
  preprocess: vitePreprocess(),

  kit: {
    adapter: adapter(),
  },
}

export default config

最後，我們需要透過新增一個根目錄 +layout.ts 檔案（如果你沒有使用 TypeScript，則為 +layout.js）來停用 SSR 並啟用預先渲染，內容如下

src/routes/+layout.ts
export const prerender = true
export const ssr = false

請注意，static-adapter 不要求你為整個應用程式停用 SSR，但它讓你可以使用依賴於全域 window 物件（例如 Tauri 的 API）的 API，而不需要客戶端檢查。

此外，如果你偏好單頁應用程式 (SPA) 模式而非 SSG，你可以根據轉接器文件變更轉接器設定和 +layout.ts。

建立 Rust 專案​

每個 Tauri 應用程式的核心都是一個 Rust 二進位檔，它透過名為 tauri 的 Rust crate 管理視窗、網頁檢視和對作業系統的呼叫。此專案由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 作為此值。

  4. 您的開發伺服器的 URL 為何？
    這可以是 URL 或檔案路徑，Tauri 將在開發期間載入。
    請使用 http://localhost:5173 作為此值。

  5. 您的前端開發指令為何？
    這是用於啟動您的前端開發伺服器的指令。
    請使用 npm run dev（請務必調整為使用您選擇的套件管理員）。

  6. 您的前端建置指令為何？
    這是用於建置您的前端檔案的指令。
    請使用 npm run build（請務必調整為使用您選擇的套件管理員）。
資訊

如果您熟悉 Rust，您會注意到 tauri init 的外觀和運作方式很像 cargo init。如果您偏好完全手動設定，您可以只使用 cargo init 並新增必要的 Tauri 相依性。

tauri init 指令會產生一個名為 src-tauri 的資料夾。Tauri 應用程式的慣例是將所有與核心相關的檔案放置到這個資料夾中。讓我們快速瀏覽此資料夾的內容

  • Cargo.toml
    貨物的清單檔案。你可以宣告你的應用程式所依賴的 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 的 圖示功能指南 中，進一步了解各種圖示格式。

現在我們已經架構好前端並初始化 Rust 專案，建立的 tauri.conf.json 檔案應該看起來像這樣

src-tauri/tauri.conf.json
{
  "build": {
    // This command will execute when you run `tauri build`.
    "beforeBuildCommand": "npm run build",
    // This command will execute when you run `tauri dev`
    "beforeDevCommand": "npm run dev",
    "devPath": "http://localhost:5173",
    "distDir": "../build"
  },

這樣就完成了！現在你可以在終端機中執行以下指令，以開始開發應用程式的建置

npm run tauri dev

Application Window

呼叫指令​

Tauri 讓您使用原生功能增強您的前端。我們稱這些為 命令，基本上是 Rust 函式，您可以從前端 JavaScript 呼叫。這讓您能夠以效能更高的 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");
}

現在您已準備好從前端呼叫您的命令！

要呼叫我們新建立的命令，我們將使用 @tauri-apps/api JavaScript 函式庫。它透過方便的 JavaScript 抽象提供對核心功能的存取，例如視窗、檔案系統等。您可以使用您最愛的 JavaScript 套件管理員安裝它

npm install @tauri-apps/api

安裝函式庫後，我們現在可以建立新的 Svelte 元件。我們將在 src/lib/Greet.svelte 中建立它

src/lib/Greet.svelte
<script>
  import { invoke } from '@tauri-apps/api/tauri'

  let name = ''
  let greetMsg = ''

  async function greet() {
    greetMsg = await invoke('greet', { name })
  }
</script>

<div>
  <input id="greet-input" placeholder="Enter a name..." bind:value="{name}" />
  <button on:click="{greet}">Greet</button>
  <p>{greetMsg}</p>
</div>

您現在可以將這個元件新增到 src/routes/+page.svelte

src/routes/+page.svelte
<script>
  import Greet from '../lib/Greet.svelte'
</script>

<h1>Welcome to SvelteKit</h1>
<Greet />

您現在可以使用 npm run tauri dev 執行這個程式，並查看結果

Application Preview

提示

如果您想進一步了解 Rust 和 JavaScript 之間的通訊，請閱讀 Tauri 程序間通訊指南。