QtShadcn
快速开始

安装与构建

克隆、构建并运行 QtShadcn showcase。

环境要求

  • Qt 6.5+(本机开发环境:Qt 6.11.1 @ ~/Qt/6.11.1/macos, Apple Silicon arm64)
  • CMake 3.24+

获取源码

git clone https://github.com/QtShadcn/qtshadcn.git
cd qtshadcn

构建

# 一键构建(默认 QT_PREFIX=$HOME/Qt/6.11.1/macos,可用环境变量覆盖)
make build

# 运行 showcase(Design Token 色板 + 组件展示,明暗切换)
make run

或手动:

cmake -S . -B build -DCMAKE_PREFIX_PATH="${QT_PREFIX:-$HOME/Qt/6.11.1/macos}" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build
./build/bin/showcase

!TIP 本机多 Qt 版本共存时,用 QT_PREFIX / -DCMAKE_PREFIX_PATH 指定版本。Linux 用 gcc_64,Homebrew 用 $(brew --prefix qt)。

在你的项目里使用

三种方式任选其一。

方式一:find_package(预编译安装)

cmake -S . -B build -DCMAKE_PREFIX_PATH="$HOME/Qt/6.11.1/macos"
cmake --build build
cmake --install build --prefix /your/prefix
find_package(QtShadcn 0.2 REQUIRED)
target_link_libraries(myapp PRIVATE QtShadcn::QtShadcn Qt6::Quick)

链接上目标就够 import QtShadcn:QML 模块(qmldir、类型信息、全部 .qml)编译在库资源里, 运行时不需要 QML_IMPORT_PATH。安装出的磁盘副本在 <prefix>/lib/qml/QtShadcn, 只给 qmllint / qmlls / Qt Designer 用(CMake 变量 QtShadcn_QML_IMPORT_PATH)。

方式二:FetchContent

include(FetchContent)
FetchContent_Declare(qtshadcn
    GIT_REPOSITORY https://github.com/QtShadcn/qtshadcn.git
    GIT_TAG        v0.2.0)
FetchContent_MakeAvailable(qtshadcn)
target_link_libraries(myapp PRIVATE QtShadcn Qt6::Quick Qt6::QuickControls2)

方式三:submodule / clone 到 third_party(便于本地改库源码)

mkdir -p third_party
git submodule add https://github.com/QtShadcn/qtshadcn.git third_party/qtshadcn
find_package(Qt6 REQUIRED COMPONENTS Core Gui Quick Qml QuickControls2 Svg Network)
add_subdirectory(third_party/qtshadcn)
target_link_libraries(myapp PRIVATE QtShadcn Qt6::Quick Qt6::QuickControls2)

main.cpp 必须 QQuickStyle::setStyle("Basic")。

QML_IMPORT_PATH 只有「不链接库、纯靠 import 路径加载」时才需要(例如直接跑 .qml 文件、 或给 qmllint 指路),此时要指到模块目录的父路径(build/third_party/qtshadcn/src)。

import QtShadcn

Window {
    QtShadcnTheme { id: theme }
    ShadcnButton { text: qsTr("Deploy") }
}
Copyright © 2026