Portfolio
Portfolio 是一个 ClojureScript 的“可视化 REPL”——它在命名、隔离的场景中渲染 UI 组件,让你能一眼看到所有组件状态。它类似于 Storybook.js,但专为 REPL 驱动的 ClojureScript 开发而设计。
当前版本: no.cjohansen/portfolio {:mvn/version "2026.03.1"}
快速决策:你需要什么?
| 任务 | 前往 |
|---|---|
| 安装、启动 UI、shadow-cljs 设置 | setup.md |
使用 defscene、参数、原子、生命周期定义场景 | 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,如果可以从生产构建中简单地排除场景命名空间的话。