入门指南

Getting Started

开始使用 Leptos 有两条基本路径：

There are two basic paths to getting started with Leptos:

1. 使用 Trunk 进行客户端渲染（CSR） —— 如果你只想用 Leptos 制作一个响应迅速的网站，或者与现有的服务器或 API 配合使用，这是一个很好的选择。

   Client-side rendering (CSR) with Trunk - a great option if you just want to make a snappy website with Leptos, or work with a pre-existing server or API.

   在 CSR 模式下，Trunk 会将你的 Leptos 应用编译为 WebAssembly（WASM），并像典型的 Javascript 单页应用（SPA）一样在浏览器中运行。Leptos CSR 的优势包括更快的构建时间、更短的迭代开发周期、更简单的思维模型，以及更多的应用部署选项。然而，CSR 应用确实也有一些缺点：与服务器端渲染方法相比，终端用户的初始加载时间较慢，并且使用 JS 单页应用模型常见的 SEO 挑战同样适用于 Leptos CSR 应用。另请注意，在底层，会使用一段自动生成的 JS 代码片段来加载 Leptos WASM 包，因此客户端设备必须启用 JS 才能让你的 CSR 应用正常显示。正如所有软件工程一样，你需要在这里权衡利弊。

   In CSR mode, Trunk compiles your Leptos app to WebAssembly (WASM) and runs it in the browser like a typical Javascript single-page app (SPA). The advantages of Leptos CSR include faster build times and a quicker iterative development cycle, as well as a simpler mental model and more options for deploying your app. CSR apps do come with some disadvantages: initial load times for your end users are slower compared to a server-side rendering approach, and the usual SEO challenges that come along with using a JS single-page app model apply to Leptos CSR apps as well. Also note that, under the hood, an auto-generated snippet of JS is used to load the Leptos WASM bundle, so JS must be enabled on the client device for your CSR app to display properly. As with all software engineering, there are trade-offs here you'll need to consider.

2. 全栈，使用 cargo-leptos 进行服务器端渲染（SSR） —— 如果你想使用 Rust 来驱动前端和后端，那么 SSR 是构建 CRUD 风格网站和自定义 Web 应用的绝佳选择。

   Full-stack, server-side rendering (SSR) with cargo-leptos - SSR is a great option for building CRUD-style websites and custom web apps if you want Rust powering both your frontend and backend.

   使用 Leptos SSR 选项，你的应用会在服务器上被渲染为 HTML 并发送至浏览器；接着，WebAssembly 被用于对该 HTML 进行插桩（instrument），使你的应用具备交互能力 —— 这个过程被称为“水合”（hydration）。在服务器端，Leptos SSR 应用能够与你选择的Actix-web 或 Axum 服务器库紧密集成，因此你可以利用这些社区的 crates 来帮助构建你的 Leptos 服务器。 采用 Leptos 走 SSR 路线的优势包括能够帮助你的 Web 应用获得最佳的初始加载时间和最优的 SEO 评分。SSR 应用还能通过一项名为“服务器函数”（server functions）的 Leptos 特性，极大地简化跨越服务器/客户端边界的工作，它允许你在客户端代码中透明地调用服务器上的函数（稍后将详细介绍此特性）。然而，全栈 SSR 并非尽善尽美 —— 其缺点包括开发者迭代周期较慢（因为在更改 Rust 代码时你需要重新编译服务器和客户端），以及随水合过程而来的一些额外复杂性。

   With the Leptos SSR option, your app is rendered to HTML on the server and sent down to the browser; then, WebAssembly is used to instrument the HTML so your app becomes interactive - this process is called 'hydration'. On the server side, Leptos SSR apps integrate closely with your choice of eitherActix-web orAxum server libraries, so you can leverage those communities' crates to help build out your Leptos server. The advantages of taking the SSR route with Leptos include helping you get the best initial load times and optimal SEO scores for your web app. SSR apps can also dramatically simplify working across the server/client boundary via a Leptos feature called "server functions", which lets you transparently call functions on the server from your client code (more on this feature later). Full-stack SSR isn't all rainbows and butterflies, though - disadvantages include a slower developer iteration loop (because you need to recompile both the server and client when making Rust code changes), as well as some added complexity that comes along with hydration.

到本书结束时，你应该能清楚地了解根据项目的需求应进行何种权衡，以及选择哪条路线 —— CSR 还是 SSR。

By the end of the book, you should have a good idea of which trade-offs to make and which route to take - CSR or SSR - depending on your project's requirements.

在本书的第一部分中，我们将从进行 Leptos 网站的客户端渲染以及构建响应式 UI 开始，使用 Trunk 为浏览器提供 JS 和 WASM 打包文件。

In Part 1 of this book, we'll start with client-side rendering Leptos sites and building reactive UIs using Trunk to serve our JS and WASM bundle to the browser.

我们将在本书的第二部分介绍 cargo-leptos，该部分完全是关于如何在全栈 SSR 模式下发挥 Leptos 的全部威力。

We’ll introduce cargo-leptos in Part 2 of this book, which is all about working with the full power of Leptos in its full-stack, SSR mode.

Hello World！搭建 Leptos CSR 开发环境

Hello World! Getting Set up for Leptos CSR Development

首先，确保 Rust 已安装并且是最新的（如果需要说明请查看此处）。

First up, make sure Rust is installed and up-to-date (see here if you need instructions).

如果你尚未安装它，可以在命令行中运行以下命令来安装用于运行 Leptos CSR 站点的 “Trunk” 工具：

If you don’t have it installed already, you can install the "Trunk" tool for running Leptos CSR sites by running the following on the command-line:

cargo install trunk

然后创建一个基础的 Rust 项目

And then create a basic Rust project

cargo init leptos-tutorial

使用 cd 进入你新建的 leptos-tutorial 项目，并将 leptos 添加为依赖项

cd into your new leptos-tutorial project and add leptos as a dependency

cargo add leptos --features=csr

确保你已经添加了 wasm32-unknown-unknown 目标（target），以便 Rust 能够将你的代码编译为 WebAssembly 从而在浏览器中运行。

Make sure you've added the wasm32-unknown-unknown target so that Rust can compile your code to WebAssembly to run in the browser.

rustup target add wasm32-unknown-unknown

在 leptos-tutorial 目录的根目录下创建一个简单的 index.html 文件

Create a simple index.html in the root of the leptos-tutorial directory

<!DOCTYPE html>
<html>
  <head></head>
  <body></body>
</html>

并在你的 main.rs 文件中添加一个简单的 “Hello, world!”

And add a simple “Hello, world!” to your main.rs

use leptos::prelude::*;

fn main() {
    leptos::mount::mount_to_body(|| view! { <p>"Hello, world!"</p> })
}

你的目录结构现在应该大致如下所示

Your directory structure should now look something like this

leptos_tutorial
├── src
│   └── main.rs
├── Cargo.toml
├── index.html

现在在 leptos-tutorial 目录的根目录下运行 trunk serve --open。 Trunk 会自动编译你的应用，并在默认浏览器中将其打开。 如果你对 main.rs 进行了修改，Trunk 将会重新编译你的源代码， 并进行页面的实时重载（live-reload）。

Now run trunk serve --open from the root of the leptos-tutorial directory. Trunk should automatically compile your app and open it in your default browser. If you make edits to main.rs, Trunk will recompile your source code and live-reload the page.

欢迎来到由 Leptos 和 Trunk 驱动的，使用 Rust 和 WebAssembly（WASM）进行 UI 开发的世界！

Welcome to the world of UI development with Rust and WebAssembly (WASM), powered by Leptos and Trunk!

现在，在我们开始使用 Leptos 构建你的第一个真正的应用之前，你可能需要了解几件事，这有助于让你的 Leptos 体验稍微轻松一点。

Now before we get started building your first real applications with Leptos, there are a couple of things you might want to know to help make your experience with Leptos just a little bit easier.