【deepin插件开发活动】多卡片 Dock 插件 CardsDock：剪贴板历史 + 文件中转站一键浮窗

参赛方向：方向四 · 扩展 DDE Shell 的桌面能力（dde-shell-development） 适用环境：Deepin 25（dde-shell / Qt6 / DTK6） 版本：v0.2.1 ｜ 语言：C++ / Qt6 / DTK6

一、作品简介

在 dock 上只占一个图标，点一下（或按快捷键）就浮出一张玻璃质感面板，上面叠着两张常用卡片：

• 剪贴板历史卡片：回顾/回贴最近复制过的文本。
• 文件中转站卡片：把临时要用的文件「暂存」进来，统一拖出，告别反复翻文件夹。

随用随取、用完即隐，不抢焦点、不挡桌面。

🎬 演示视频：【待补充——建议录一段 15–30s：dock 图标 → 唤起浮层 → 切卡片 → 搜索过滤 → 拖文件进出中转站】

二、核心功能

• 双卡片堆叠浮层：同一浮窗内剪贴板历史 + 文件中转站两张卡片切换，节省 dock 空间。
• 全局高斯模糊玻璃面板：整窗 WM 级模糊，内容列表区与面板同款毛玻璃（UI/UX 打磨重点）。
• 实时搜索过滤：两张卡片均有搜索框，输入即筛。
• 多种唤起方式：dock 左键、右键菜单、全局快捷键（Ctrl+Alt+V / Ctrl+Alt+F）、DBus 调用、文件触发。
• 文件中转站：拖入暂存、拖出使用，列表持久化到 ~/.local/share/deepin-cardsdock/transfer/。
• X11 / Wayland 双栈适配：X11 下绕过 layer-shell 手动定位并强制可聚焦窗口类型；Wayland 走 layer-shell + 键盘交互。
• 隐藏策略：失焦不强制隐藏，支持 Esc 关闭、空闲超时与鼠标移出自动隐藏，体验顺手。

三、演示截图（3–5 张）

以下为已截取的实机画面（Deepin 25 X11 VM，KWin 合成后真实画面）。

中转站卡片 玻璃模糊效果

剪贴板历史卡片 玻璃模糊效果

搜索框真实键盘输入验证

输入框中出现了 fcitx 输入法提交的「泡打粉」（由英文 pdf 拼音触发），证明 v0.2.0 修复后搜索框已能真正获得键盘焦点，且中文输入法未被全局键盘抓取破坏。

四、安装与构建

环境要求

• Deepin 25（dde-shell 桌面栈，Qt6 / DTK6）
• 构建依赖：cmake、qt6、dtk6、libdde-shell-dock-dev、libX11-dev

构建

git clone https://gitlink.org.cn/ltree/deepin-cardsdock.git
cd deepin-cardsdock
cmake -B build -S .
cmake --build build -j$(nproc)

部署（dde-shell 插件，拷贝 .so 到 dde-shell 插件目录后重载）

sudo cp build/plugins/org.deepin.ds.dock.cardsdock.so \
     /usr/local/lib/dde-shell/
sudo cp build/plugins/org.deepin.ds.dock.cardsdock.so \
     /usr/local/lib/dde-shell/cardsdock.so
systemctl --user restart dde-shell@DDE.service

注：当前为手工部署路径；后续会补充一键安装脚本 / 打包，进一步满足「可独立构建安装」要求。

五、使用说明

1. 部署并重载 dde-shell 后，dock 右侧出现 CardsDock 图标。
2. 左键图标：唤起浮层（再次左键切换显隐）。
3. 右键图标：菜单直接选择「剪贴板历史 / 文件中转站」。
4. 快捷键：Ctrl+Alt+V 打开剪贴板、Ctrl+Alt+F 打开中转站、Win+Esc 关闭。
5. 中转站：把文件拖进卡片即暂存，拖出即使用；列表自动持久化。

六、开源与协议

• 源码以 GPL-3.0 协议开源（LICENSE 文件已加入仓库）。
• 独立仓库，可单独 cmake 构建与部署。
• 仓库地址：https://gitlink.org.cn/ltree/deepin-cardsdock

七、开发过程：AI 辅助 + deepin Skills

本项目全程借助 AI 编程助手（WorkBuddy） 辅助开发，并遵循 deepin 官方 dde-shell 插件开发规范 / 示例，重点攻克了几个硬核桌面开发难点：

• DDE Shell 插件脚手架：基于 dde-shell applet 机制（D_APPLET_CLASS），实现 dock 图标与浮层解耦。
• X11 键盘焦点根治（技术亮点）：浮窗搜索框一度「完全无法输入」。经真机逐层排查，定位到根因——X11 下 DTK 的 DPlatformWindowHandle 把浮窗标成了 _NET_WM_WINDOW_TYPE_DOCK，而 DOCK 类窗口永远拿不到真实键盘焦点。最终用 Xlib XChangeProperty 把窗口类型强制改写为 _NET_WM_WINDOW_TYPE_DIALOG（既能获焦、又不会被 KWin 全屏最大化），彻底解决。
• 像素级真机验证：借助 KWin ScreenShot2 抓取合成后真实画面，逐像素核对毛玻璃效果与定位。