Qwik

本指南将指导你使用 Qwik Web 框架创建你的第一个 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 箱管理窗口、Web 视图以及对操作系统的调用。此项目由 Cargo 管理，Cargo 是 Rust 的官方包管理器和通用构建工具。

我们的 Tauri CLI 在幕后使用 Cargo，因此您很少需要直接与之交互。Cargo 还有更多有用的功能，而我们的 CLI 并未公开这些功能，例如测试、linting 和格式化，因此请参阅他们的 官方文档 以了解更多信息。

安装 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. 您的 Web 资源（HTML/CSS/JS）相对于将创建的 <current dir>/src-tauri/tauri.conf.json 文件位于何处？
   这是 Tauri 在为 生产环境构建时将从中加载您的前端资源的路径。
   为此值使用 ../dist。


4. 您的开发服务器的 URL 是什么？
   这可以是 URL 或文件路径，Tauri 将在 开发期间加载该 URL 或文件路径。
   为此值使用 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 函数是入口点，也是程序运行时调用的第一个函数。

• icons
  您很有可能希望为您的应用程序添加一个漂亮的图标！为了让您快速上手，我们包含了一组默认图标。在发布应用程序之前，您应该将它们换掉。在 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 进程间通信指南。