# ukui-quick

**Repository Path**: r0cking/ukui-quick

## Basic Information

- **Project Name**: ukui-quick
- **Description**: ukui-quick是一个基于Qt Quick 2.0的功能集合，提供了在ukui上开发Qml应用所需要的接口和功能模块。
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: upstream
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 40
- **Created**: 2026-09-19
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ukui-quick

ukui-quick 是面向 UKUI 桌面环境的 Qt Quick 组件与基础设施集合。它既提供可直接在 QML 中使用的界面组件，也提供窗口系统、主题、桌面插件和实时缩略图等平台能力。

项目同时支持 Qt 5/Qt 6 和 X11/Wayland。工作区、输出管理、窗口缩略图等能力依赖当前 UKUI 会话及合成器支持，使用时应检查对应接口的可用状态。

## 主要特性

- **UKUI 风格组件**：背景、文本、按钮、图标、菜单、工具提示、搜索框、滑块和窗口组件，可自动跟随系统主题。
- **图标与动画**：支持主题图标、应用图标适配、圆角与统一底板、角标、静态回退，以及 Lottie JSON/dotLottie 动画。
- **异步 Lottie 运行时**：支持播放、循环、倍速、逐帧控制、隐藏时播放策略和 dotLottie 主题切换；加载与栅格化在后台执行，并可直接用于 `LottieItem` 或 `Icon`。
- **高性能视觉效果**：提供基于 Qt Quick Scene Graph 的 `ShadowedRectangle`、`ShadowedTexture`、`GradientBorderItem` 和窗口模糊组件。
- **桌面平台集成**：通过 `GlobalTheme`、`Settings`、`AppLauncher`、`WindowManager` 等入口提供主题、设置、应用启动、窗口控制、启动反馈、屏幕区域、DBus 和保活协议等能力。
- **工作区与输出管理**：支持创建、删除、重命名、排序和激活工作区；可查询主输出、显示模式、位置、缩放、旋转以及电源、亮度、色温能力。
- **X11/Wayland 统一接口**：上层可通过统一的窗口管理 API 使用激活、最小化、最大化、窗口所在工作区和主输出等能力。
- **桌面插件框架**：支持 Widget、Container、Island 的组合式结构，以及插件发现、生命周期、独立 QML 上下文、配置管理和国际化。
- **插件能力桥接**：插件或宿主可通过 `WidgetFeatureProvider` 注册领域能力，由 QML 中的 `WidgetBridge` 按 key 查询。
- **实时缩略图**：支持 X11/Wayland 窗口缩略图、Wayland 工作区缩略图，以及基于 MPRIS 的音视频预览与控制。

## 模块

| 目录 | 使用入口 | 主要内容 |
| --- | --- | --- |
| [`core/`](core/) | CMake `ukui-quick::core` | 公共类型、边距类型、共享 QML Engine/View/Component |
| [`items/`](items/) | QML `org.ukui.quick.items 1.0` | UKUI 基础控件、图标、Lottie、菜单、窗口、模糊和 Scene Graph 特效 |
| [`platform/`](platform/) | QML `org.ukui.quick.platform 1.0`；CMake `ukui-quick::platform` | QML 主题、设置、应用启动和窗口/工作区入口；C++ 输出管理及 X11/Wayland 平台 API |
| [`framework/`](framework/) | CMake `ukui-quick::framework` | Widget/Container/Island 插件模型、配置、加载器和 feature bridge |
| [`modules/window-thumbnail/`](modules/window-thumbnail/) | QML `org.ukui.windowThumbnail 1.0` | 窗口与工作区实时预览、MPRIS 媒体预览 |

## 快速开始

### 在 QML 中使用

安装 QML 插件后，按 URI 导入所需模块：

```qml
import QtQuick 2.15
import org.ukui.quick.items 1.0
import org.ukui.quick.platform 1.0

Item {
    width: 320
    height: 120

    LottieItem {
        id: loadingAnimation
        width: 48
        height: 48
        source: "qrc:/animations/loading.lottie"
        Lottie.playing: true
        Lottie.loop: true
    }

    SearchLineEdit {
        anchors.left: loadingAnimation.right
        anchors.leftMargin: 16
        width: 240
        height: 36
        placeholderText: qsTr("Search")
        searchIcon.source: "search-symbolic"
        enableContextMenu: true
    }
}
```

`LottieItem.source` 支持本地路径、相对 QML 文件的路径和 `qrc:` URL。`Icon` 也可直接使用 `.json`、`.lottie` 或 `*-motion` 动画源，并通过 `fallbackSource` 设置静态回退图标。

窗口与工作区预览使用独立模块：

```qml
import QtQuick 2.12
import org.ukui.windowThumbnail 1.0

WindowThumbnail {
    width: 320
    height: 180
    winId: targetWindowId
}
```

### 在 C++ 中使用

安装开发文件后，可按组件查找并链接导出的 CMake target：

```cmake
find_package(ukui-quick REQUIRED COMPONENTS core platform framework)

target_link_libraries(my-application
    PRIVATE
        ukui-quick::core
        ukui-quick::platform
        ukui-quick::framework
)
```

`items` 和 `window-thumbnail` 主要作为 QML 插件使用；`core`、`platform` 和 `framework` 同时提供已安装的 C++ 头文件与 CMake package。

## Widget 插件框架

框架以四个概念组织桌面插件：

- `Widget`：插件的元数据、配置和生命周期对象。
- `WidgetContainer`：管理子 Widget 的组合容器。
- `Island` / `IslandView`：承载主容器的应用窗口。
- `Config`：支持树形 JSON、局部配置与插件全局配置的统一接口。

一个最小 Widget 包如下：

```text
org.ukui.example/
├── metadata.json
├── translations/
│   └── org.ukui.example_zh_CN.qm
└── ui/
    └── main.qml
```

最小 `metadata.json` 示例：

```json
{
  "Id": "org.ukui.example",
  "Name": "Example Widget",
  "Version": "1.0",
  "ShowIn": "Panel,SideBar",
  "Contents": {
    "Main": "ui/main.qml",
    "I18n": "translations/org.ukui.example",
    "Config": "LocalOnly"
  }
}
```

Widget 包目录名应与 `Id` 一致，`Contents.Main` 指向 QML 入口。`ShowIn` 支持 `Panel`、`SideBar`、`Desktop`、`TaskManager`、`Shortcut`、`Wallpaper`、`DesktopView`、`Search` 和 `All`；其中 `All` 只包含前五种常规宿主类型，`Wallpaper`、`DesktopView` 和 `Search` 需要显式声明。插件还可在 `Contents` 中声明 `Plugin`、`PluginVersion` 与 `PluginPreload`，通过可选的 C++ 动态库提供菜单动作或 feature provider；使用 `Plugin` 时应同时提供 `PluginVersion`。

默认 Widget 搜索位置包括：

- `:/ukui/widgets`
- `~/.local/share/ukui/widgets`
- `/usr/share/ukui/widgets`
- `/opt/system/resource/ukui/ukui/widgets`

也可以通过 `WidgetLoader::addWidgetSearchPath()` 在运行时增加搜索目录。框架与 Widget 包示例位于 [`framework/test/`](framework/test/)，feature bridge 说明位于 [`framework/doc/widget-bridge-feature.qdoc`](framework/doc/widget-bridge-feature.qdoc)。

## 构建

构建环境需要 CMake 3.16 或更高版本、支持 C++20 的编译器，以及对应 Qt 5/Qt 6 开发包。完整构建还依赖 KDE Frameworks/ECM、Wayland 协议、gsettings-qt、QtXdg、ThorVG、PipeWire、X11/XCB、EGL/GLX 等组件；不同发行版的软件包名称可能不同。

```bash
cmake -S . -B build
cmake --build build -j$(nproc)
```

需要安装到系统时：

```bash
sudo cmake --install build
```

### 测试

```bash
cmake -S . -B build \
    -DBUILD_TEST=ON \
    -DBUILD_INTERACTIVE_TESTS=OFF \
    -DUKUI_QUICK_ENABLE_COVERAGE=OFF
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure
```

常用配置项：

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `BUILD_TEST` | `OFF` | 构建并注册自动测试 |
| `BUILD_INTERACTIVE_TESTS` | `ON` | `BUILD_TEST=ON` 时构建交互式演示程序 |
| `UKUI_QUICK_ENABLE_COVERAGE` | `ON` | `BUILD_TEST=ON` 时为测试目标启用 GCC coverage |

交互式示例主要位于 [`platform/test/`](platform/test/)、[`framework/test/`](framework/test/) 和 [`modules/window-thumbnail/core/test/`](modules/window-thumbnail/core/test/)。

## 项目结构

```text
ukui-quick/
├── core/                       # 公共 C++ 类型与共享 QML 引擎
├── items/                      # org.ukui.quick.items QML 插件
├── platform/                   # UKUI 平台 API 与 X11/Wayland 后端
├── framework/                  # 桌面 Widget 插件框架
├── modules/
│   └── window-thumbnail/       # 窗口、工作区和媒体缩略图
└── cmake-extend/               # CMake/QDoc 辅助模块
```

自动测试与被测模块放在一起，主要位于 `*/autotest/`；QDoc 源码位于各模块的 `doc/` 目录。

## 文档与示例

- [`items/doc/ukui-quick-item.qdoc`](items/doc/ukui-quick-item.qdoc)：Items 模块与 QML 类型索引
- [`platform/doc/ukui-quick-platform.qdoc`](platform/doc/ukui-quick-platform.qdoc)：平台能力概览
- [`framework/doc/ukui-quick-framework.qdoc`](framework/doc/ukui-quick-framework.qdoc)：插件框架架构
- [`framework/test/org.ukui.testWidget/`](framework/test/org.ukui.testWidget/)：Widget 包与可选 C++ 插件示例

## 参与贡献

欢迎通过 [Gitee Issues](https://gitee.com/openkylin/ukui-quick/issues) 报告问题或提交建议。提交代码时请尽量按模块拆分改动，并在合并请求中写明构建与测试命令；涉及可见 QML/UI 变化时请附截图或短视频。

## 许可证

本项目依据 [`GPL-3.0-or-later`](LICENSE) 发布。