CREEPER-QT

基于 Qt 的现代化 UI 包装库

使用指南 • 组件文档 • 布局文档 • 主题文档 • API 参考 • 视频演示

---

✨ 项目简介

creeper-qt 是基于 Qt 开发的 轻量级 UI 集成库，具有以下特点：

• 现代化设计 - 组件外观遵循 Google Material Design3 规范
• 声明式接口 - 改造传统命令式调用，组件构造和配置一步完成
• 主题系统 - 内置主题管理，支持明亮/黑暗模式及多种配色方案
• 流畅动画 - 基于 PID 控制器和弹簧模型的迭代算法，实现丝滑动效和无缝打断
• 开箱即用 - 提供跨平台示例程序，快速上手体验

欢迎贡献！ 期待您的 PR 和 ISSUE

QQ交流群：885246539

---

📦 快速体验

下载示例程序

这里有一份自动构建的跨平台示例程序，无需编译即可体验完整功能。

• 📥 下载最新版本 (GitHub Releases)

平台支持

操作系统	安装与运行方式
🐧 Linux	下载 AppImage 文件，赋予执行权限后直接运行；或下载 .tar.gz 压缩包，解压后执行 AppRun 文件
🪟 Windows	下载 .zip 压缩包并解压，进入文件夹，双击运行 widgets.exe

---

🎨 效果展示

应用界面

组件样式

动画效果

开关组件动画	文本框动画

---

🚀 快速开始

安装配置

详细安装指南请参考：使用指南

CMake 集成

cmake_minimum_required(VERSION 3.28)
project(hello-world)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTOMOC ON)

# Qt 是项目依赖的库，记得导入
find_package(Qt6 REQUIRED COMPONENTS Widgets)

# 引入依赖
include(FetchContent)
FetchContent_Declare(
    creeper-qt
    GIT_REPOSITORY https://github.com/creeper5820/creeper-qt.git
    GIT_TAG main
    GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(creeper-qt)

add_executable(
    ${PROJECT_NAME}
    main.cc
)
target_link_libraries(
    ${PROJECT_NAME}
    Qt6::Widgets
    creeper-qt::widgets
)

代码示例

#include < ... >

auto main(int argc, char* argv[]) -> int {
    using namespace creeper;

    // Qt 运行时初始化
    auto application = new QApplication { argc, argv };

    // 创建主题管理器，可以传入主题包
    auto manager = ThemeManager { kBlueMikuThemePack };

    // 和正常 Qt 一致的使用方式也是 OK 的，这里用声明式的方法示例
    creeper::ShowWindow<MainWindow> {
        mwpro::MinimumSize { 1080, 720 },
        mwpro::Central<FilledCard> {
            capro::ThemeManager { manager },
            capro::Radius { 0 },
            capro::Level { CardLevel::HIGHEST },

            capro::Layout<Row> {
                lnpro::Margin { 0 },
                lnpro::Spacing { 0 },

                lnpro::Item {
                    // 某些自定义组件
                    NavComponent(nav_component_state),
                },
                lnpro::Item<Col> {
                    lnpro::ContentsMargin { { 15, 15, 5, 15 } },
                    lnpro::Item { ListComponent(list_component_state) },
                },
                lnpro::Item<Col> {
                    { 255 },
                    lnpro::ContentsMargin { { 5, 15, 15, 15 } },
                    lnpro::Item<ScrollArea> {
                        scroll::pro::ThemeManager { manager },
                        scroll::pro::HorizontalScrollBarPolicy {
                            Qt::ScrollBarAlwaysOff,
                        },
                        scroll::pro::Item {
                            ViewComponent(view_component_state),
                        },
                    },
                },
            },
            // More Widgets
            // ......
        },
    };

    // 将主题应用到注册过的组件中
    manager.apply_theme();

    return application->exec();
}

---

📋 TODO

• 版本发布

  • 等接口稳定后 release 一个正式版本，开始迭代版本号
  • 接口设计目前基本稳定，多数修改不会影响下游项目

• 组件完善

  • 全组件表格展示
  • 增加更多组件（至 2025.09.18，组件数量仍需扩充）
  • 按钮的禁用效果优化

• 布局容器

  • 增加视图容器（原生容器不可用）
  • 目前已实现无动画的 Flow 布局

• 高级组件

  • 提供日历模组组件
  • 提供设置中心示例

• 构建系统

  • 适配 module 导出
  • 提供开发脚手架

---

📊 项目统计

---

📄 许可证

本项目采用 MIT 开源许可证，详见 LICENSE 文件。

🤝 贡献

欢迎提交 Pull Request 和 Issue！

• 💬 提出问题: GitHub Issues
• 🔀 贡献代码: GitHub Pull Requests
• 📖 阅读文档: 使用指南 | 组件文档