Qwik

本指南將引導您使用 Qwik 網路架構建立您的第一個 Tauri 應用程式。

資訊

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

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

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

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

以下是我們將建置的內容預覽

建立前端

Qwik 主要設計用於伺服器端渲染 (SSR)。為了讓 Qwik 與 Tauri 搭配使用，我們將使用「靜態網站」轉接器來建立一個基於靜態網站產生 (SSG) 的前端。

Qwik 附帶了一個類似於 create-tauri-app 的建構工具，可以快速設定一個新專案，並提供許多自訂選項。在本指南中，我們將選擇 TypeScript 範本。

npm

npm create qwik@latest

Yarn

yarn create qwik@latest

pnpm

pnpm create qwik@latest

Bun

bunx create-qwik@latest

1. 專案名稱
   這將會是您的 JavaScript 專案名稱。對應於此工具將建立的資料夾名稱，但不會對您的應用程式產生其他影響。您可以在這裡使用任何您想要的。名稱。

2. 應用程式啟動器
   我們將選擇 基本應用程式 (QwikCity) 選項作為範本範例。

3. 安裝相依性
   是的，如果您希望它自動安裝相依性。

SSG 模式中的 Qwik

npm

npm run qwik add

Yarn

yarn create qwik add

pnpm

pnpm qwik add

Bun

bun run qwik add

選取 靜態網站（.html 檔案） 適配器。然後您可以透過以下方式建立靜態網頁

npm

npm run build

Yarn

yarn build

pnpm

pnpm build

Bun

bun run build

建立 Rust 專案

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

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

安裝 Tauri CLI

如果您尚未安裝 Tauri CLI，可以使用下列其中一個命令進行安裝。不確定要使用哪一個？查看 常見問題解答條目。

npm

npm install --save-dev @tauri-apps/cli

要讓 npm 正確偵測 Tauri，您需要將它新增到 package.json 檔案中的「scripts」區段

package.json

"scripts": {
  "tauri": "tauri"
}

Yarn

yarn add -D @tauri-apps/cli

pnpm

pnpm add -D @tauri-apps/cli

Bun

bun add -D @tauri-apps/cli

Cargo

cargo install tauri-cli

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

npm

npm run tauri init

Yarn

yarn tauri init

pnpm

pnpm tauri init

Bun

bunx tauri init

Cargo

cargo tauri init

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

1. 您的應用程式名稱為何？
   這將是您最終套件的名稱，也是作業系統會用來稱呼您的應用程式的名稱。您可以在這裡使用任何您想要的。


2. 視窗標題應為何？
   這將是預設主視窗的標題。您可以在這裡使用任何您想要的標題。


3. 你的網頁資源 (HTML/CSS/JS) 相對於即將建立的 <current dir>/src-tauri/tauri.conf.json 檔案位於何處？
   這是 Tauri 在為 正式環境 建置時會從中載入你的前端資源的路徑。
   請使用 ../dist 作為此值。


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
  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 的 圖示功能指南 中，深入了解各種圖示格式。

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

npm

npm run tauri dev

Yarn

yarn tauri dev

pnpm

pnpm tauri dev

bun

bunx tauri dev

Cargo

cargo tauri dev

呼叫指令

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

現在您可以從前端呼叫您的指令了！

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

安裝函式庫後，我們現在可以建立新的 Qwik 元件。我們將在 src/components/greet/greet.tsx 中建立它

src/components/greet/greet.tsx

import { $, component$, useSignal } from '@builder.io/qwik'
import { invoke } from '@tauri-apps/api/tauri'

export default component$(() => {
  const greetMsg = useSignal('')

  const greet = $(async (name: string) => {
    greetMsg.value = await invoke('greet', { name })
  })

  return (
    <div>
      <button onClick$={() => greet('Qwik')}>Greet</button>
      <p>{greetMsg.value}</p>
    </div>
  )
})

現在你可以將這個元件新增到 src/routes/index.tsx

src/routes/index.tsx

// ...
import Greet from '~/components/greet/greet'

export default component$(() => {
  return (
    <>
      <Greet />
      ...
    </>
  )
})

提示

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