Topcoat UI 组件库实战:用 topcoat ui 复制、定制与维护组件
Topcoat UI 组件库实战:用 topcoat ui 复制、定制与维护组件
Topcoat UI 不是一个在运行时被依赖的组件库,而是一套"把组件源码复制进你的 crate"的工具链:topcoat ui init 安装主题与安装状态,topcoat ui add 把组件 Rust 源码写进 src/components,之后组件就是你项目里的普通模块,可以任意改写。本文以 UI 文档 为主线,结合 topcoat-ui 实现、内置 registry 清单 与 neutral 主题样式表,完整讲清初始化、Tailwind 接线、组件增删改查、主题定制与自定义 registry 的每一个参数和背后的实现逻辑。
为什么是"复制源码"而不是"加依赖"
理解这一点,后面的所有命令行为才说得通。Topcoat UI 的核心模型是 vendoring(源码内联):
- 组件是用
#[component]、view!和 Tailwind 类写成的普通 Rust 代码,安装后位于你的src/components/*.rs,编译进你自己的 crate; - 颜色、圆角、阴影等共享样式不写在组件里,而是通过
bg-primary、text-muted-foreground这类语义化工具类读取主题变量,主题定义在styles.css; - 安装状态记录在包根目录的
components.toml中,用源码内容的 SHA-256 哈希标识"版本",因此既能判断上游是否更新,也不会因为你本地修改而误判。
topcoat-ui 的 crate 文档 明确描述了这个模型:它负责加载 registry 与管理已安装组件,组件以源码哈希作为版本。所以你获得的是完全的可编辑权,代价是需要自己承担合并上游更新的成本。
环境准备:开启 feature 并配置 Cargo
先按 快速开始 安装 topcoat CLI,再接入 Tailwind 集成,最后启用 ui feature。文档给出的配置同时使用 Fontsource 加载主题指定的字体:
[dependencies]
topcoat = { version = "0.12.0", features = ["font-fontsource", "tailwind", "ui"] }
[build-dependencies]
topcoat = { version = "0.12.0", default-features = false, features = ["tailwind"] }
这里有两个容易踩错的点:
ui只是一个"带上内置 registry"的 feature。在 topcoat 的 Cargo.toml 中,ui = ["dep:topcoat-ui-registry"],即启用后会把内置组件 registry crate 纳入依赖图。CLI 的topcoat ui子命令则来自 CLI 工具本身,与运行时依赖无关。build-dependencies里必须关掉默认 feature。构建脚本只需要 Tailwind 的编译能力(BuildConfig),不需要把整个框架编译进宿主。
font-fontsource 不是可选项的装饰:内置 neutral 主题在 @theme inline 里把 --font-sans 设为 "Geist", sans-serif,而 neutral.css 的注释 明确说明 Geist 字体不随主题打包,需要用 topcoat-font 提供。
初始化:topcoat ui init 到底写了什么
在包目录下执行:
topcoat ui init
这条命令做两件事:
| 产物 | 位置 | 作用 |
|---|---|---|
components.toml |
包根目录 | 安装状态:格式版本、组件目录、已装主题与已装组件及其哈希 |
styles.css |
包根目录 | 主题样式表,同时充当 Tailwind 的输入文件 |
两个文件都应当提交到版本控制。文档强调"先 init 再使用其他 UI 命令",在实现里有硬性依据:InstallState::load 在找不到状态文件时会直接报错 no install state at ...; run \topcoat ui init` first`。
主题选择与 --theme
如果 registry 提供多个主题,命令会提示你选择;也可以用 --theme <name> 直接指定:
topcoat ui init --theme neutral
实现细节值得注意(ThemePlan::select):
- 只提供一个主题时不会弹提示,直接安装该主题;
- 传入了不存在的主题名,会报错并列出可用主题;
- 在有终端的环境下才会弹出选择器;非交互环境下若未指定
--theme,会报错提示必须显式传入。这意味着 CI 脚本里应当始终写上--theme。
组件目录与 workspace
组件默认安装到 src/components。要换目录用 --components-dir:
topcoat ui init --components-dir src/ui
该值会被写入 components.toml 的 components_dir 字段(默认值定义在 default_components_dir),此后所有 add/remove 都以它为准。注意:它只在 init 时确定一次,后续修改需要在 components.toml 里同步调整。
在 workspace 中,任何 topcoat ui 子命令都可以用 --package <name> 指定包,语义类似 cargo -p:
topcoat ui init --package admin --theme neutral
topcoat ui add button --package admin
包定位由 Package::locate 完成:指定名字时走 cargo metadata 查找成员;未指定时用 cargo locate-project 定位当前目录所属 crate,否则退化为当前目录。
初始化是幂等的反义词
init 在 components.toml 已存在时会直接失败,而不是覆盖。这是一种保护:styles.css 允许你自由定制,重复 init 会把你的主题改动冲掉。实现上它会先解析主题、再写盘(init 的注释说明了这个顺序),所以主题名写错、registry 不可达或用户取消选择时,包不会被改成"半初始化"状态。
把主题接进 Tailwind
styles.css 是完整的 Tailwind 输入文件,它包含三段关键内容:
@import "tailwindcss";
@source "./src/**/*.rs";
@custom-variant dark (&:is(.dark *));
分别负责:引入 Tailwind、扫描 Rust 源码里的类名、定义"祖先带 .dark 即暗色"的变体。因为该文件安装在包根目录,./src 正是 crate 的源码目录(见文件内注释)。
在 build.rs 中把它设为输入:
fn main() {
topcoat::tailwind::BuildConfig::new()
.input("styles.css")
.render()
.unwrap();
}
render() 会把编译结果写到 $OUT_DIR/tailwind.css。页面里通过 tailwind::stylesheet!() 引用它——该宏在 stylesheet.rs 中被定义为 asset!("{out_dir}/tailwind.css") 的封装;若自定义了输出路径,则改用 asset! 显式声明。
在根布局中加载样式与字体
主题只有在页面引入生成的样式表后才生效,并且会通过 @layer base 把基础样式应用到 <body>:
@layer base {
body {
@apply bg-background font-sans text-foreground;
}
}
因此根布局应当同时加载样式表与字体。下面是文档给出的完整示例,其中 font::link 负责输出字体资源:
use topcoat::{
Result,
context::Cx,
font::fontsource::fontsource_font,
router::{Slot, layout},
tailwind,
view::{View, view},
};
#[layout]
async fn layout(cx: &Cx, slot: Slot<'_>) -> Result<impl View> {
Ok(view! {
<!DOCTYPE html>
<html>
<head>
topcoat::font::link(font: fontsource_font!(GEIST))
<link rel="stylesheet" href=(tailwind::stylesheet!())>
</head>
<body>
(slot)
</body>
</html>
})
}
如果你换成一个不使用 Geist 的自定义主题,可以移除字体部分;但请同步确认主题里的 --font-sans 与 body 的 font-sans 是否仍能解析到实际存在的字体。
添加组件
按名字安装
topcoat ui add button
这条命令一次性完成三件事(add):
- 把组件源码复制到
components_dir,文件名为 registry 中source的末段(src/components/button.rs→button.rs); - 在模块文件里写入
pub mod button;; - 在
components.toml的[registries.topcoat.components.button]下记录hash与file。
同时,组件声明的依赖会被自动一并安装。以 registry.toml 为例:
| 组件 | 自动带入的依赖 |
|---|---|
alert_dialog |
dialog |
sheet |
dialog |
field |
label |
pagination |
button |
dropdown_menu / hover_card / popover / tooltip |
floating |
sidebar |
button、input、separator、sheet、skeleton |
依赖是传递展开的(广度优先 + 去重),所以 sidebar 会顺带把 sheet 需要的 dialog 也拉进来。
模块声明写到哪里
这是实践中第一个高频困惑点。module_file 的决策规则是:
- 若
src/components/mod.rs存在 → 写入mod.rs; - 否则写入同级兄弟文件
src/components.rs; - 两个都存在时报错,提示你删除其中一个以选定风格。
文档的表述与此一致。这里的设计取舍很明确:不猜你的意图,让你先消除歧义,避免把声明写到编译器不会读取的文件里。
安装全部组件与覆盖
内置 registry 目前提供 34 个组件。全量安装:
topcoat ui add --all
已安装的组件会被跳过并逐条报告(- skipped <name> ... already installed)。要连已存在的文件一起替换,加 --overwrite:
topcoat ui add --all --overwrite
--all --overwrite 同时具备"补齐缺失组件"的能力,这也是把项目整体升级到最新 registry 源码的最短路径。
三种写入动作对应 AddAction:Installed(首次写入)、Overwritten(替换既有文件)、Skipped(存在且未覆盖)。CLI 输出分别用 +、~、- 前缀区分(CLI add 输出)。
三类"来源"决定冲突行为
add 内部区分名字来源(Origin),这解释了为什么同样是"文件已存在",行为却不同:
| 来源 | 文件已存在且未 --overwrite |
|---|---|
| 命令行点名(Named) | 直接报错,提示加 --overwrite |
--all 扫描(Swept) |
跳过该组件并报告 |
| 作为依赖被拉入(Dependency) | 静默跳过,绝不覆盖 |
| 与其他 registry 的文件冲突且你确认替换 | 删除旧组件文件与声明后写入 |
最后一条是跨 registry 场景的保护:所有 registry 共享同一个扁平安装目录,一个文件只能容纳一个组件。若某个文件已被另一个 registry 的组件占用,命令会先询问是否替换;拒绝则中止整个操作。
查看与更新:topcoat ui list
topcoat ui list
topcoat ui list --installed
topcoat ui list --registry topcoat
列表按 registry 分组,每个组件标注状态:
| 标记 | 含义 | 判定依据 |
|---|---|---|
✓ |
已安装且与 registry 一致 | 安装哈希 == 当前源码哈希 |
↑ |
有可用更新 | 安装哈希 != 当前源码哈希 |
? |
孤立(orphaned) | 状态里记录了该组件,但 registry 不再提供,或 registry 无法加载 |
| 无标记 | 仅可安装 | registry 有该组件,本地未安装 |
判定逻辑在 statuses。一个关键结论值得单独强调:哈希比较的是 registry 源码,不是你本地的文件。因此你手改组件不会显示为"更新",list 报出的 ↑ 一定意味着上游源码变了。
拉取更新
topcoat ui add button --overwrite
这会用 registry 的源码替换你的文件。文档给出的工作流是:先保存本地改动 → 执行覆盖 → 查看 diff → 把需要保留的改动手工重新应用。因为组件是普通 Rust 文件,用 git diff 就能精确看到上游变更点。
全量刷新:
topcoat ui add --all --overwrite
顺带补齐所有你尚未安装的组件。
使用组件:一个完整表单
安装后的组件就是普通模块。下面的登录卡片示例来自文档,涵盖了 card、field、input、button 的典型组合:
mod components;
use components::button::button;
use components::card::{
card, card_content, card_description, card_footer, card_header, card_title,
};
use components::field::{field, field_description, field_group, field_label};
use components::input::input;
use topcoat::{
Result,
context::Cx,
view::{View, attributes, component, element_id, view},
};
#[component]
async fn sign_in(cx: &Cx) -> Result<impl View> {
Ok(view! {
// Elements that refer to each other share these IDs.
let form = element_id(cx);
let email = element_id(cx);
let email_description = element_id(cx);
card(
card_header(
card_title("Sign in")
card_description("Use your work email to continue.")
)
card_content(
<form id=(&form) method="post" action="/login">
field_group(
field(
field_label(attrs: attributes! { for=(&email) }, "Email")
input(
attrs: attributes! {
id=(&email)
name="email"
type="email"
placeholder="you@example.com"
aria-describedby=(&email_description)
}
)
field_description(
attrs: attributes! { id=(&email_description) },
"Use the email address associated with your account."
)
)
)
</form>
)
card_footer(
button(
attrs: attributes! { class="w-full" type="submit" form=(&form) },
"Sign in"
)
)
)
})
}
这段代码刻意演示了两个细节:
element_id(cx)避免手写 id。<form>的id被 footer 里按钮的form属性引用;field_label的for与input的id对应;field_description的id被aria-describedby引用。三者都是"元素之间互相引用"的关系,手写字符串极易冲突。field_label而不是裸<label>。查看 field.rs 可见它会在disabled时降低透明度、在aria-invalid="true"时把标签文字染成text-destructive,这些样式依赖field容器上的group/field类,必须组合使用。
四条共享约定
文档总结了组件共同遵守的约定,逐条都能在源码中印证:
1. 变体与尺寸用枚举 prop。 例如 button 的签名:
pub async fn button(
cx: &Cx,
#[default] variant: ButtonVariant,
#[default] size: ButtonSize,
#[default] mut attrs: Attributes,
#[default] child: Child<'_>,
) -> Result<impl View>
#<a href="https://link.gitcode.com/i/0ba339ae74298a8427172d6598113a5f" target="_blank">default] 表示可以省略,此时取类型的 Default 实现。ButtonVariant 的默认值是 Primary,ButtonSize 是 Md(见 [button.rs)。要表达危险操作:
button(variant: ButtonVariant::Destructive, "Delete")
2. 额外属性走 attrs。 用 attributes! 构造。每个组件文档都会说明属性落到哪个元素上——button 落到 <button>,card 落到外层 <div>,field 落到包裹的 <div role="group">。源码里统一写成先 attrs.remove("class") 再参与 class! 组合,因此你传入的类会追加到组件默认类之后。
这里有一个重要限制:追加不会解决 Tailwind 工具类冲突。手册的建议是使用更具体的选择器,或直接修改组件源码来可靠地覆盖默认值。例如想改卡片的内边距,与其在 attrs 里传 py-0 赌优先级,不如编辑 card.rs 中的 CARD 常量。
3. 内容通过 children 传递。 子节点可以是文本、HTML 元素或其他组件,这正是 Child<'_> 参数的作用。
4. 用 class helper 复用样式。 需要"看起来像按钮的链接"时,不要包裹一个按钮,而是取类名:
view! {
<a href="/login" class=(button_variants(ButtonVariant::Outline, ButtonSize::Md))>
"Sign in"
</a>
}
button_variants 在 button.rs 中就是把 BASE、变体类、尺寸类拼成一个 Class。同类 helper 还有 badge_variants。这比复制粘贴一长串类名更可靠:语义化变体仍然集中在一处维护。
组件的确切 props 与行为应以源码为准,examples/ui 提供了可运行的完整展示。
主题定制:改变量而不是改组件
主题的关键设计是"组件只引用 token,不引用原始颜色"。styles.css 里 @theme inline 把 --color-* 映射到 :root / .dark 中的变量,于是切换颜色方案只需要换变量值。
语义化 token 一览
| Token | 用途 |
|---|---|
--background / --foreground |
页面底色 / 其上的文字与图标 |
--card / --card-foreground |
卡片与面板底色 / 其上的文字 |
--popover / --popover-foreground |
浮层菜单、弹层底色 / 其上的文字 |
--muted-foreground |
次要文字:说明、占位符、caption |
--primary / --primary-foreground |
强调色:主操作、选中、高亮 / 主色填充上的文字 |
--destructive / --destructive-foreground |
危险操作与错误态 / 其上的文字 |
--border |
细边框与分割线 |
--ring |
焦点环 |
--sidebar*(8 个) |
侧边栏专属的底色、前景、主操作、hover/选中、边框、焦点环 |
--shadow-xs / --shadow-sm |
轻微抬起的控件 / 卡片与菜单的投影 |
每个 token 可独立调整,文档特意强调 --background 与 --card、--card-foreground 是分开的,便于做"同色系但不同层"的层次感。
暗色模式
给 <html>(或任意祖先元素)加 dark 类即可启用暗色;加在局部祖先上则只对子树生效。该行为由 @custom-variant dark (&:is(.dark *)); 定义,要改暗色配色就编辑 .dark 块里的变量。
默认没有阴影
这是很容易被忽略的默认值:neutral 主题把两个阴影变量都设成 0 0 #0000:
--shadow-xs: 0 0 #0000;
--shadow-sm: 0 0 #0000;
要启用,把 :root 和 .dark 里的这两行替换为紧邻注释中的值(两个作用域都要改,否则切换暗色时阴影会消失)。注释还解释了为什么用 0 0 #0000 而不是 none:Tailwind 把阴影和焦点环合并进同一个 box-shadow,用 none 会连焦点环一起废掉。
组件如何派生交互态
主题注释说明了另一条约定:hover 与按下态由填充色或前景色按降低的不透明度派生,例如按钮的 hover:bg-primary/90 active:bg-primary/80。侧边栏单独使用 --sidebar-accent,因此可以独立于主色系调校。
init 之后可以自由改
文档明确保证:UI 命令在初始化之后不会覆盖 styles.css。这与 add --overwrite 只覆盖组件文件的行为一致。换句话说,主题是你的资产,组件源码也是你的资产,只有 components.toml 由工具维护(建议不要手改,尤其是其中的 hash)。
移除组件
topcoat ui remove button
它做三件事:删除组件文件、移除模块声明、从 components.toml 中删除条目。两个细节:
- 不会顺带删除当初作为依赖安装进来的组件。
field依赖label,移除field后label.rs依然在项目里,需要的话自己再remove。 - 删除前会先解析全部目标(
remove),拼错名字或跨 registry 歧义会在动文件之前报错。当同名组件从多个 registry 安装时,用--registry <name>指定来源:
topcoat ui remove button --registry my-registry-crate
module::undeclare 还有个好用行为:当模块文件里最后一条声明被移除后,若文件只剩空行,会直接删除该模块文件,不留下空壳。
自定义 registry
当团队需要沉淀自己的设计系统时,可以发布一个 registry crate。文档给出的最小结构如下。
在 registry crate 的 Cargo.toml 中声明 manifest 目录:
# Cargo.toml of the registry crate
[package.metadata.topcoat-ui]
registry = "registry"
在 registry/registry.toml 中声明主题与组件:
version = 1
[themes.acme]
source = "themes/acme.css"
[components.button]
source = "src/components/button.rs"
[components.data_table]
source = "src/components/data_table.rs"
# Installed alongside data_table. An entry names a component in the same
# registry, or one in another registry by that registry's crate name.
dependencies = ["button", { registry = "other-registry-crate", name = "spinner" }]
字段语义在源码中非常明确(registry.rs):
| 字段 | 说明 |
|---|---|
version |
manifest 格式版本,当前最高支持 1;声明更高版本会被拒绝 |
[themes.<name>].source |
相对 registry 目录的 CSS 路径 |
[components.<name>].source |
相对 registry 目录的 Rust 源文件路径 |
[components.<name>].dependencies |
字符串=同 registry 的组件名;表 {registry, name}=另一个 registry crate 的组件 |
文件名与注册名可以不同:data_table 用下划线命名,落地文件名取自 source 的末段,因此可以写 src/components/data_table.rs 而调用时用 data_table(...)。
组件的"版本"来自源码
文档指出:组件版本由源码计算,分发更新就是发布 registry crate 的新版本。实现上 content_hash 会对源码做 SHA-256 并加上 sha256: 前缀(registry.rs)。因此只要源码不变,即使 crate 版本号变了,list 也不会误报更新。
消费自定义 registry
把 registry crate 声明为直接依赖:
topcoat ui add data_table --registry my-registry-crate
这条约束有明确报错:非直接依赖会得到 registry crate ... must be a direct dependency in Cargo.toml(workspace.rs)。原因是组件安装会改动消费方源码,工具需要确保来源是你显式认可的 crate。内置 registry 例外,允许作为传递依赖——它由 ui feature 引入。
省略 --registry 时的解析顺序(resolve_root_registry):
- 内置
topcoatregistry 有该组件 → 直接用它; - 否则在所有依赖 registry 中查找;
- 只有一处提供 → 询问是否从该 registry 安装;拒绝则提示改用
--registry; - 多处提供 → 直接报错,要求显式
--registry消歧。
非交互环境(如 CI)无法回答确认提示,会返回错误并建议传 --registry。所以脚本里始终显式写 --registry。
另外,所有 registry 共享同一安装目录,如果两个 registry 提供同名不同源的文件,工具会在替换前询问;只由一个 registry 提供、路径不同的同名组件则互不冲突。
工程化建议
把一致性交给测试
仓库自带的 demos/admin 演示了一种值得借鉴的守护方式:registry_sync.rs 用 topcoat_ui::Registry 加载内置 registry,逐项断言已安装文件与上游源码一致,并检查 src/components 下没有"野生"组件(自定义组件需登记在 OWN_COMPONENTS 白名单)。失败信息直接给出修复命令,例如 run \topcoat ui add {name} --overwrite` in demos/admin`。
这解决了一个真实风险:项目长期迭代后,没人记得哪些组件文件被改过、哪些是原样复制。测试能强制你为每一处偏离留下明示记录。
命令速查
| 命令 | 作用 |
|---|---|
topcoat ui init [--theme <name>] [--components-dir <dir>] [--package <name>] |
创建 components.toml 并安装主题到 styles.css |
topcoat ui add <name>... [--registry <crate>] [--overwrite] |
安装指定组件及其传递依赖 |
topcoat ui add --all [--overwrite] |
安装/刷新 registry 中全部组件 |
topcoat ui list [--registry <crate>] [--installed] |
列出组件与状态(已装 / 有更新 / 孤立) |
topcoat ui remove <name>... [--registry <crate>] |
删除组件文件、模块声明与状态记录 |
--package <name> |
附加于任意子命令,选中 workspace 成员 |
三条容易被忽略的边界
- 初始化只能一次。
init遇到已有components.toml会失败;要重装主题得先删掉它和styles.css,如demos/admin测试提示的那样。 --overwrite会丢本地修改。它替换整个文件,不做三方合并。更新前先提交或 stash。- 模块声明文件风格一旦选定就固定。
src/components.rs与src/components/mod.rs同时存在会让add/remove在写盘前直接报错。
小结
Topcoat UI 把"组件库"从运行时依赖变成了可编辑源码 + 可追踪的安装状态:topcoat ui init 建立主题与 components.toml,build.rs 把 styles.css 编译成 Tailwind 输出,topcoat ui add 复制源码并自动带入依赖,list 依赖源码哈希发现上游更新,remove 干净回收文件与声明,而自定义 registry 让团队可以按同一套 manifest 格式分发自己的设计系统。真正决定项目是否好维护的,不是这些命令本身,而是本文强调的几条纪律:把 components.toml 与 styles.css 纳入版本控制、把覆盖更新当作需要 review 的 diff、把主题定制收敛在 CSS 变量上,而不是散落在组件源码里。