M3 组件规范对照表

来源：shadcn/ui 官方文档 + 源码（apps/v4/registry/bases/base/ui/*.tsx + apps/v4/registry/styles/style-luma.css），抓取于 2026-08-18。 依据：组件开发流程铁律（先研究 → 输出对照表 → 确认 → 实现）。

0. 公共决策（跨组件）

0.1 新增 Design Tokens（ThemeManager）

shadcn 语义中 M3 组件需要但当前 tokens 缺失的项：

• QtShadcnTheme.qml 同步暴露只读属性：card cardForeground input popover popoverForeground
• light/dark 两套 tokens 各加 5 项（值如上，与背景/边框体系自洽）

0.2 圆角体系决策（v4 激进大圆角 vs 项目既有体系）

v4 luma 风格大量使用 rounded-3xl(24px) / rounded-4xl(32px)，与本项目 M2 已定体系 （控件 6px / 容器 8px）冲突。决策：遵循项目既有体系，不跟 v4 大圆角：

若后续想对齐 v4 大圆角，仅需改各组件圆角属性，不影响 token 体系。

1. ShadcnCard（纯组合组件，无 QQC 基类）

结构（对齐 shadcn 组合方式）

Card（容器）
├── CardHeader  （padding、间距，可含 title/description/action）
│   ├── CardTitle        （font-medium, text-base=16px）
│   ├── CardDescription  （text-sm=14px, mutedForeground）
│   └── CardAction       （右上角动作区，可选）
├── CardContent （内容区）
└── CardFooter  （flex 横向，底部按钮区）

shadcn 规范值

QML 实现要点

• 纯组合：ShadcnCard 容器 + ShadcnCardHeader + ShadcnCardTitle + ShadcnCardDescription + ShadcnCardContent + ShadcnCardFooter 六个 QML 类型
• 容器：Rectangle + radius: theme.radius + color: theme.card + border.width: 1 + border.color: Qt.rgba(theme.foreground, 0.05) + 阴影（layer 或简单矩形叠层）
• 子组件用 Item 派生、default property 接子项、leftPadding/rightPadding/topPadding/bottomPadding 由外部 padding 属性控制（对齐 shadcn：Header/Content/Footer 各自带 padding，Card 管 gap）
• 内容流：Header/Content/Footer 垂直堆叠（Column），间距 gap-1.5(6px) 等对齐
• 提供 size: "default" | "sm" 属性（sm 内边距 16px）

2. ShadcnInput（基于 QQC.TextField）

shadcn 规范值

QML 实现要点

• import QtQuick.Controls.Basic，基于 TextField，重写 background + placeholderTextColor
• 背景 Rectangle：radius: 6，常态 color: Qt.rgba(theme.input, 0.5) + 1px 透明边框；activeFocus 时 border.color: theme.ring + 外扩 ring 环（3px、30% 透明，同 Button 焦点环做法）
• placeholderTextColor: theme.mutedForeground
• 禁用态 opacity: 0.5（!enabled）
• implicitWidth: 200（shadcn 无默认宽，w-full 由外部决定）

3. ShadcnBadge

shadcn 规范值

variants（v4 官方，6 种）

注意 v4 变化：destructive 是「透明底 + 红字」（旧版是实心红底白字），按 v4 实现。

QML 实现要点

• 无 QQC 基类：Item/Rectangle 容器 + 内部 Text（对齐 Button 的居中做法）
• variant → token 查表：新增 VariantTokens.badge 表（bg/fg 字符串，沿用现有机制）；destructive 需特殊处理（底色 = destructive 10% 透明，非实心）
• 支持 text 属性；implicitWidth: text + 16，implicitHeight: 20
• 复用 theme.tokens[] 查询保持 mode 切换绑定

4. ShadcnSwitch（基于 QQC.Switch）

shadcn 规范值（size: default / sm）

QML 实现要点

• 基于 QQC.Switch（Basic style），重写 background + indicator（或 contentItem）
• 轨道：Rectangle 宽高随 size（44×20 / 28×16），radius: height/2；checked → theme.primary + 1px primary 边框；!checked → Qt.rgba(theme.input, 0.9) + 透明边框
• 滑块：Rectangle（24×16 / 16×12），radius: height/2，color: theme.background；x 绑定：checked ? width - thumb.width - 2*border : 2（用 Behavior on x 或 NumberAnimation 150ms 过渡）
• 聚焦环：activeFocus 时 3px ring 外环（同 Input）
• disabled：opacity: 0.5

5. ShadcnTabs（基于 QQC.TabBar / TabButton / StackLayout）

结构

ShadcnTabs（容器）
├── ShadcnTabsList（TabBar 视觉：胶囊底 or line）
│   ├── ShadcnTabsTrigger（TabButton，选中态 + 指示器）
│   └── ...
└── ShadcnTabsContent（StackLayout 页区）

shadcn 规范值

QML 实现要点

• ShadcnTabs：暴露 currentIndex/currentItem/currentTitle，管 Trigger 与 Content 的联动
• ShadcnTabsList：TabBar（Basic），重写 background；position 对齐 shadcn（列表在上）
• ShadcnTabsTrigger：TabButton，重写 background（选中 bg-background / 常态透明）+ 内容 Text（60%→100% 透明切换）+ line variant 下划线指示器（Rectangle 2px，x 动画可选）
• ShadcnTabsContent：StackLayout（或 TabBar + 关联 StackLayout），currentIndex 绑定
• 提供 variant: default/line、orientation（横向为主，vertical 后期）

6. ShadcnDialog（基于 QQC.Dialog）

结构

ShadcnDialog（Popup 封装）
├── ShadcnDialogOverlay  （bg-black/30 + backdrop-blur）
├── ShadcnDialogContent  （popover 底 + 圆角 + 阴影 + 居中）
│   ├── ShadcnDialogHeader（Title + Description）
│   │   ├── ShadcnDialogTitle
│   │   └── ShadcnDialogDescription
│   ├── （业务内容）
│   └── ShadcnDialogFooter（按钮区，右对齐）
└── ShadcnDialogClose  （右上角 X，ghost 图标按钮）

shadcn 规范值

QML 实现要点

• 基于 QQC.Dialog（Basic），modal: true；重写 overlay（黑 30% + blur）
• 内容：ShadcnDialogContent 容器（popover 底 + 8px 圆角 + 1px 环 + 阴影 + 448px 宽），居中于 overlay
• standardButtons: Dialog.NoButton，关闭由右上角 X / Esc（QQC 自带）触发
• Header/Footer 组合组件对齐 Card 风格；closeButtonVisible 属性控制 X 显示（shadcn showCloseButton）
• 动画：进入时 opacity 0→1 + scale 0.95→1（100ms），退出反向

7. 各组件 API 草案（与 shadcn 对齐）

// Card
ShadcnCard { size: "default" }  // default | sm
    ShadcnCardHeader {
        ShadcnCardTitle { text: "标题" }
        ShadcnCardDescription { text: "描述" }
    }
    ShadcnCardContent { /* 业务内容 */ }
    ShadcnCardFooter {
        ShadcnButton { text: "确定" }
    }

// Input
ShadcnInput {
    placeholderText: "请输入"
    onAccepted: ...
}

// Badge
ShadcnBadge { text: "New"; variant: ShadcnBadge.Variant.Default }
// Default / Secondary / Destructive / Outline / Ghost / Link

// Switch
ShadcnSwitch { checked: true; size: ShadcnSwitch.Size.Default }  // Default | Small

// Tabs
ShadcnTabs {
    currentIndex: 0
    ShadcnTabsList {   // variant: "default" | "line"
        ShadcnTabsTrigger { text: "账户" }
        ShadcnTabsTrigger { text: "密码" }
    }
    ShadcnTabsContent { /* 页 1 */ }
    ShadcnTabsContent { /* 页 2 */ }
}

// Dialog
ShadcnDialog {
    id: dialog
    title: "确认删除"
    ShadcnDialogContent {
        ShadcnDialogHeader {
            ShadcnDialogTitle { text: dialog.title }
            ShadcnDialogDescription { text: "此操作不可撤销。" }
        }
        ShadcnDialogFooter {
            ShadcnButton { text: "取消"; onClicked: dialog.close() }
            ShadcnButton { text: "删除"; variant: ShadcnButton.Variant.Destructive; onClicked: dialog.close() }
        }
    }
}

8. 实现顺序与验证

1. ThemeManager 加 5 个新 token + QtShadcnTheme 暴露属性（先行，供后续组件使用）
2. Card → Input → Badge → Switch → Tabs → Dialog（每个：实现 → QML_FILES 注册 → showcase 新页 → 全状态展示）
3. showcase「组合示例」：新建项目对话框（Dialog + Card + Input + Button + Tabs 组合），验证 M3 集成
4. make build + 运行截图确认 + commit + 关闭 GitHub issues