Я PM, которые лезет в то, что его может сожрать. Так что, я перевела часть документации по Reagent, если будет полезно, выложу продолжение.
In the no-holds-barred world of coding, the end justifies the extreme.
Введение в Reagent
Reagent обеспечивает минималистичное взаимодействие между ClojureScript и React. Он позволяет вам создавать эффективные компоненты React, используя только простые функции ClojureScript и данные, которые описывают пользовательский интерфейс, используя Hiccup-подобный синтаксис.
Цель Reagent сделать возможным создание произвольно сложных пользовательских интерфейсов, используя пару основных понятий, и быть по-умолчанию достаточно быстрым, чтобы вам редко приходилось думать о производительности.
Простейший компонент Reagent
может выглядеть примерно так:
(defn simple-component [] [:div [:p "I am a component!"] [:p.someclass "I have " [:strong "bold"] [:span {:style {:color "red"}} " and red "] "text."]])
Вы можете создавать новые компоненты, вкладывая внутрь другие компоненты.
Как в этом примере:
(defn simple-parent [] [:div [:p "I include simple-component."] [simple-component]])
Данные передаются дочерним компонентам с помощью простых типов данных Clojure.
Как в этом примере:
(defn hello-component [name] [:p "Hello, " name "!"])(defn say-hello [] [hello-component "world"])
Примечание: В приведенном выше примере hello-component можно было бы точно так же вызвать как нормальную функцию Clojure, а не как компонент Reagent, т.е. с круглыми скобками вместо квадратных скобок. Единственным отличием была бы производительность, так как реальные компоненты Reagent перерисовываются только тогда, когда их данные изменились. Однако более продвинутые компоненты (см. ниже) должны вызываться в квадратных скобках.
Вот еще один пример, который рендерит список
элементов:
(defn lister [items] [:ul (for [item items] ^{:key item} [:li "Item " item])])(defn lister-user [] [:div "Here is a list:" [lister (range 3)]])
Примечание: приведенная выше часть ^{: key item} на самом деле не является необходимой в этом простом примере, но добавление уникального ключа к каждому элементу в динамически генерируемом списке компонентов является хорошей практикой и и увеличивает производительность рендеринга больших списков. Ключ может быть задан либо (как в этом примере) как метаданные, либо как элемент :key в первом аргументе компонента (если это map). Дополнительную информацию смотрите в документации React.
Управление состоянием в React
Самый простой способ управлять состоянием использовать собственную версию atom из Reagent. Он работает точно так же, как и в clojure.core, за исключением того, что при каждом использовании дерефается/разыменовывается (deref). Любой компонент, использующий atom, автоматически ререндерится при изменении его значения.
Продемонстрируем это на простом примере:
(ns example (:require [reagent.core :as r]))(def click-count (r/atom 0))(defn counting-component [] [:div "The atom " [:code "click-count"] " has value: " @click-count ". " [:input {:type "button" :value "Click me!" :on-click #(swap! click-count inc)}]])
Иногда вы можете захотеть использовать локальный стейт в компоненте. Это легко сделать и с атомом.
Мы вызываем setTimeout, и каждый раз компонент перерендеривается с обновленным счетчиком:
Вот пример
(ns example (:require [reagent.core :as r]))(def click-count (r/atom 0))(defn counting-component [] [:div "The atom " [:code "click-count"] " has value: " @click-count ". " [:input {:type "button" :value "Click me!" :on-click #(swap! click-count inc)}]])
В предыдущем примере также используется другая особенность Reagent: компонентная функция может возвращать другую функцию, которая используется для фактического рендеринга. Эта функция вызывается с теми же аргументами, что и первая.
Это позволяет выполнить некоторую настройку вновь создаваемых компонентов, не прибегая к событиям жизненного цикла Reagent.
Просто передавая атом, вы можете разделить управление состоянием между компонентами.
Как это делается:
(ns example (:require [reagent.core :as r]))(defn atom-input [value] [:input {:type "text" :value @value :on-change #(reset! value (-> % .-target .-value))}])(defn shared-state [] (let [val (r/atom "foo")] (fn [] [:div [:p "The value is now: " @val] [:p "Change it here: " [atom-input val]]])))
Замечание: Функции компонентов могут вызываться с любыми аргументами до тех пор, пока они неизменны. Вы могли бы использовать и мутабельные структуры, но тогда было бы необходимо убедиться, что компонент ререндерится при изменении данных. Reagent предполагает по-умолчанию, что два объекта равны, если они являются одним и тем же объектом.
Основное API
Reagent поддерживает большинство API React, но на самом деле существует только одна точка входа, необходимая для большинства приложений: reagent.dom/render.
Требуется два аргумента: компонент и DOM-узел.
Например, код самого первого примера по странице
будет выглядеть так:
(ns example (:require [reagent.core :as r]))(defn simple-component [] [:div [:p "I am a component!"] [:p.someclass "I have " [:strong "bold"] [:span {:style {:color "red"}} " and red "] "text."]])(defn render-simple [] (rdom/render [simple-component] (.-body js/document)))
Складывая все вместе
Вот более жизненный пример: простой калькулятор BMI.
Данные хранятся в одном reagent.core/atom: map со
следующими ключами: высота, вес и BMI.
(ns example (:require [reagent.core :as r]))(defn calc-bmi [{:keys [height weight bmi] :as data}] (let [h (/ height 100)] (if (nil? bmi) (assoc data :bmi (/ weight (* h h))) (assoc data :weight (* bmi h h)))))(def bmi-data (r/atom (calc-bmi {:height 180 :weight 80})))(defn slider [param value min max invalidates] [:input {:type "range" :value value :min min :max max :style {:width "100%"} :on-change (fn [e] (let [new-value (js/parseInt (.. e -target -value))] (swap! bmi-data (fn [data] (-> data (assoc param new-value) (dissoc invalidates) calc-bmi)))))}])(defn bmi-component [] (let [{:keys [weight height bmi]} @bmi-data [color diagnose] (cond (< bmi 18.5) ["orange" "underweight"] (< bmi 25) ["inherit" "normal"] (< bmi 30) ["orange" "overweight"] :else ["red" "obese"])] [:div [:h3 "BMI calculator"] [:div "Height: " (int height) "cm" [slider :height height 100 220 :bmi]] [:div "Weight: " (int weight) "kg" [slider :weight weight 30 150 :bmi]] [:div "BMI: " (int bmi) " " [:span {:style {:color color}} diagnose] [slider :bmi bmi 10 50 :weight]]]))
Производительность
React очень быстрый, как и Reagent. На самом деле, Reagent будет даже быстрее, чем обычный React практически всегда, благодаря оптимизациям, сделанным ClojureScript.
Смонтированные компоненты ререндерятся только тогда, когда их параметры изменились. Ререндеринг может вызываться сменой значения атома, аргументы передаются компоненту или состоянию компонента.
Все параметры сравниваются через функцию identical?, которая сравнивает указатели, поэтому не влияет на производительность. Mapы, передаваемые в качестве аргументов компонентам, сравниваются так же: они считаются идентичными, если все их элементы идентичны. Это относится и к встроенным компонентам React, таким как :div, :p и т. д.
Все это означает, что большую часть времени вам просто не придется заботиться о производительности. Просто определите свой пользовательский интерфейс как угодно он будет достаточно быстрым.
Есть пара ситуаций, о которых вам, возможно, придется позаботиться. Если вы дадите Reagent большой список компонентов для рендеринга, вам, возможно, придется снабдить их все уникальным атрибутом :key для ускорения рендеринга (см. выше). Также обратите внимание, что анонимные функции в целом не равны друг другу, даже если они представляют один и тот же код и замыкание.
Но опять же, в целом, стоит просто поверить, что React и Reagent будут достаточно быстрыми. Именно эта страница состоит из одного компонента Reagent с тысячами дочерних компонентов (каждая скобка и т.д. в примерах кода это отдельный компонент), и все же страница может обновляться многократно каждую секунду, не нагружая браузер.
Кстати, та страница также использует другой трюк React: вся страница пререндериватся с помощью Nodejs и reagent.dom.server/render-to-string. Когда она загружается в браузер, React автоматически добавляет обработчики событий к уже существующему DOM-дереву.
Полная демонстрация
Reagent поставляется с парой полных примеров, с проектными файлами Leiningen и всем остальным.
Вот один из них в действии:
(ns simpleexample.core (:require [reagent.core :as r] [reagent.dom :as rdom] [clojure.string :as str]))(defonce timer (r/atom (js/Date.)))(defonce time-color (r/atom "#f34"))(defonce time-updater (js/setInterval #(reset! timer (js/Date.)) 1000))(defn greeting [message] [:h1 message])(defn clock [] (let [time-str (-> @timer .toTimeString (str/split " ") first)] [:div.example-clock {:style {:color @time-color}} time-str]))(defn color-input [] [:div.color-input "Time color: " [:input {:type "text" :value @time-color :on-change #(reset! time-color (-> % .-target .-value))}]])(defn simple-example [] [:div [greeting "Hello world, it is now"] [clock] [color-input]])(defn ^:export run [] (rdom/render [simple-example] (js/document.getElementById "app")))
Todomvc
Список дел (ToDo List) в Reagent (за исключением роутинга и сохранения данных)
выглядит примерно так:
(ns todomvc.core (:require [reagent.core :as r] [reagent.dom :as rdom] [clojure.string :as str]))(defonce todos (r/atom (sorted-map)))(defonce counter (r/atom 0))(defn add-todo [text] (let [id (swap! counter inc)] (swap! todos assoc id {:id id :title text :done false})))(defn toggle [id] (swap! todos update-in [id :done] not))(defn save [id title] (swap! todos assoc-in [id :title] title))(defn delete [id] (swap! todos dissoc id))(defn mmap [m f a] (->> m (f a) (into (empty m))))(defn complete-all [v] (swap! todos mmap map #(assoc-in % [1 :done] v)))(defn clear-done [] (swap! todos mmap remove #(get-in % [1 :done])))(defonce init (do (add-todo "Rename Cloact to Reagent") (add-todo "Add undo demo") (add-todo "Make all rendering async") (add-todo "Allow any arguments to component functions") (complete-all true)))(defn todo-input [{:keys [title on-save on-stop]}] (let [val (r/atom title) stop #(do (reset! val "") (if on-stop (on-stop))) save #(let [v (-> @val str str/trim)] (if-not (empty? v) (on-save v)) (stop))] (fn [{:keys [id class placeholder]}] [:input {:type "text" :value @val :id id :class class :placeholder placeholder :on-blur save :on-change #(reset! val (-> % .-target .-value)) :on-key-down #(case (.-which %) 13 (save) 27 (stop) nil)}])))(def todo-edit (with-meta todo-input {:component-did-mount #(.focus (rdom/dom-node %))}))(defn todo-stats [{:keys [filt active done]}] (let [props-for (fn [name] {:class (if (= name @filt) "selected") :on-click #(reset! filt name)})] [:div [:span#todo-count [:strong active] " " (case active 1 "item" "items") " left"] [:ul#filters [:li [:a (props-for :all) "All"]] [:li [:a (props-for :active) "Active"]] [:li [:a (props-for :done) "Completed"]]] (when (pos? done) [:button#clear-completed {:on-click clear-done} "Clear completed " done])]))(defn todo-item [] (let [editing (r/atom false)] (fn [{:keys [id done title]}] [:li {:class (str (if done "completed ") (if @editing "editing"))} [:div.view [:input.toggle {:type "checkbox" :checked done :on-change #(toggle id)}] [:label {:on-double-click #(reset! editing true)} title] [:button.destroy {:on-click #(delete id)}]] (when @editing [todo-edit {:class "edit" :title title :on-save #(save id %) :on-stop #(reset! editing false)}])])))(defn todo-app [props] (let [filt (r/atom :all)] (fn [] (let [items (vals @todos) done (->> items (filter :done) count) active (- (count items) done)] [:div [:section#todoapp [:header#header [:h1 "todos"] [todo-input {:id "new-todo" :placeholder "What needs to be done?" :on-save add-todo}]] (when (-> items count pos?) [:div [:section#main [:input#toggle-all {:type "checkbox" :checked (zero? active) :on-change #(complete-all (pos? active))}] [:label {:for "toggle-all"} "Mark all as complete"] [:ul#todo-list (for [todo (filter (case @filt :active (complement :done) :done :done :all identity) items)] ^{:key (:id todo)} [todo-item todo])]] [:footer#footer [todo-stats {:active active :done done :filt filt}]]])] [:footer#info [:p "Double-click to edit a todo"]]]))))(defn ^:export run [] (rdom/render [todo-app] (js/document.getElementById "app")))
Благодарность
Благодарю за помощь в переводе zombiQWERTY.
