快速开始
如何使用
主题接入与各组件用法示例。
如何使用
1. 引入模块
QML 侧只需一行 import，组件与主题即可使用：
import QtShadcn
2. 主题接入（必做）
任何使用组件的页面/窗口先放一个 QtShadcnTheme（声明式入口，绑定 C++ ThemeManager 的 token 字典）：
import QtQuick
import QtQuick.Controls as QQC
import QtShadcn
Window {
id: root
width: 640
height: 480
visible: true
QtShadcnTheme { id: theme }
color: theme.background // 窗口底色跟主题走
QQC.Button {
anchors.centerIn: parent
text: qsTr("点击")
onClicked: theme.mode = theme.mode === "dark" ? "light" : "dark"
}
}
Theme 属性一览（全部只读，组件直接绑定）：
| 类别 | 属性 |
|---|---|
| 颜色 | background foreground primary primaryForeground secondary secondaryForeground muted mutedForeground accent accentForeground destructive destructiveForeground border ring |
| 形状 | radius（全局圆角） |
| 间距 | spacingXs spacingSm spacingMd spacingLg spacingXl |
| 原始字典 | tokens（动态索引，如 theme.tokens["primary"]） |
切换明暗：theme.mode = "dark" → 全局随动，所有绑定自动刷新。
3. ShadcnButton
ShadcnButton {
text: qsTr("Deploy")
variant: ShadcnButton.Variant.Primary // Primary / Secondary / Outline / Ghost / Destructive / Link
size: ShadcnButton.Size.Medium // ExtraSmall / Small / Medium / Large / Icon
loading: false
onClicked: console.log("clicked")
}
- variant × size 对照：Primary 实心主色、Secondary 次色、Outline 描边、Ghost 幽灵、Destructive 危险、Link 链接（hover 下划线）
- 尺寸：XS=32 / Small=36 / Medium=40 / Large=44 / Icon=40（对齐 shadcn/ui）
- loading：显示 Spinner 且禁用交互，文字半透明
- disabled：继承 QQC
enabled属性，禁用态整体 50% 透明度 - 键盘焦点：Tab 可达，聚焦显示 ring 焦点环（继承 QQC Button 行为）
4. ShadcnButtonGroup（按钮组）
ShadcnButtonGroup {
ShadcnButton { text: qsTr("A"); variant: ShadcnButton.Variant.Primary }
ShadcnButton { text: qsTr("B"); variant: ShadcnButton.Variant.Primary }
ShadcnButton { text: qsTr("C"); variant: ShadcnButton.Variant.Primary }
}
组内按钮自动合并边框、只留两端圆角；无 border 的 variant（如 Primary）中间自动加 1px 分隔线。
5. ShadcnToggle / ShadcnToggleGroup（切换按钮）
// 独立切换（outline 样式 + checkable，选中时 accent 背景）
ShadcnToggle { text: qsTr("粗体") }
ShadcnToggle { text: qsTr("斜体"); checked: true }
// 多选组
ShadcnToggleGroup {
ShadcnToggle { text: qsTr("左") }
ShadcnToggle { text: qsTr("中"); checked: true }
ShadcnToggle { text: qsTr("右") }
}
// 单选组（exclusive: true）
ShadcnToggleGroup {
exclusive: true
ShadcnToggle { text: qsTr("单选 1"); checked: true }
ShadcnToggle { text: qsTr("单选 2") }
}
6. ShadcnSpinner（加载指示器）
ShadcnSpinner { width: 14; height: 14; color: theme.foreground }
ShadcnButton 的 loading: true 内部即用它。
完整示例（组合用法）
import QtQuick
import QtQuick.Layouts
import QtShadcn
Rectangle {
color: theme.background
QtShadcnTheme { id: theme }
ColumnLayout {
spacing: theme.spacingMd
anchors.centerIn: parent
ShadcnCard { /* M3 落地后：卡片容器 */ }
RowLayout {
spacing: theme.spacingSm
ShadcnButton { text: qsTr("新建"); onClicked: doCreate() }
ShadcnButton {
text: qsTr("提交")
variant: ShadcnButton.Variant.Outline
loading: busy
}
}
}
}