diff --git a/src-russian/01_introduction.md b/src-russian/01_introduction.md new file mode 100644 index 0000000..e600fa6 --- /dev/null +++ b/src-russian/01_introduction.md @@ -0,0 +1,20 @@ +# Вступление + +Эта книга познакомит вас с Веб-фреймворком [Leptos](https://github.com/leptos-rs/leptos). +В ней мы пройдемся по фундаментальным концепциям необходимым для написания приложений, +начиная от простого приложения с рендерингом в браузере и постепенно перейдём к full-stack +приложению с рендерингом на стороне сервера и гидратацией. + +Данное руководство не ждёт, что вы знаете что-либо о мелкозернистой реактивности +или о особенностях современных Веб-фреймворков. Оно подразумевает, что вы знакомы +с Rust, HTML, CSS, а также DOM и простые Web API. + +Leptos больше всего похож на такие фреймворки как [Solid](https://www.solidjs.com) (JavaScript) +и [Sycamore](https://sycamore-rs.netlify.app/) (Rust). У него также есть схожие черты с другими фреймворками, +такими как React (JavaScript), Svelte (JavaScript), Yew (Rust), и +Dioxus (Rust). Так что знание одного из этих фреймворков может +помочь вам понять Leptos. + +Вы можете найти более детальную документацию каждой части API на [Docs.rs](https://docs.rs/leptos/latest/leptos/). + +> Исходный код этой книги доступен [здесь](https://github.com/leptos-rs/book-ru). Запросы Pull для исправление опечаток и уточнения всегда желанны. diff --git a/src-russian/SUMMARY.md b/src-russian/SUMMARY.md new file mode 100644 index 0000000..77d7d85 --- /dev/null +++ b/src-russian/SUMMARY.md @@ -0,0 +1,55 @@ +z# Оглавление + +- [Вступление](./01_introduction.md) +- [Начало работы](./getting_started/README.md) + - [Leptos DX](./getting_started/leptos_dx.md) + - [Сообщество Leptos и leptos-* Крейты](./getting_started/community_crates.md) +- [Часть 1: Построение UI](./view/README.md) + - [Простой компонент](./view/01_basic_component.md) + - [Динамические атрибуты](./view/02_dynamic_attributes.md) + - [Компоненты и свойства](./view/03_components.md) + - [Итерирование](./view/04_iteration.md) + - [Итерирование более сложных структур через ``](./view/04b_iteration.md) + - [Формы и поля ввода](./view/05_forms.md) + - [Порядок выполнения](./view/06_control_flow.md) + - [Обработка ошибок](./view/07_errors.md) + - [Общение Родитель-Ребёнок в дереве компонентов](./view/08_parent_child.md) + - [Передача Детей другим компонентам](./view/09_component_children.md) + - [Без макросов: синтаксис билдера View](./view/builder.md) +- [Реактивность](./reactivity/README.md) + - [Работа с сигналами](./reactivity/working_with_signals.md) + - [Реагирование на изменения с помощью `create_effect`](./reactivity/14_create_effect.md) + - [Примечание: Реактивность и функции](./reactivity/interlude_functions.md) +- [Тестирование](./testing.md) +- [Асинхронность](./async/README.md) + - [Подгрузка данных с помощью ресурсов (Resource)](./async/10_resources.md) + - [Ожидания (Suspense)](./async/11_suspense.md) + - [Переходы (Transition)](./async/12_transition.md) + - [Действия (Action)](./async/13_actions.md) +- [Примечание: Пробрасывание дочерних элементов](./interlude_projecting_children.md) +- [Управление глобальным состоянием](./15_global_state.md) +- [Маршрутизатор URL](./router/README.md) + - [Определение ``](./router/16_routes.md) + - [Вложенная маршрутизация](./router/17_nested_routing.md) + - [Параметры в пути и в строке запроса](./router/18_params_and_queries.md) + - [``](./router/19_a.md) + - [`
`](./router/20_form.md) +- [Примечание: Стили](./interlude_styling.md) +- [Метаданные](./metadata.md) +- [Рендеринг на стороне клиента (CSR): Заключение](./csr_wrapping_up.md) +- [Часть 2: Рендеринг на стороне сервера (SSR)](./ssr/README.md) + - [`cargo-leptos`](./ssr/21_cargo_leptos.md) + - [Жизненный цикл загрузки страницы](./ssr/22_life_cycle.md) + - [Асинхронный рендеринг и режимы SSR](./ssr/23_ssr_modes.md) + - [Баги возникающие при гидратации](./ssr/24_hydration_bugs.md) +- [Работа с сервером](./server/README.md) + - [Серверные функции](./server/25_server_functions.md) + - [Экстракторы](./server/26_extractors.md) + - [Ответы и перенаправления](./server/27_response.md) +- [Постепенное улучшение и Изящная деградация](./progressive_enhancement/README.md) + - [``](./progressive_enhancement/action_form.md) +- [Развёртывание](./deployment/README.md) + - [Оптимизация размера бинарника WASM](./deployment/binary_size.md) +- [Руководство: Острова](./islands.md) + +- [Приложение: Как работает реактивная система?](./appendix_reactive_graph.md) \ No newline at end of file diff --git a/src-russian/getting_started/README.md b/src-russian/getting_started/README.md new file mode 100644 index 0000000..74109b6 --- /dev/null +++ b/src-russian/getting_started/README.md @@ -0,0 +1,160 @@ +# Начало работы + +Есть два пути чтобы начать работу с Leptos: +1. **Рендеринг на клиенте (CSR) с [Trunk](https://trunkrs.dev/)** - отличный вариант если вы просто хотите сделать шустрый сайт на Leptos, +или работать с уже существующим сервером или API. +В режиме CSR, Trunk компилирует ваше Leptos приложение в WebAssembly (WASM) и запускает его в браузере как обычное +одностраничное Javascript приложение (SPA). Примущества Leptos CSR включают более быструю сборку и ускоренный +итеративный цикл разработки, а также более простую ментальную модель и больше вариантов развёртывания вашего приложения. +CSR приложения имеют и некоторые недоставки: время первоначальной загрузки для ваших пользователей будет дольше +в сравнении с подходом серверного рендеринга (SSR), а ещё пресловутые проблемы SEO, которыми сопровождаются +одностраничники на JS, применимы и к приложениям на Leptos CSR. Также стоит заметить, что "под капотом" используется + автоматически генерируемый скрипт на JS, подгружающий бинарник WASM с Leptos, так что JS *должен* быть включен +на устройстве пользователя, чтобы ваше CSR приложение отображалось нормально. Как и во всей программной инженерии, +здесь есть компромиссы, которые вам нужно учитывать. + +2. **Full-stack, серверный рендеринг (SSR) c [`cargo-leptos`](https://github.com/leptos-rs/cargo-leptos)** +— SSR это отличный вариант для построения веб-сайтов в стиле CRUD и кастомных веб-приложений если вы хотите, +чтобы Rust был и на клиенте и на сервере. При использовании варианта Leptos SSR, ваше приложение рендерится +в HTML на сервере и отправляется в браузер; затем в дело вступает WebAssembly, вооружая HTML, чтобы ваше приложение +стало интерактивным — этот процесс называется "гидратация". На стороне сервера, Leptos SSR приложения тесно интегрируются +либо с фреймворком по вашему выбору — [Actix-web](https://docs.rs/leptos_actix/latest/leptos_actix/index.html) или [Axum](https://docs.rs/leptos_axum/latest/leptos_axum/index.html), таким образом вы можете крейты этих сообществ, +чтобы они помогли вам в построении вашего сервера Leptos. +Преимущества выбора Leptos SSR включают в себя помощь в получении наилучшего времени первоначальной загрузки и оптимальные +очки SEO для вашего веб-приложения. SSR приложения могут также кардинально упростить клиент-серверное взаимодействие +с помощью Leptos-фичи под названием "серверные функции", которая позволяет вам прозрачно вызывать функции на сервере +из вашего клиентского кода (об этом позже). Full-stack SSR, впрочем, это не только пони, питающиеся радугой, +есть и недоставки, они включают в себя более медленный цикл разработки (потому что вам нужно перекомпилировать +и сервер и клиент, когда вы меняете Rust код), а также некоторую дополнительную сложность, которую вносит гидратация. + +К концу этой книги вы будете иметь ясное представление о том на какие компромиссы идти и какой путь избирать — CSR или SSR + — в зависимости от требований вашего проекта. + +В Части 1 этой книги мы начнём с клиентского рендеринга Leptos сайтов и построения реактивных UI используя `Trunk` +для отдачи нашего JS и WASM бандла в браузер. + +Мы познакомим вас с `cargo leptos` во Части 2 этой книги, которая посвящена работе со всей мощью +Leptos в его full-stack SSR режиме. + +```admonish note +Если вы пришли из мира Javascript и такие термины как клиентский рендеринг (CSR) и серверный рендеринг (SSR) вам незнакомы, +самый простой способ понять разницу между ними — это по аналогии: + +CSR режим в Leptos похож на работу с React (или с фреймворком основаным на сигналах, таким как SolidJS) и сфокусирован +на создании UI на клиентской стороне, который вы можете использовать с любым серверным стеком. + +Использование режима SSR в Leptos похоже на работу с full-stack фреймворком как Next.js в мире React +(или "SolidStart" фреймворком в SolidJS) — SSR помогает строить сайты и приложения, которые рендрятся на сервере и затем отправляются клиенту. +SSR может помочь улучшить производительность загрузки вашего сайта и доступность, +а также упростить работу одному человеку *сразу* и над клиентом и на сервером без необходимости переключать контекст + между разными языками для frontend и backend. + +Фреймворк Leptos может быть использовать либо в режиме CSR, чтобы просто сделать UI (как React), а может в + full-stack SSR режиме (как Next.js), так чтобы вы могли писать и UI и серверную часть на одном языке: на Rust. +``` + +## Привет, Мир! Подготовка к Leptos CSR разработке + +Первым делом убедитесь что Rust установлен и обновлен ([здесь инструкции, если нужны](https://www.rust-lang.org/tools/install)) + +Если инструмент `Trunk` ещё не установлен, вы можете установить его для запуска сайтов на Leptos CSR, путем выполнения следующей команды: + +```bash +cargo install trunk +``` + +А затем создайте простой Rust проект + +```bash +cargo init leptos-tutorial +``` + +`cd` в директорию вашего нового проекта `leptos-tutorial` и добавьте `leptos` в качестве зависимости + +```bash +cargo add leptos --features=csr,nightly +``` + +Или вы можете убрать `nightly` если вы используете стабильную версию Rust + +```bash +cargo add leptos --features=csr +``` + +> Использование `nightly` Rust, и `nightly` feature в Leptos включает синтаксис вызова функции для геттеров и сеттеров сигналов, который использован в большей части этой книги. +> +> Чтобы использовать nightly Rust, вы можете либо выбрать nightly для всех ваших Rust проектов, выполнив команды +> +> ```bash +> rustup toolchain install nightly +> rustup default nightly +> ``` +> +> либо только для этого проекта +> +> ```bash +> rustup toolchain install nightly +> cd +> rustup override set nightly +> ``` +> +> [Здесь больше подробностей](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +> +> Если вы бы предпочли использовать стабильную версию Rust с Leptos, то так тоже можно. В этом руководстве и примерах +> просто используйте методы +> [`ReadSignal::get()`](https://docs.rs/leptos/latest/leptos/struct.ReadSignal.html#impl-SignalGet%3CT%3E-for-ReadSignal%3CT%3E) +> и [`WriteSignal::set()`](https://docs.rs/leptos/latest/leptos/struct.WriteSignal.html#impl-SignalGet%3CT%3E-for-ReadSignal%3CT%3E) +> вместо вызова геттеров и сеттеров как будто они функции. + +Убедитесь, что вы добавили цель сборки `wasm32-unknown-unknown`, чтобы Rust мог компилировать ваш код в WebAssembly для запуска в браузере. + +```bash +rustup target add wasm32-unknown-unknown +``` + +Создайте простой файл `index.html` в корне вашей директории `leptos-tutorial` + +```html + + + + + +``` + +И добавьте простое “Привет, Мир!” в ваш `main.rs` + +```rust +use leptos::*; + +fn main() { + mount_to_body(|| view! {

"Привет, Мир!"

}) +} +``` + +Ваша структура директорий должна выглядеть как-то так + +``` +leptos_tutorial +├── src +│ └── main.rs +├── Cargo.toml +├── index.html +``` + +Теперь запустите `trunk serve --open` из корня вашей директории `leptos-tutorial`. +Trunk должен автоматически скомпилировать ваше приложение и открыть ваш браузер по-умолчанию. +Если вы вносите правки в `main.rs`, Trunk перекомпилирует ваш исходный код и перезагрузит страницу. + + +Добро пожаловать в мир разработки UI с помощью Rust и WebAssembly (WASM), приводимый в действие Leptos и Trunk! + +```admonish note +Если вы используете Windows, учтите что `trunk server --open` может не работать. Если у вас проблемы с `--open`, просто +используйте `trunk serve` и откройте вкладку браузера вручную. +``` + +--- + +Теперь прежде чем мы начнем строить ваше первый реальный UI c Leptos, есть пара вещей, о которых вам возможно стоит знать, +чтобы сделать ваш опыт с Leptos чуточку проще. diff --git a/src-russian/getting_started/community_crates.md b/src-russian/getting_started/community_crates.md new file mode 100644 index 0000000..a50460b --- /dev/null +++ b/src-russian/getting_started/community_crates.md @@ -0,0 +1,31 @@ +# Сообщество Leptos и `leptos-*` крейты + +## Сообщество + +Одно финальное замечание прежде чем мы начнём разработку на Leptos: не постесняйтесь присоединиться к нашему растущему сообществу Leptos в [Discord](https://discord.gg/YdRAhS7eQB) и на [Github](https://github.com/leptos-rs/leptos). +В особенности, наш Discord канал очень активен и дружелюбен — мы бы очень хотели вас там видеть! + +```admonish note +Если вы найдёте какую-либо главу или объяснение непонятным во время чтения книги, просто упомяните об этом в канале "docs-and-education" или задайте вопрос в "help" чтобы могли всё прояснить и обновить книгу для других. +``` + +Если по мере того как вы продвигаетесь в вашем Leptos путешествии у вас будут возникать вопросы вида "как сделать 'x' с помощью Leptos", +воспользуйтесь поиском по Discord каналу "help" чтобы посмотреть не был ли поднят этот вопрос ранее, или же без стеснения опубликуйте ваш вопрос — +сообщество помогает новичкам и очень отзывчиво. + +"[Обсуждения](https://github.com/leptos-rs/leptos/discussions)" на Github также отличное место чтобы задавать вопросы и оставаться в курсе анонсов Leptos. + +И конечно, если вы сталкиваетесь с какими-либо багами во время разработки с Leptos или хотите создать запрос +нового функционала (или отправить багфикс / новую фичу), откройте issue в [Github issue tracker](https://github.com/leptos-rs/leptos/issues). + +## Leptos-* крейты + +Сообщество создало растущее число крейтов связанных с Leptos, которые помогут вам быстрее стать продуктивными с вашими Leptos проектами — +ознакомьтесь со списком крейтов построенных на базе Leptos и выложенных сообществом вы можете в [Awesome Leptos](https://github.com/leptos-rs/awesome-leptos) репозитории на Github. + +Еслм вы хотите найти последние, новейшие крейты для Leptos, ознакомьтесь с секцией "Tools and Libraries" в Leptos Discord. +В этой секции есть канал для форматера Leptos-макроса `view!` (#leptosfmt); есть канал для библиотеки утилит "leptos-use"; +канал для библиотеки UI-компонентов "leptonic"; и канал "libraries" где обсуждаются новые `leptos-*` крейты прежде чем они +проложат себе путь в растущий список крейтов и ресурсов доступных в [Awesome Leptos](https://github.com/leptos-rs/awesome-leptos). + + diff --git a/src-russian/getting_started/leptos_dx.md b/src-russian/getting_started/leptos_dx.md new file mode 100644 index 0000000..48bec57 --- /dev/null +++ b/src-russian/getting_started/leptos_dx.md @@ -0,0 +1,148 @@ +# Улучшения опыта разработчика на Leptos + +Есть пара вещей, которые вы можете сделать, чтобы улучшить ваш опыт разработки веб-сайтов и приложения на Leptos. +Возможно вы захотите потратить несколько минут и настроить ваше окружение, чтобы оптимизировать ваш опыт как разработчика, +особенно если вы хотите программировать попутно с примерами из этой книги. + +## 1) Настройте `console_error_panic_hook` + +По-умолчанию паники, которые происходят во время выполнения вашего WASM кода в браузере просто выбросят ошибку в браузере +с неинформативным сообщением вроде `Unreachable executed` и трассировкой стека, указывающей на ваш WASM бинарник. + +Используя `console_error_panic_hook` вы можете получить настоящую трассировку стека Rust, включающую номер строки в вашем Rust коде. + +Настроить это очень просто: + +1. Выполните `cargo add console_error_panic_hook` в вашем проекте +2. В вашей функции main добавьте вызов `console_error_panic_hook::set_once();` + +> Если это непонятно, [вот пример](https://github.com/leptos-rs/leptos/blob/main/examples/counter/src/main.rs#L4-L15). + +Теперь сообщения о паниках в консоле браузере будут намного лучше! + +## 2) Автоподстановка в редакторе внутри `#[component]` и `#[server]` + +Из-за природы макросов (они могут разворачивать что угодно из чего угодно, но только если ввода вполне корректен в тот +момент) rust-analyzer'у может быть сложно делать должную автоподстановку и другую поддержку. + +Если вы столкнулись с проблемами при использовании этих макросов в вашем редакторе, вы можете явно сказать rust-analyzer +игнорировать определенные процедурные макросы. Особенно для макроса `#[server]`, который добавляет аннотации к телам функций, +но в действительно ничего не трансформирует внутри тела вашей функции, это может быть очень полезно. + +Начиная с версии Leptos 0.5.3, поддержка rust-analyzer была добавлена для `#[component]`, но если вы столкнулись с проблемами, +вы можете также добавить `#[component]` в игнор лист (см. ниже). +Учтите что это будет означать, что rust-analyzer ничего не будет знать о свойствах вашего компонента, что может породить +собственный набор ошибок или предупреждений в IDE> + +VSCode `settings.json`: + +```json +"rust-analyzer.procMacro.ignored": { + "leptos_macro": [ + // optional: + // "component", + "server" + ], +} +``` + +`VSCode` с `cargo-leptos` `settings.json`: +```json +"rust-analyzer.procMacro.ignored": { + "leptos_macro": [ + // optional: + // "component", + "server" + ], +}, +// if code that is cfg-gated for the `ssr` feature is shown as inactive, +// you may want to tell rust-analyzer to enable the `ssr` feature by default +// +// you can also use `rust-analyzer.cargo.allFeatures` to enable all features +"rust-analyzer.cargo.features": ["ssr"] +``` + +`neovim` с `lspconfig`: + +```lua +require('lspconfig').rust_analyzer.setup { + -- Other Configs ... + settings = { + ["rust-analyzer"] = { + -- Other Settings ... + procMacro = { + ignored = { + leptos_macro = { + -- optional: -- + -- "component", + "server", + }, + }, + }, + }, + } +} +``` + +Helix, в `.helix/languages.toml`: + +```toml +[[language]] +name = "rust" + +[language-server.rust-analyzer] +config = { procMacro = { ignored = { leptos_macro = [ + # Optional: + # "component", + "server" +] } } } +``` + +Zed, в `settings.json`: + +```json +{ + -- Other Settings ... + "lsp": { + "rust-analyzer": { + "procMacro": { + "ignored": [ + // optional: + // "component", + "server" + ] + } + } + } +} +``` + +SublimeText 3, `LSP-rust-analyzer.sublime-settings` в `Goto Anything...` меню: + +```json +// Settings in here override those in "LSP-rust-analyzer/LSP-rust-analyzer.sublime-settings" +{ + "rust-analyzer.procMacro.ignored": { + "leptos_macro": [ + // optional: + // "component", + "server" + ], + }, +} +``` + +## 3) Настройка `leptosfmt` с Rust Analyzer (опциально) + +`leptosfmt` это форматер для Leptos макроса `view!` (внутри которого вы обычно пишете ваш UI код). +Поскольку макрос `view!` включает 'RSX' (как JSX) стиль написания вашего UI, cargo-fmt сложнее авто-форматировать ваш код внутри макроса `view!`. `leptosfmt` это крейт, который решает ваши проблемы с форматированием и поддерживает ваш UI код стиля RSX чистым и красивым. + +`leptosfmt` может быть установлен и использовать через командную строку или из вашего редактора кода: + +Для начала установите его командой `cargo install leptosfmt`. + +Если вы хотите использовать настройки по-умолчанию из командной строки, просто запустите `leptosfmt ./**/*.rs` из корня вашего проекта, чтобы отформатировать все Rust файлы используя `leptosfmt`. + +Если вы хотите настроить ваш редактор для работы с `leptosfmt` или хотите кастомизировать настройки `leptosfmt`, пожалуйста обратитесь к инструкциям доступным в [`leptosfmt` github repo's README.md](https://github.com/bram209/leptosfmt). + +Только учтите, что рекомендуется настраиить ваш редактор c `leptosfmt` на per-workspace основе для наилучших результатов.