React18, Reagent(v1.3)与Ant Design(V5)联合使用指南

Reagent 使用 Hiccup, 一种将 HTML 结构表示为 ClojureScript 向量(vector)的 DSL.

• 基本结构: [:tag-keyword {:attributes "map"} child1 child2...].
• 示例: [:div {:class "container"} [:h1 "Hello"][:p "World"]].
• Reagent 对 Hiccup 进行了一些扩展, 例如 . 用于 class, # 用于 id 的简写(尽管更推荐在属性 map 中明确指定), 以及 > 用于快速嵌套.
• nil 子节点会被忽略, 便于条件渲染: [:div (when visible? [:p "Visible"])].

在 Reagent 中, 组件通常是返回 Hiccup 的普通 ClojureScript 函数.

• Form-1 (简单组件): (defn my-component [params][:div "Hello " params]).

• Form-2 (带局部状态或初始化逻辑的组件): 函数返回一个渲染函数, 外部函数用于一次性设置, 内部函数用于多次渲染.

  (defn timer-component [] ;; Original example was incomplete, this is a common Reagent pattern.
    (let [seconds-elapsed (r/atom 0)] ;; 局部状态
      (fn [] ;; 渲染函数
        (js/setTimeout #(swap! seconds-elapsed inc) 1000)
        ;; Original snippet was missing the Hiccup to render
        ;; For example: [:div "Seconds: " @seconds-elapsed]
        ;; Sticking to the original provided code structure:
        (js/setTimeout #(swap! seconds-elapsed inc) 1000))))
        ;; The number 1 seems to be a reference, not part of the code.
  

• Form-3 (需要生命周期方法的组件): 使用 reagent.core/create-class 定义, 或通过元数据附加到函数组件上.

  (def component-with-lifecycle
    (with-meta plain-component
      {:component-did-mount (fn [this] (js/console.log "Mounted!"))}))
      ;; The number 2 seems to be a reference.
  

Reagent 1.2.0 引入了对 React 18 的实验性支持. 新的 reagent.dom.client 命名空间提供了 React 18 createRoot API 及其相关辅助函数. 而传统的 reagent.dom/render 继续使用旧的 ReactDOM.render, 允许项目继续使用 React 17 的模式. 这意味着如果想利用 React 18 的并发特性, 需要主动使用 reagent.dom.client/create-root 和 reagent.dom.client/render.

;; 使用 React 18 createRoot API
(ns my.app
  (:require [reagent.dom.client :as rdomc]
            [reagent.core :as r]))

(defn app-root []
  ;; Example content
  [:div "App Root Content"])

(defn init! []
  (let [el (js/document.getElementById "app") ;; Example target element
        root (rdomc/create-root el)] ;; Create root
    (rdomc/render root [app-root]))) ;; Render the component

Reagent 的核心状态管理机制是 reagent.core/atom (通常称为 ratom).

• ratom 行为类似 Clojure 的 atom, 但 Reagent 会追踪对其的解引用 (deref 或 @).
• 任何解引用了 ratom 的组件在其值改变时会自动重新渲染.

• 示例:

  (def click-count (r/atom 0))
  
  (defn counting-component []
    [:div {:on-click #(swap! click-count inc)}
     "Clicked " @click-count " times."])
     ;; The number 2 seems to be a reference.
  

• cursor 允许创建指向 ratom 内部某个路径的 "视图", 当 cursor 指向的数据变化时, 仅依赖该 cursor 的组件会更新, 有助于性能优化.

Reagent 构建于 React 之上, 并提供与 React 的互操作机制.

• reagent.core/adapt-react-class 或其简写 :> 用于在 Hiccup 中使用 React 组件.
• reagent.core/reactify-component 用于将 Reagent 组件转换为 React 组件, 以便传递给需要 React 组件作为参数的库.
• reagent.core/as-element 用于将 Hiccup 形式转换为 React 元素, 常用于需要 React 元素作为 prop 的场景.

Reagent 1.0 之后, 通过 :f> 语法糖或配置编译器选项, 可以创建函数式 React 组件, 从而直接使用 React Hooks (如 useState, useEffect 等). 这是与现代 React 生态(包括 Antd 5.x 的许多内部实现)集成的关键.

(ns my.app
  (:require ["react" :as react] ;; 引入 react 库
            [reagent.core :as r]))

(defn hook-example []
  (let [[count setCount] (react/useState 0)]
    [:div
     [:p "Count: " count]
     [:button {:on-click #(setCount (inc count))} "Increment"]]))

(defn app []
  [:f> hook-example]) ;; :f> 表示这是一个函数式组件, 可以使用 hooks

• Breaking Change: :dangerouslySetInnerHTML 的使用方式改变. 现在必须使用 reagent.core/unsafe-html 来标记那些将直接插入 DOM 的 HTML 字符串, 否则 Reagent 会忽略该值. 这是出于安全考虑.

  ;; 旧方法 (Reagent < 1.3.0)
  ;; [:div {:dangerouslySetInnerHTML {:__html "<p>Raw HTML</p>"}}]
  ;; 或
  ;; [:div {:innerHTML "<p>Raw HTML</p>"}] ;; Depending on context
  
  ;; 新方法 (Reagent >= 1.3.0)
  (require '[reagent.core :as r])
  [:div {:dangerouslySetInnerHTML {:__html (r/unsafe-html "<p>Raw HTML</p>")}}]
  

  如果 Antd 组件的某些属性间接导致了此类 HTML 的渲染, 并且该 HTML 内容来源于 Reagent, 开发者需要注意此变化.

• 示例已更新为使用 shadow-cljs.
• 扩展了 reaction, make-reaction, run! 的文档字符串.
• 暴露了 clj-kondo 库配置, 使得 reagent.core/with-let 的行为与 clojure.core/let 一致. with-let 宏用于在组件挂载时仅评估一次绑定, 并提供一个 finally 块用于组件卸载时的清理, 是管理组件内部状态和生命周期的有效方式, 可替代部分 useEffect 的场景.

• 自然 (Natural): 追求自然的交互, 降低用户认知成本.
• 确定 (Certain): 提供高确定性, 低协作熵的界面, 无论是对设计者还是用户.
• 意义 (Meaningful): 以用户为中心, 创造有意义的人机交互, 助力用户达成目标.
• 生长 (Growing): 设计具有发展眼光的产品, 促进人机共同成长. 这些设计价值观指导着 Antd 组件库的开发和迭代, 确保了其在企业级应用中的适用性和一致性.

Antd 提供了丰富的组件集, 涵盖通用, 布局, 导航, 数据录入, 数据展示, 反馈等多个方面. 例如: Button, Icon, Grid, Layout, Space, Menu, Dropdown, Form, Input, Select, Table, Modal, Message, Notification 等.

Antd 5.x 的一个核心技术调整是全面采用 CSS-in-JS, 底层使用 @ant-design/cssinjs.

• 优势: 更好地支持动态主题, 按需加载, 避免全局样式污染, 提升性能(组件级别 CSS-in-JS).
• 变更: 移除了 Less 文件和 Less 变量的导出; 不再打包 CSS 文件(如 antd/dist/antd.css); babel-plugin-import 不再被支持, 因为 CSS-in-JS 天然支持按需引入.
• 如果需要重置基础样式, 可以引入 antd/dist/reset.css.
• 对于不想污染全局样式但又希望原生元素符合 Antd 规范的情况, 可以在最外层使用 App 组件.

出于性能和包大小的考虑, Antd 5.x 使用 Day.js 替换了内置的 Moment.js. 如果项目中依赖日期处理, 需要注意此变更并相应调整.

• 弹层类组件的 visible 属性统一为 open (例如 Modal, Drawer, Dropdown, Tooltip).
• 弹层类组件的类名 API 统一为 popupClassName.
• 移除了 LocaleProvider, 应使用 <ConfigProvider locale={...} /> .
• Comment 组件移至 @ant-design/compatible, PageHeader 组件移至 @ant-design/pro-components.
• BackTop 组件被废弃, 功能合并到 FloatButton.

这些核心概念的理解对于有效结合 Reagent 和 Ant Design 至关重要. 开发者需要意识到, 虽然 Reagent 提供了 ClojureScript 的便利性, 但在与 Antd 这样的 React 组件库交互时 , 本质上还是在与 React 组件打交道, 因此 React 的 props 传递, 事件处理, 生命周期(或 Hooks)等概念依然适用, 只是通过 Reagent 的语法和机制进行表达.

• 基础 Button: [:> antd/Button "Click Me"]

• 带 Icon 的 Button: 首先, 安装并引入 @ant-design/icons.

  (ns my.app
    (:require ["antd" :as antd]
              ["@ant-design/icons" :as icons] ; 引入图标库, 如 icons/SearchOutlined
              [reagent.core :as r]))
  
  (defn button-with-icon []
    [:> antd/Button {:icon [:> icons/SearchOutlined]} "Search"])
  
  (defn another-button-with-icon []
    [:> antd/Button {:icon [:> icons/PlusCircleOutlined] :type "primary"} " Create New Record"])
  

• 图标的 Tree Shaking: Ant Design 和 @ant-design/icons 本身支持 ES 模块的 tree shaking. shadow-cljs 在构建 release 版本时也会尝试进行 tree shaking.

  为了最大化 tree shaking 的效果, 从而减小最终包体积, 推荐从 @ant-design/icons 中具体导入所需的图标, 而不是导入整个库.

  例如, 在 JavaScript 中会写 import { SmileOutlined } from '@ant-design/icons';. 在 ClojureScript 中, 通过 (:require ["@ant-design/icons" :as icons]) 然后使用 [:> icons/SmileOutlined] 的方式, 依赖于 shadow-cljs 对 icons 这个 JavaScript 模块别名的 tree shaking 能力.

  这通常是有效的. 如果遇到包体积问题, 可以考虑更细粒度的引入, 例如 (:require ["@ant-design/icons/es/icons/SmileOutlined$default" :as SmileOutlined]) (具体路径需查证 antd 结构), 这样引入的是图标的默认导出.

使用 Reagent atom 控制 Modal 的可见性. Antd 5.x 中 Modal 的可见性属性是 open.

(ns my.app
  (:require [reagent.core :as r]
            ["antd" :as antd]))

(def modal-visible (r/atom false))

(defn handle-ok [e]
  (js/console.log "OK clicked")
  (reset! modal-visible false))

(defn handle-cancel [e]
  (js/console.log "Cancel clicked")
  (reset! modal-visible false))

(defn my-modal-component []
  [:div
   [:> antd/Button {:on-click #(reset! modal-visible true)} "Open Modal"]
   [:> antd/Modal {:title "My Modal Title"
                   :open @modal-visible
                   :onOk handle-ok
                   :onCancel handle-cancel}
    [:p "Modal Content Line 1"]
    [:p "Modal Content Line 2"]]])

此模式借鉴了 Reagent 中常见的状态管理方式 并适配了 Antd 5.x Modal 的 API.

• 受控 Antd Input 与 Reagent Atoms: 使用 r/atom 管理输入框的值, 通过 :value 和 :onChange props 实现双向绑定.

  (ns my.app
    (:require [reagent.core :as r]
              ["antd" :as antd]))
  (def name-val (r/atom ""))
  
  (defn my-input []
    [:> antd/Input
     {:placeholder "Enter name"
      :value @name-val
      :onChange #(reset! name-val (.. % -target -value))}])
  

这是 Reagent 中处理表单输入的基础模式, 也适用于 Antd 的 Input 组件.

• 使用 Form.useForm Hook 实现高级表单 (在 Reagent :f> 组件中): Antd 5.x 的 Form 组件推荐使用 Form.useForm() hook 来进行表单状态管理, 校验和提交. 要在 Reagent 中使用 React Hooks, 组件需要以 :f> 形式定义.

  (ns my.app
    (:require ["react" :as react] ; 必须引入 react 才能使用 hooks
              ["antd" :as antd]
              [reagent.core :as r] ; Ensure reagent.core is aliased
              [cljs.core :refer [clj->js js->clj]]))
  
  (defn login-form-comp []
    ;; 直接在函数式组件内部调用 useForm
    (let [[form-instance] (antd/Form.useForm) ; form-instance 在组件重渲染间保持稳定
          handle-finish (fn [values]
                          (js/console.log "Success:" (js->clj values :keywordize-keys true)))]
      [:> antd/Form {:form form-instance ; 将 form 实例传递给 Form 组件
                     :name "login"
                     :initialValues (clj->js {:remember true}) ; 初始值需 clj->js
                     :onFinish handle-finish} ; 提交回调
       [:> antd/Form.Item {:label "Username"
                           :name "username" ; 字段名
                           :rules (clj->js [{:required true ; 校验规则需 clj->js
                                            :message "Please input your username!"}])}
        [:> antd/Input]]
       [:> antd/Form.Item {:label "Password"
                           :name "password"
                           :rules (clj->js [{:required true
                                            :message "Please input your password!"}])}
        [:> antd/Input.Password]]
       [:> antd/Form.Item
        [:> antd/Button {:type "primary" :htmlType "submit"}
         "Log in"]]]))
  
  (defn app []
    [:f> login-form-comp]) ; 使用 :f> 使得 login-form-comp 可以使用 hooks
  

Form.useForm 返回一个包含 form 实例的数组, 因此使用 (let [[form-instance] (antd/Form.useForm)]...) 进行解构. 这个 form-instance 是稳定且可以在多次渲染中使用的.

此模式是 Reagent 应用现代 React 表单库(如 Antd Form)的关键, 它允许 ClojureScript 开发者利用 Antd 强大的表单功能, 同时保持 Reagent 的函数式风格.

• 校验规则 (rules): 在 Form.Item 的 :rules prop 中传递校验规则数组. 这些规则对象需要通过 clj->js 转换为 JavaScript 数组和对象. 例如: :rules (clj->js [{:required true :message "此字段为必填项"} {:min 5 :message "至少需要5个字符"}]).

• 数据绑定 (dataSource, columns 与 clj->js): Table 的 :dataSource prop 需要一个 JavaScript 对象数组, 每个对象代表一行数据且必须有唯一的 key 属性. :columns prop 也需要一个 JavaScript 对象数组, 定义列的结构和行为. 这两者都需从 ClojureScript 数据结构通过 (clj->js...) 转换.

• 使用 r/as-element 进行列的自定义渲染: 列定义中的 render 函数接收 (text, record, index) 三个参数, 其中 text 是当前单元格的值, record 是当前行的数据对象 (JS 对象), index 是行索引 64. 此函数应返回一个 React 节点. 如果想在单元格中渲染 Reagent 组件或 Hiccup, 必须使用 reagent.core/as-element 将其转换为 React 元素.

  (ns my.app
    (:require [reagent.core :as r]
              ["antd" :as antd]
              ["@ant-design/icons" :as icons]
              [cljs.core :refer [clj->js js->clj]]))
  
  ;; 一个简单的 Reagent 组件作为单元格渲染器
  (defn action-buttons [record-clj] ; record-clj 是转换后的 ClojureScript map
    [:<> ;; Use a fragment or a span
     [:> antd/Button {:type "link"
                      :on-click #(.log js/console "Edit" record-clj)}
      "Edit"]
     [:> antd/Button {:type "link" :danger true
                      :on-click #(.log js/console "Delete" record-clj)}
      "Delete"]]) ;; Original had "Delete"]]", assuming typo corrected
  
  (def table-columns
    (clj->js ; 整个列定义数组需要转换
     [{:title "Name" :dataIndex "name" :key "name"}
      {:title "Age" :dataIndex "age" :key "age"}
      {:title "Address" :dataIndex "address" :key "address"}
      {:title "Action"
       :key "action"
       :render (fn [text record index] ; record 是 JS 对象
                 (r/as-element [action-buttons (js->clj record :keywordize-keys true)]))}]))
                 ;; Original had "]))" which seems like an extra paren
  
  (def table-data
    (clj->js ; dataSource 需要是 JS 对象数组
     [{:key "1" :name "John Brown" :age 32 :address "New York No. 1 Lake Park"}
      {:key "2" :name "Jim Green" :age 42 :address "London No. 1 Lake Park"}
      {:key "3" :name "Joe Black" :age 32 :address "Sidney No. 1 Lake Park"}]))
  
  (defn my-table []
    [:> antd/Table {:dataSource table-data :columns table-columns}])
  

这个 (r/as-element...) 的使用是至关重要的. Antd 的 Table 组件(或其他任何接受渲染函数的 React 组件)期望 render 函数返回一个 React 可以直接处理的节点. Reagent 组件本身返回的是 Hiccup 数据结构, 或者它就是一个函数. r/as-element 充当了桥梁, 将 Reagent 的世界(Hiccup)转换到 React 的世界(React 元素). 不使用它, Antd Table 将无法正确渲染自定义的 Reagent 内容.

Antd 5.x 的 Menu 组件改用 items prop 来定义菜单项, 取代了之前直接嵌套 Menu.Item 和 Menu.SubMenu 的方式 items prop 需要一个特定结构的 JavaScript 对象数组.

(ns my.app
  (:require [reagent.core :as r]
            ["antd" :as antd]
            ["@ant-design/icons" :as icons]
            [cljs.core :refer [clj->js js->clj]]))

(def menu-items
  (clj->js
   [{:key "mail"
     :icon (r/as-element [:> icons/MailOutlined]) ; 图标也需要是 React 元素
     :label "Navigation One"}
    {:key "app"
     :icon (r/as-element [:> icons/AppstoreOutlined])
     :label "Navigation Two"}
    {:key "sub1"
     :label "Navigation Three - Submenu"
     :icon (r/as-element [:> icons/SettingOutlined]) ;; Original had empty (r/as-element)
     :children [{:type "group" ; 分组类型
                 :label "Item 1 Group"
                 :children [{:key "setting:1" :label "Option 1"}
                            {:key "setting:2" :label "Option 2"}]}
                {:type "group"
                 :label "Item 2 Group"
                 :children [{:key "setting:3" :label "Option 3"}
                            {:key "setting:4" :label "Option 4"}]}]}]))

(defn my-menu []
  [:> antd/Menu {:mode "inline"
                 :theme "dark"
                 :items menu-items ; 传递转换后的 items
                 :onClick (fn [info]
                            (let [key (.-key info)
                                  keyPath (js->clj (.-keyPath info))]
                              (js/console.log "Clicked menu item:" key keyPath)))}])

注意, 如果菜单项的 icon 或 label 是复杂的 Reagent 组件, 它们也需要通过 r/as-element 转换. Antizer 库的示例 60 可能展示的是旧版 Antd Menu API, 使用 Antd 5.x 时务必参考其最新文档关于 items prop 的用法.

为了保证跨浏览器的一致性和基础样式的重置, Antd 5.x 仍然提供了 reset.css 文件 8. 如第二部分所述, 应在项目的 index.html 中引入此文件 18.

<link rel="stylesheet" href="path/to/your/node_modules/antd/dist/reset.css" />

或者, 更常见的做法是将此文件复制到 shadow-cljs 开发服务器可访问的公共目录(例如项目的 public/css/ 目录), 然后在 index.html 中引用.

@ant-design/cssinjs 中的 StyleProvider 组件允许对 CSS-in-JS 的行为进行配置.

• hashPriority: 可以设置为 "high" 来增加 Antd 生成样式的特异性(默认是 "low", 使用 :where), 这在需要兼容不支持 :where 的旧浏览器或解决特异性冲突时有用.
• transformers: 可以用于在样式注入前对其进行转换, 例如 legacyLogicalPropertiesTransformer 用于兼容旧浏览器的逻辑属性, 或 px2remTransformer 用于将 px 单位转换为 rem 单位.
• container: 在 Shadow DOM 场景下, 可以指定样式注入的容器 73.
• layer: Antd 5.17.0+ 支持配置 @layer 来统一降低 CSS 优先级, 便于用户覆盖样式 73.

在 Reagent 中使用 StyleProvider:

(ns my.app
  (:require ["@ant-design/cssinjs" :as cssinjs] ; For StyleProvider
            ["antd" :as antd]
            [reagent.core :as r]))

(defn my-app-with-style-provider []
  [:> cssinjs/StyleProvider {:hashPriority "high"}
   ;; Your application components go here
   [:div "My App Content"]]
  )

ConfigProvider 的 :theme prop 接受一个主题对象, 用于定制应用的整体外观和感觉.

• 主题对象结构: 该主题对象主要包含两个顶级键:
  • token: 一个包含全局设计令牌 (design tokens) 的 map. 这些令牌控制着基础样式, 如主色调 (:colorPrimary), 圆角大小 (:borderRadiusLG), 字体 (:fontFamily) 等.
  • components: 一个 map, 允许对特定组件的样式进行覆盖. 键是组件名 (如 :Button, :Modal), 值是该组件的特定令牌配置.
• 在 Reagent 中使用并进行 clj->js 转换: 在 ClojureScript 中定义主题时, 通常会使用 ClojureScript 的 map 结构. 由于 Antd 的 ConfigProvider~期望一个 JavaScript 对象作为 ~theme prop 的值, 因此必须使用 clj->js 进行递归转换.

(ns my.app
  (:require [reagent.core :as r]
            ["antd" :as antd]
            [cljs.core :refer [clj->js]]))

(def my-custom-theme
  (clj->js ; 必须进行转换
   {:token {:colorPrimary "#52c41a" ; 修改主色调
            :borderRadiusLG 12     ; 修改大圆角
            :fontFamily "Georgia, serif"}
    :components {:Button {:colorPrimary "#1890ff" ; 单独覆盖 Button 的主色调
                          :fontWeight "bold"
                          :controlHeightLG 48} ; 大号按钮高度
                 :Modal {:titleFontSize 22
                         :headerBg "#f0f2f5"}}}))

(defn app-with-custom-theme []
  [:> antd/ConfigProvider {:theme my-custom-theme}
   [:div
    [:> antd/Button {:type "primary"} "Custom Themed Button"]
    ;;... 其他组件将继承或使用 ConfigProvider 定义的主题...
    ]])

这种通过 ConfigProvider 和 clj->js 进行主题定制的方式, 是 Reagent 应用充分利用 Antd 5.x 强大主题能力的标准途径. 忘记 clj->js 的转换会导致主题配置无效, 因为 Antd 无法理解 ClojureScript 的原生数据结构. 这突显了在进行 JavaScript 互操作时, 数据结构转换的重要性, 尤其是在处理如主题这样复杂的嵌套配置对象时.

• Reagent 本身因其基于 ClojureScript 不可变数据结构的高效比较, 默认情况下性能良好 2. 组件仅在其依赖的数据(ratom, props)发生变化时才重新渲染.
• 对于动态生成的组件列表, 务必为每个列表项提供唯一的 :key prop, 这有助于 React 进行高效的 DOM diff 和更新.
• 在 props 中传递匿名函数时需谨慎, 因为每次父组件渲染时都可能创建新的函数实例, 导致子组件不必要的重渲染. 在 :f> 组件中, 可以使用 react/useCallback 来记忆化回调函数, 确保其引用稳定性.

• Ant Design 5.x 及其图标库 @ant-design/icons 被设计为支持 tree shaking, 这意味着现代构建工具(如 Webpack, shadow-cljs 底层也可能利用类似机制处理 JS 模块)可以移除未使用的代码, 从而减小最终应用的包体积.
• shadow-cljs 对 npm 依赖也支持 tree shaking 19. 在构建生产版本时 (通常是 shadow-cljs release app), shadow-cljs 会尝试优化 JavaScript 依赖.
• 为了获得最佳的 tree shaking 效果, 推荐从 antd 或 @ant-design/icons 中按需导入具体组件或图标, 而不是导入整个库. 例如, 在 JavaScript 中 import { Button } from 'antd';. 在 ClojureScript 中, 当使用 ["antd" :refer [Avatar Button DatePicker Input Layout Menu Modal Pagination Space Table Tag Typography]] 时, shadow-cljs 通常能够有效地进行 tree shaking. 如果遇到问题, 可以考虑更细粒度的导入, 例如 (:require ["antd/es/button$default" :as AntButton]) (路径可能因 antd 内部结构而异, 需查证). syn-antd 项目的初衷之一就是为了解决早期 Antd 版本与 ClojureScript tree shaking 的问题, 但 Antd 5.x 本身在这方面已有很大改进.