feat(capture): add window capture functionality and options

Author: DrizzleTime

.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
 
       - name: Install Linux system dependencies
         if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y ninja-build libgl1-mesa-dev
+        run: sudo apt-get update && sudo apt-get install -y ninja-build libgl1-mesa-dev libx11-dev
 
       - name: Set up MSVC
         if: runner.os == 'Windows'

CMakeLists.txt

@@ -21,6 +21,22 @@ endif()
 
 qt_standard_project_setup(REQUIRES 6.8)
 
+add_library(clipit_capture_platform INTERFACE)
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    find_package(X11 QUIET)
+    if(TARGET X11::X11)
+        target_link_libraries(clipit_capture_platform INTERFACE X11::X11)
+        target_compile_definitions(clipit_capture_platform INTERFACE CLIPIT_HAS_X11)
+    endif()
+elseif(WIN32)
+    target_link_libraries(clipit_capture_platform INTERFACE user32)
+elseif(APPLE)
+    find_library(APPLICATION_SERVICES_FRAMEWORK ApplicationServices REQUIRED)
+    target_link_libraries(clipit_capture_platform
+        INTERFACE ${APPLICATION_SERVICES_FRAMEWORK}
+    )
+endif()
+
 qt_add_library(clipit_core STATIC
     src/core/annotation.cpp
     src/core/annotation.h
@@ -79,7 +95,11 @@ target_include_directories(appClipit PRIVATE
     ${CMAKE_CURRENT_SOURCE_DIR}
     ${CMAKE_CURRENT_SOURCE_DIR}/src/app
 )
-target_link_libraries(appClipit PRIVATE clipit_core Qt6::Quick)
+target_link_libraries(appClipit PRIVATE
+    clipit_core
+    clipit_capture_platform
+    Qt6::Quick
+)
 clipit_enable_warnings(appClipit)
 target_compile_definitions(appClipit PRIVATE CLIPIT_VERSION="${PROJECT_VERSION}")
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
@@ -106,7 +126,7 @@ if(BUILD_TESTING)
                 $<TARGET_FILE:appClipit> --help
     )
     set_tests_properties(cli_help_without_display PROPERTIES
-        PASS_REGULAR_EXPRESSION "--region"
+        PASS_REGULAR_EXPRESSION "--window"
     )
     add_test(
         NAME cli_version_without_display
@@ -158,7 +178,7 @@ if(BUILD_TESTING)
             ${CMAKE_CURRENT_SOURCE_DIR}/src/app
         )
         target_link_libraries(tst_screenshotservice
-            PRIVATE clipit_core Qt6::Quick Qt6::Test
+            PRIVATE clipit_core clipit_capture_platform Qt6::Quick Qt6::Test
         )
         add_test(NAME screenshotservice COMMAND tst_screenshotservice)
         set_tests_properties(screenshotservice PROPERTIES

Main.qml

@@ -344,13 +344,14 @@ ApplicationWindow {
 
             Repeater {
                 model: [
+                    { icon: "window", title: qsTr("窗口截图"), note: window.screenshotService.wayland ? qsTr("由系统选择窗口") : qsTr("当前活动窗口"), action: "window" },
                     { icon: "screen", title: qsTr("全屏截图"), note: qsTr("立即捕获"), action: "screen" },
                     { icon: "clock", title: qsTr("延时截图"), note: qsTr("3 / 5 / 10 秒"), action: "delay" }
                 ]
                 delegate: Rectangle {
                     id: actionCard
                     required property var modelData
-                    width: (parent.width - 12) / 2
+                    width: (parent.width - 24) / 3
                     height: parent.height
                     radius: 13
                     color: secondaryMouse.containsMouse ? (window.darkMode ? "#292D36" : "#F9FAFF") : window.panel
@@ -382,7 +383,14 @@ ApplicationWindow {
                         hoverEnabled: true
                         cursorShape: Qt.PointingHandCursor
                         enabled: !window.screenshotService.busy
-                        onClicked: actionCard.modelData.action === "screen" ? window.screenshotService.captureFullscreen(0) : delayPopup.open()
+                        onClicked: {
+                            if (actionCard.modelData.action === "window")
+                                window.screenshotService.captureWindow(0)
+                            else if (actionCard.modelData.action === "screen")
+                                window.screenshotService.captureFullscreen(0)
+                            else
+                                delayPopup.open()
+                        }
                     }
                 }
             }

README.md

@@ -2,7 +2,7 @@
 
 一个以 **Linux Wayland** 为主要使用场景，同时支持 Linux X11、Windows 和 macOS 的轻量截图与标注工具。
 
-Clipit 通过标准的 [XDG Desktop Portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Screenshot.html) 获取屏幕画面，再在应用内完成区域选择、标注、保存和复制。它不依赖 X11 抓屏，也不绑定 GNOME Shell 私有接口。
+Clipit 在 Wayland 下通过标准的 [XDG Desktop Portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Screenshot.html) 获取画面，再在应用内完成区域选择、标注、保存和复制。Wayland 路径不依赖 X11 抓屏，也不绑定 GNOME Shell 私有接口。
 
 ![Clipit 程序截图](https://img.cdn1.vip/i/6a52698f6b18b_1783785871.webp)
 
@@ -21,7 +21,7 @@ Clipit 要解决的是这段缺失的工作流：**在遵守 Wayland 安全模
 
 ## 功能
 
-- 区域截图、全屏截图和延时截图
+- 区域截图、窗口截图、全屏截图和延时截图
 - 矩形、箭头、自由画笔和单行文字
 - 模糊与马赛克隐私处理
 - 预设色板与屏幕像素取色
@@ -39,19 +39,20 @@ Clipit 要解决的是这段缺失的工作流：**在遵守 Wayland 安全模
 | 平台 | 截图方式 | 当前状态 |
 | --- | --- | --- |
 | GNOME / KDE Wayland | XDG Desktop Portal | 主要支持目标 |
-| Linux X11 | Qt `QScreen::grabWindow()` | 可用 |
-| Windows | Qt `QScreen::grabWindow()` | 基础支持 |
-| macOS | Qt `QScreen::grabWindow()` | 基础支持，需要录屏权限 |
+| Linux X11 | X11 活动窗口查询 + Qt `QScreen::grabWindow()` | 可用 |
+| Windows | Win32 活动窗口查询 + Qt `QScreen::grabWindow()` | 基础支持 |
+| macOS | Qt + Core Graphics | 基础支持，需要录屏权限 |
 
-Wayland 下，portal 负责向 Clipit 交付一帧完整屏幕画面，区域选择和标注由 Clipit 自己完成。首次使用或受沙箱策略影响时，系统仍可能显示授权界面；这是 Wayland 安全模型的一部分，应用无法绕过。
+Wayland 下，portal 负责向 Clipit 交付截图。区域截图仍先获取完整屏幕，再由 Clipit 完成框选和标注。窗口截图优先请求 portal v3 的 `Active Window` 目标；如果系统只提供窗口选择或旧版交互接口，会显示系统选择界面。首次使用或受沙箱策略影响时，系统也可能显示授权界面；这是 Wayland 安全模型的一部分，应用无法绕过。
 
 ### 跨平台设计
 
 Clipit 使用 C++、Qt 6 和 QML 开发。主界面、区域选择、标注、PNG 保存与剪贴板等核心逻辑由各平台共用，平台差异集中在“如何安全地取得屏幕画面”这一层：
 
-- **Linux Wayland**：通过标准 XDG Desktop Portal 请求屏幕画面，兼容采用 portal 的 GNOME、KDE 等桌面环境；
-- **Linux X11、Windows 和 macOS**：通过 Qt 的跨平台屏幕接口获取主屏幕画面；
-- **macOS**：沿用系统录屏权限机制，用户需要在首次使用时授权。
+- **Linux Wayland**：通过标准 XDG Desktop Portal 请求屏幕或窗口画面，兼容采用 portal 的 GNOME、KDE 等桌面环境；
+- **Linux X11**：通过 X11 查询活动窗口，再由 Qt 获取窗口画面；
+- **Windows**：通过 Win32 查询活动窗口，再由 Qt 获取窗口画面；
+- **macOS**：通过 Core Graphics 查询并获取最前方窗口画面，沿用系统录屏权限机制，用户需要在首次使用时授权。
 
 这种方式不要求为每个平台重新实现整套编辑器，也避免把 Wayland 支持绑定到某个桌面环境的私有接口。相同的截图一旦交给 Clipit，后续框选、标注、保存和复制行为保持一致。
 
@@ -62,6 +63,7 @@ Clipit 使用 C++、Qt 6 和 QML 开发。主界面、区域选择、标注、PN
 - Qt 6.8 或更高版本
 - Qt Quick
 - Linux：Qt DBus、`xdg-desktop-portal` 和当前桌面对应的 portal 后端
+- Linux X11 窗口截图：构建时需要 X11 开发库；未找到时仍可构建，但不包含 X11 窗口截图
 - Wayland 命令行模式：`wl-clipboard`，用于在 Clipit 退出后继续保留剪贴板内容
 
 GNOME 通常使用 `xdg-desktop-portal-gnome`，KDE Plasma 通常使用 `xdg-desktop-portal-kde`。
@@ -100,19 +102,25 @@ ctest --test-dir build/release --output-on-failure
 # 区域截图
 ./build/release/appClipit --region
 
+# 窗口截图
+./build/release/appClipit --window
+
 # 全屏截图
 ./build/release/appClipit --fullscreen
 
 # 延时 3 秒后全屏截图
 ./build/release/appClipit --fullscreen --delay 3
 ```
 
-短参数分别为 `-r`、`-f` 和 `-d`。`--region` 与 `--fullscreen` 互斥，延时范围为 0–3600 秒。
+短参数分别为 `-r`、`-w`、`-f` 和 `-d`。`--region`、`--window` 与 `--fullscreen` 互斥，三种截图模式都可以与 `--delay` 组合，延时范围为 0–3600 秒。
+
+`--window` 在 X11、Windows 和 macOS 下截取当前活动窗口。Wayland 下优先截取活动窗口；portal 不支持该目标时会打开系统界面，由用户选择窗口。
 
 Clipit 暂不自行注册全局快捷键。可以在 GNOME 的“设置 → 键盘 → 查看及自定义快捷键 → 自定义快捷键”中绑定以下命令，路径需要替换为可执行文件的实际绝对路径：
 
 ```text
 /home/user/apps/Clipit/appClipit --region
+/home/user/apps/Clipit/appClipit --window
 /home/user/apps/Clipit/appClipit --fullscreen
 ```
 
@@ -130,21 +138,21 @@ Clipit 暂不自行注册全局快捷键。可以在 GNOME 的“设置 → 键
 
 Clipit 针对不同环境选择不同的抓屏后端，但复用同一套区域选择和标注流程：
 
-1. `PortalScreenCaptureBackend` 在 Wayland 下通过 `org.freedesktop.portal.Screenshot` 请求屏幕画面；`QtScreenCaptureBackend` 在其他平台通过 Qt 获取画面。
+1. `PortalScreenCaptureBackend` 在 Wayland 下通过 `org.freedesktop.portal.Screenshot` 请求屏幕或窗口画面；`QtScreenCaptureBackend` 在其他平台查询活动窗口并通过平台接口获取画面。
 2. `CaptureOverlay.qml` 在静态画面上完成区域选择与标注。
 3. `ScreenshotService` 管理截图状态，`AnnotationRenderer` 合成最终图片，`ScreenshotStorage` 以原子方式保存 PNG。
 
-程序有三种启动模式：完整 GUI、仅区域截图和仅全屏截图。全屏命令模式不会加载 QML 界面，适合快捷键或脚本调用。
+程序有四种启动模式：完整 GUI、仅区域截图、仅窗口截图和仅全屏截图。窗口与全屏命令模式不会加载 QML 界面，适合快捷键或脚本调用。
 
 项目将可独立测试的图片逻辑放在 `src/core/`，将 portal、Qt 抓屏和剪贴板实现放在 `src/platform/`。详细模块边界和扩展方式见 [架构说明](docs/architecture.md)。提交代码前请阅读 [贡献指南](CONTRIBUTING.md)。
 
 ## 当前限制
 
-- 非 Wayland 平台目前只捕获主屏幕，尚不支持多显示器联合框选。
+- 非 Wayland 平台的全屏与区域模式目前只捕获主屏幕，尚不支持多显示器联合框选。
 - 尚未接入 Wayland `GlobalShortcuts` portal，需要通过桌面设置绑定快捷键。
 - 文字标注目前只支持单行输入。
 - 模糊工具的编辑预览是视觉近似，最终 PNG 会执行实际模糊处理。
-- 尚无窗口自动识别、OCR、托盘和持久化截图历史。
+- 尚无 OCR、托盘和持久化截图历史。
 - macOS 首次截图需要在系统设置中授予录屏权限。
 
 ## 参与开发

components/Glyph.qml

@@ -42,6 +42,11 @@ Item {
             } else if (root.name === "screen") {
                 c.strokeRect(3, 4, 18, 13)
                 c.beginPath(); c.moveTo(9, 21); c.lineTo(15, 21); c.moveTo(12, 17); c.lineTo(12, 21); c.stroke()
+            } else if (root.name === "window") {
+                c.strokeRect(3, 4, 18, 16)
+                c.beginPath(); c.moveTo(3, 8); c.lineTo(21, 8); c.stroke()
+                c.beginPath(); c.arc(6, 6, 0.7, 0, Math.PI * 2); c.fill()
+                c.beginPath(); c.arc(9, 6, 0.7, 0, Math.PI * 2); c.fill()
             } else if (root.name === "clock") {
                 c.beginPath(); c.arc(12, 12, 8.5, 0, Math.PI * 2); c.stroke()
                 c.beginPath(); c.moveTo(12, 7); c.lineTo(12, 12); c.lineTo(15.5, 14); c.stroke()

docs/architecture.md

@@ -2,7 +2,7 @@
 
 ## 目标
 
-Clipit 的核心流程是获取屏幕画面、选择区域、应用标注、保存图片和写入剪贴板。平台差异主要存在于屏幕画面的获取方式，因此架构只对抓屏后端和可独立测试的图片处理建立边界。
+Clipit 的核心流程是获取屏幕或窗口画面、选择区域、应用标注、保存图片和写入剪贴板。平台差异主要存在于画面的获取方式，因此架构只对抓屏后端和可独立测试的图片处理建立边界。
 
 ## 模块关系
 
@@ -23,7 +23,7 @@ ScreenshotService（流程与状态）
 
 `ScreenshotService` 是 QML 与 C++ 的边界，负责：
 
-- 接收区域、全屏、延时和取消命令；
+- 接收区域、窗口、全屏、延时和取消命令；
 - 驱动抓屏后端；
 - 保存待编辑图片并通知 QML 打开选区窗口；
 - 将标注数据交给解析器和渲染器；
@@ -37,19 +37,19 @@ ScreenshotService（流程与状态）
 ```text
 Idle → Delaying → Capturing → Selecting → Saving → Idle
                      │                         │
-                     └──── Fullscreen ─────────┘
+                     └──── Window / Fullscreen ┘
 ```
 
 取消或失败会清理临时选区图片并回到 `Idle`。
 
 ### 抓屏后端
 
-`ScreenCaptureBackend` 只负责产生一张完整的原始屏幕图片：
+`ScreenCaptureBackend` 接收 `Screen` 或 `ActiveWindow` 目标，只负责产生对应的原始图片：
 
-- `PortalScreenCaptureBackend` 实现 XDG Desktop Portal 的异步请求、取消、超时和服务可用性监听；
-- `QtScreenCaptureBackend` 使用 `QScreen::grabWindow()`，用于 X11、Windows 和 macOS。
+- `PortalScreenCaptureBackend` 实现 XDG Desktop Portal 的异步请求、目标能力判断、取消、超时和服务可用性监听；
+- `QtScreenCaptureBackend` 在 X11 和 Windows 下查询活动窗口后调用 `QScreen::grabWindow()`，在 macOS 下使用 Core Graphics。
 
-区域选择不是抓屏后端的职责。所有后端返回原始画面后，都复用同一个选区和标注流程。
+区域选择不是抓屏后端的职责。区域模式要求后端返回完整屏幕，再进入统一的选区和标注流程；窗口与全屏模式直接保存后端图片。
 
 ### 标注模型与渲染
 
@@ -75,7 +75,7 @@ QML Canvas 只提供编辑预览，最终 PNG 以 `AnnotationRenderer` 的结果
 
 新增抓屏方式时：
 
-1. 实现 `ScreenCaptureBackend` 的 `available()`、`capture()` 和 `cancel()`。
+1. 实现 `ScreenCaptureBackend` 的 `available()`、`capture(CaptureTarget)` 和 `cancel()`。
 2. 正确发出 `captured`、`canceled` 或 `failed` 终态信号。
 3. 在组合入口中按平台选择后端。
 4. 使用假后端测试控制器状态，不要求 CI 连接真实桌面服务。

src/app/applicationoptions.cpp

@@ -15,6 +15,9 @@ void configureParser(QCommandLineParser &parser)
     parser.addOption(QCommandLineOption(
         {QStringLiteral("r"), QStringLiteral("region")},
         QStringLiteral("直接开始区域截图，只显示框选层。")));
+    parser.addOption(QCommandLineOption(
+        {QStringLiteral("w"), QStringLiteral("window")},
+        QStringLiteral("开始窗口截图，不启动 Clipit 主窗口。")));
     parser.addOption(QCommandLineOption(
         {QStringLiteral("f"), QStringLiteral("fullscreen")},
         QStringLiteral("直接进行全屏截图，不启动 Clipit 主窗口。")));
@@ -54,20 +57,26 @@ ApplicationOptionsParseResult parseApplicationOptions(const QStringList &argumen
     }
 
     const bool region = parser.isSet(QStringLiteral("region"));
+    const bool window = parser.isSet(QStringLiteral("window"));
     const bool fullscreen = parser.isSet(QStringLiteral("fullscreen"));
-    if (region && fullscreen) {
-        result.error = QStringLiteral("--region 与 --fullscreen 不能同时使用");
+    const int captureModeCount = static_cast<int>(region) + static_cast<int>(window)
+                                 + static_cast<int>(fullscreen);
+    if (captureModeCount > 1) {
+        result.error = QStringLiteral("--region、--window 与 --fullscreen 不能同时使用");
         return result;
     }
 
     if (region)
         result.options.mode = LaunchMode::RegionCapture;
+    else if (window)
+        result.options.mode = LaunchMode::WindowCapture;
     else if (fullscreen)
         result.options.mode = LaunchMode::FullscreenCapture;
 
     if (parser.isSet(QStringLiteral("delay"))) {
-        if (!region && !fullscreen) {
-            result.error = QStringLiteral("--delay 只能与 --region 或 --fullscreen 一起使用");
+        if (captureModeCount == 0) {
+            result.error = QStringLiteral(
+                "--delay 只能与 --region、--window 或 --fullscreen 一起使用");
             return result;
         }
 

src/app/applicationoptions.h

@@ -8,6 +8,7 @@
 enum class LaunchMode {
     Gui,
     RegionCapture,
+    WindowCapture,
     FullscreenCapture,
     Help,
     Version,

src/app/main.cpp

@@ -90,6 +90,8 @@ int runCaptureCommand(QGuiApplication &app, const ApplicationOptions &options)
     QTimer::singleShot(0, &screenshotService, [&screenshotService, options]() {
         if (options.mode == LaunchMode::RegionCapture)
             screenshotService.captureRegion(options.delaySeconds);
+        else if (options.mode == LaunchMode::WindowCapture)
+            screenshotService.captureWindow(options.delaySeconds);
         else
             screenshotService.captureFullscreen(options.delaySeconds);
     });
@@ -147,13 +149,15 @@ int main(int argc, char *argv[])
                             << QCoreApplication::applicationVersion() << Qt::endl;
         return 0;
     case LaunchMode::RegionCapture:
+    case LaunchMode::WindowCapture:
     case LaunchMode::FullscreenCapture:
     case LaunchMode::Gui:
         break;
     }
 
     switch (parsed.options.mode) {
     case LaunchMode::RegionCapture:
+    case LaunchMode::WindowCapture:
     case LaunchMode::FullscreenCapture:
         return runCaptureCommand(app, parsed.options);
     case LaunchMode::Gui:

src/app/screenshotservice.cpp

@@ -111,6 +111,11 @@ void ScreenshotService::captureRegion(int delaySeconds)
     startCapture(Mode::Region, delaySeconds);
 }
 
+void ScreenshotService::captureWindow(int delaySeconds)
+{
+    startCapture(Mode::Window, delaySeconds);
+}
+
 void ScreenshotService::captureFullscreen(int delaySeconds)
 {
     startCapture(Mode::Fullscreen, delaySeconds);
@@ -143,7 +148,9 @@ void ScreenshotService::performCapture()
     if (m_state != CaptureState::Delaying && m_state != CaptureState::Capturing)
         return;
     setState(CaptureState::Capturing);
-    m_backend->capture();
+    const auto target = m_mode == Mode::Window ? Clipit::CaptureTarget::ActiveWindow
+                                               : Clipit::CaptureTarget::Screen;
+    m_backend->capture(target);
 }
 
 void ScreenshotService::handleCapturedImage(const QImage &image)