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 crate 来管理窗口、webview 和对操作系统的调用。此项目由 Cargo 管理，Cargo 是 Rust 的官方包管理器和通用构建工具。

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

安装 Tauri CLI

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

npm

npm install --save-dev @tauri-apps/cli@">1.0.0"

为了使 npm 正确检测 Tauri，您需要将其添加到 package.json 文件的“scripts”部分

package.json

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

Yarn

yarn add -D @tauri-apps/cli@^1.0.0

pnpm

pnpm add -D @tauri-apps/cli@1

Bun

bun add -D @tauri-apps/cli@1.0.0

Cargo

cargo install tauri-cli --version "^1.0.0"

要搭建一个预配置为使用 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 是什么？
   这可以是 Tauri 在 开发过程中将加载的 URL 或文件路径.
   为此值使用https://127.0.0.1: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 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函数是入口点，也是程序运行时调用的第一个函数。

• 图标
  您可能想要一个漂亮的应用程序图标！为了让您快速上手，我们包含了一组默认图标。在发布您的应用程序之前，您应该将这些图标替换掉。了解 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的进程间通信指南。