Topcoat UI 组件库实战:用 topcoat ui 复制、定制与维护组件

原创2026-11-11 20:12:062,265 阅读
文章标签:后端Web框架前端

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"] }

这里有两个容易踩错的点:

  1. ui 只是一个"带上内置 registry"的 feature。在 topcoat 的 Cargo.toml 中,ui = ["dep:topcoat-ui-registry"],即启用后会把内置组件 registry crate 纳入依赖图。CLI 的 topcoat ui 子命令则来自 CLI 工具本身,与运行时依赖无关。
  2. 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):

  1. 把组件源码复制到 components_dir,文件名为 registry 中 source 的末段(src/components/button.rs → button.rs);
  2. 在模块文件里写入 pub mod button;;
  3. 在 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):

  1. 内置 topcoat registry 有该组件 → 直接用它;
  2. 否则在所有依赖 registry 中查找;
  3. 只有一处提供 → 询问是否从该 registry 安装;拒绝则提示改用 --registry;
  4. 多处提供 → 直接报错,要求显式 --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 成员

三条容易被忽略的边界

  1. 初始化只能一次。init 遇到已有 components.toml 会失败;要重装主题得先删掉它和 styles.css,如 demos/admin 测试提示的那样。
  2. --overwrite 会丢本地修改。它替换整个文件,不做三方合并。更新前先提交或 stash。
  3. 模块声明文件风格一旦选定就固定。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 变量上,而不是散落在组件源码里。

登录后查看全文
topcoat