Portfolio
Portfolio 是一個 ClojureScript「視覺化 REPL」— 它會在名為場景的隔離區域中渲染 UI 元件,讓您能一眼看到元件的所有狀態。它類似於 Storybook.js,但專為 REPL 驅動的 ClojureScript 開發而設計。
目前版本: no.cjohansen/portfolio {:mvn/version "2026.03.1"}
快速決策:您需要什麼?
| 任務 | 前往 |
|---|---|
| 安裝、啟動 UI、shadow-cljs 設定 | setup.md |
使用 defscene、參數、atom、生命週期定義場景 | defscene.md |
| 選擇框架適配器(Reagent、React、Replicant…) | defscene.md |
| 將場景組織成集合、資料夾、套件 | organization.md |
| 自訂背景、視口、網格、CSS、HTML | customize-ui.md |
在 REPL 中使用 tap> 而不定義場景 | setup.md |
| 在生產建置中停用 Portfolio | setup.md |
| 常見錯誤與應避免的事項 | anti-patterns.md |
核心心智模型
Portfolio 會渲染場景 — 元件在特定狀態下的具名快照。場景位於一般的 ClojureScript 命名空間(通常命名為 *-scenes),Portfolio 會依命名空間階層自動將它們組織成可導覽的側邊欄。
defscene → scene → namespace (package) → folder → sidebar
UI 會在開發伺服器位址的瀏覽器中執行。在 REPL 中重新求值 defscene 會立即重新渲染它 — 無需重新整理頁面。
最小工作範例
;; deps.edn
{:deps {no.cjohansen/portfolio {:mvn/version "2026.03.1"}}}
;; src/my/button_scenes.cljs
(ns my.button-scenes
(:require [portfolio.reagent :refer-macros [defscene]]))
(defscene default-button
[:button.btn "Click me"])
(defscene disabled-button
[:button.btn {:disabled true} "Can't click"])
;; src/my/dev/portfolio.cljs — 從您的 shadow-cljs :runner-ns 呼叫此檔案
(ns my.dev.portfolio
(:require [portfolio.ui :as ui]))
(ui/start! {:config {:css-paths ["/css/app.css"]}})
shadow-cljs :portfolio 建置目標
自動載入所有名稱結尾為 -scenes 的命名空間。最快的設定路徑:
;; shadow-cljs.edn
{:deps {:aliases [:dev]}
:dev-http {8080 ["dev-resources/public" "classpath:public"]}
:builds
{:portfolio
{:target :portfolio
:runner-ns my.dev.portfolio ;; 省略則以無設定啟動
:dev {:output-dir "dev-resources/public/js"}}}}
:dev-http 中的 "classpath:public" 是必需的 — 它會從 jar 中提供 Portfolio 的打包資產。
預設建議
- 將場景放在專用目錄(
dev/、scenes/或:dev別名來源路徑)中,這樣它們永遠不會被包含在生產建置中。 - 當元件資料非簡單時,請使用
:params— 它支援 REPL 調整和搜尋索引。 - 對於新專案,優先使用
:portfolioshadow-cljs 目標,而非手動載入命名空間。 - 如果您可以單純從生產建置中排除場景命名空間,就不要透過編譯器旗標在生產環境中壓制 Portfolio。