组件开发流程
When to Use
- 开发 qtshadcn 组件库(
~/dev/qt/qtshadcn)新组件(对应 GitHub issues,每批一个,实现完关 issue) - 需要实现 shadcn/ui 风格(Design Token 驱动)的 QML 组件
铁律:先研究再实现
开发任何组件前必须研究 shadcn/ui 参考实现,禁止凭印象直接写。
M2 教训:凭印象写的 Button 尺寸整体小一档、漏 link variant、圆角写错,全靠事后对照返工。
后来 v4 又把刻度整体收紧一档,同样的毛病第二次复发 —— 所以现在只认 registry JSON / style-nova.css 里的实际类名,且圆角一律走 theme.radius* 派生值。
1. 抓官方文档(含 variants/sizes 列表)
# 网速慢用代理 7897或7890
curl -sL -x http://127.0.0.1:7897 "https://ui.shadcn.com/docs/components/<name>" -o /tmp/shadcn-<name>.html
python3 -c "
import re, html
text = open('/tmp/shadcn-<name>.html').read()
m = re.search(r'<main[^>]*>(.*?)</main>', text, re.S)
body = m.group(1) if m else text
body = re.sub(r'<script.*?</script>', '', body, flags=re.S)
body = re.sub(r'<[^>]+>', ' ', body)
print(html.unescape(re.sub(r'\s+', ' ', body)))
"
2. 抓源码(gh api 认证,免限流)
shadcn-ui/ui 仓库 2026 年已重构:
- v2/v3 稳定路径(广为人知的 cva 定义):
apps/www/registry/default/ui/<name>.tsx - v4 新路径:
apps/v4/registry/__components__/base-luma.tsx(主题变体文件,内部import("@/styles/base-luma/ui/<name>")),styles 路径apps/v4/styles/base-luma/ui/<name>.tsx
# 先列目录找路径(路径常变)
gh api "repos/shadcn-ui/ui/contents/apps/v4/registry/__components__" --jq '.[].name'
# 再拿文件内容
gh api "repos/shadcn-ui/ui/contents/apps/v4/registry/__components__/base-luma.tsx" --jq '.content' | base64 -d
注意:GitHub Contents API 未认证会限流(尤其走代理 IP);raw.githubusercontent 路径随重构 404,用 gh api 列目录确认。
3. 梳理规范清单(输出对照表再写码)
| 维度 | 必须确认 |
|---|---|
| variants | 完整列表(Button: default/secondary/destructive/outline/ghost/link) |
| sizes | 全部尺寸 + 像素值。直接读 registry JSON,别凭记忆(见下方取数命令) |
| 交互状态 | hover / pressed / disabled(opacity-50) / loading / focus(ring) |
| 样式细节 | 圆角、字重(font-medium=500)、padding、gap、hover 语义 |
| API | 属性 / 事件 / 变体枚举命名 |
| 无障碍/键盘 | 继承 QQC 基类行为(键盘导航/Focus/Accessible 白拿) |
取数命令(Tailwind 类名与像素的对应关系在 CSS 里,不在文档里):
# 组件实现(cva 里的 class 串 = 唯一事实来源)
curl -s "https://ui.shadcn.com/r/styles/base-nova/<name>.json" | python3 -c "
import json,sys; d=json.load(sys.stdin); print(d['files'][0]['content'])"
# 样式变体(.cn-* 的 @apply 串)
curl -sL "https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/registry/styles/style-nova.css"
# 圆角/间距刻度(@theme inline 里的派生公式)
curl -sL "https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/app/globals.css"
圆角不要抄像素,抄刻度:v4 的 rounded-sm/md/lg/xl/2xl/3xl/4xl = --radius ×
0.6 / 0.8 / 1.0 / 1.4 / 1.8 / 2.2 / 2.6。组件一律绑 theme.radiusSm/Md/Lg/Xl,
写死像素(按钮 6、弹窗 14)是历史漂移的直接原因。
4. 对照实现(QtShadcn 项目规范)
- 组件命名
Shadcn*前缀,文件src/qml/Components/ShadcnXxx.qml,加进src/CMakeLists.txt的QML_FILES - 基于 QQC 基类(
import QtQuick.Controls.Basic,style-specific import 是 token 自绘前提),只替换 background/contentItem - variant → token 映射集中在
src/qml/Theme/VariantTokens.qml:新增 variant = 枚举 + 映射表各加一项(顺序对齐);用 QtObject 属性定义(var 对象字面量在 qmlcache 下不可靠) - 颜色经
theme.tokens[token名]查询(保持 mode 切换绑定;存颜色值会变静态) - 文字居中:QQC 会把 contentItem 拉伸到内容区全宽 → Item 包装 + RowLayout
anchors.centerIn(水平垂直都稳);Row 子项 AlignTop 会偏上 - 动画用 Shape + Animator(禁 Canvas 动画);文案 qsTr();import 无版本号;Layout 子项用
Layout.*不用裸 width
5. showcase 验证
examples/showcase/Main.qml展示全部 variant × size × 状态(含 disabled/loading/拉伸宽度)make build构建;python 后台启动 + poll 存活 + stderr 干净 +screencapture截图给用户确认- 确认后 commit + 关对应 GitHub issue;若这批还有未完成项,先拆成独立 issue 再关(见下方「issue 关闭约定」)
M2 Button 实测偏差教训(防再犯)
- 尺寸:当年按 shadcn v3 口径 Medium=40 / Large=44 / Small=36 / XS=32 / Icon=40;
v4 base 已整体收紧一档(
h-8/h-9/h-7/h-6/size-8= 32/36/28/24/32)。 教训不是「记住数字」,而是「数字会随版本变」——所以现在写进_ctrlHeight表里并配tst_ShadcnButton.qml断言,改版本必须同时改测试 - 漏 link variant:text-primary + hover 下划线,无背景无 hover 块
- 圆角:当年写死 rounded-md = 6px,v4 起改为从
--radius派生(见上方表格) - 字重 font-medium = 500
- disabled / loading:opacity 50%
- hover 语义:default/secondary/destructive 变暗(90% 透明度等效黑 8% overlay);outline/ghost 用 accent 背景 + accentForeground 文字;link 仅下划线
- 按钮组:无 border 的 variant(如 Primary)中间需 1px 分隔线(前景色 15% 透明度);spacing: -1 合并边框;圆角只留两端
issue 关闭约定
一个 issue 对应一批组件,主体交付即关闭,未完成项拆成独立 issue 继续跟踪。
理由:让「M3 没做完」「M4 Icon 没做完」这类表述与实际严重不符 —— Icon 早已 5/5 交付,却因为挂着 Animations 一直显示未完成,反过来还会麻痹判断(看到一条挂了三个月的 issue 会以为整个 milestone 都停着)。
拆分时的要求:
- 新 issue 正文写清从哪条拆出、原 issue 已完成什么,读者不需要翻历史
- 剩余项要带上已调研的结论(决策、实测数据、优先级建议),否则等于把调研白做一遍
- 在原 issue 的关闭评论里列出已完成清单 + 指向新 issue
例:#3 布局与反馈(8 项交付)→ 关闭,剩余 4 项见 #13;#6 Icon + Animations(Icon 5/5)→ 关闭,Animations 见 #14。
项目速查
- 技术方案:设计 → 技术方案(11 节 = 组件开发流程)
- 组件计划:GitHub issues(每批一个,主体交付即关,剩余项拆出)
- 构建:Qt 6.5+ / CMake 3.24+;token 自绘须
QQuickStyle::setStyle("Basic")(macOS 默认 native style 拒绝自定义 contentItem) - 规范技能:qt-qml(Qt 官方 agent-skills,QML 最佳实践)
