deepin-cardsdock — 多卡片 Dock（dde-shell 插件）

基于设计稿（docs/design/index.html，Next-Deepin-Dock 风格）实现的 dde-shell 树外插件。 在 dock 栏放一个图标，用户唤起时把「系统剪贴板」「文件中转站」两张事件卡片以弹层形式叠放切换，与真实系统行为一致。

旧版 dde-shell（Qt6/QML/xmake）实现已挪到 legacy-ddeshell/，不参与本工程构建，仅供参考与回退。

架构

Deepin 25 桌面栈 = dde-shell（QML/Qt6/DTK6），旧 dde-dock（Qt5/DTK5）接口已移除。本插件采用 dde-shell 官方的 dock applet 接入方式：

dde-shell 进程
 └─ dock 面板（org.deepin.ds.dock）
     └─ CardsDockApplet（DAppletDock 基类，dockOrder=27）
         ├─ 图标：package/main.qml（AppletDockItem）+ dockItemInfo()
         └─ 弹层 CardsStack（QWidget 顶层窗口，自管浮窗）
              ├─ ClipboardCard     系统剪贴板（当前内容置顶 + 历史）
              └─ FileTransferCard  文件中转站（暂存 + 拖出传输）

• dock 图标：CardsDockApplet 继承 dde-shell 的 DAppletDock（dock/dappletdock.h，链接 libdde-shell-dock），重写 dockItemInfo()；QML 根 AppletDockItem 用 Applet.* Q_INVOKABLE 桥接。
• 卡片浮窗 CardsStack：无边框置顶窗口，DPlatformWindowHandle（DTK 外观 + 毛玻璃）+ DLayerShellWindow（定位）+ DockMarginHelper（动态边界处理）。
• 动态边界处理 DockMarginHelper（src/dockmarginhelper.*）：与 deepin-widget-toolbar 的 DockMarginHelper.qml（同源于 dde-shell 通知中心 windowMargin）统一边距理念——弹层左/右/下三边距恒等于 contentPadding=10，与屏幕边缘等距；dock 在弹层同屏且位于底部时下边距动态增大为 dock 与屏幕底边重叠 + 10，自动避让任务栏并实时跟随其显隐/换位/换屏/改尺寸；弹层跟随 dock 所在屏幕显示。Wayland 下不追加避让边距（任务栏自身 exclusionZone 由合成器排布可用区域）。
• 系统透明度跟随 SystemOpacity：读 DBus org.deepin.dde.Appearance1 的 Opacity（DConfig 兜底），底色 alpha 跟随。
• 复用框架无关的 clipboardmodel（dataChanged + 1s 轮询双通道）与 filetransfer（入站 + 拖出传输）。

卡片与触发

卡片	唤起方式	行为
系统剪贴板	左键图标 · Ctrl+Alt+V · 右键菜单	当前内容置顶 + 历史列表；点击条目复制回系统剪贴板（双向同步）；支持搜索/清空
文件中转站	左键图标 · Ctrl+Alt+F · 拖文件入图标/卡片	暂存文件；拖出到「可传输窗口」释放才启动真实传输（text/uri-list）；支持搜索/清空

触发规则（已敲定）

• 复制动作静默写入历史，不弹窗，仅用户主动唤起剪贴板时切换。
• 中转站只「暂存 + 发起」，不在本插件内重复实现传输 I/O。
• 拖出修饰键：Shift=移动、Ctrl=复制、Shift+Ctrl=链接。

唤起 / 退出机制

• 唤起：左键图标 togglePopup / 右键菜单 / 全局快捷键 / DBus org.deepin.cardsdock（showClipboard·showTransfer·toggle·close）。
• 退出：① 再按 toggle 快捷键关闭（showClipboard/showTransfer 带 toggle 语义）；② 鼠标移出卡片 8s 自动隐藏；③ Esc 关闭（X11 会话窗口内拦截；Wayland 会话用 Win+Esc 全局键）；④ 8s 空闲超时兜底。

工程结构

CMakeLists.txt             find_package(DDEShell/Dtk6) + find_library(dde-shell-dock)
3rdparty/dde-shell-dock/   dock library 头文件（dappletdock.h / dockiteminfo.h，内置自包含）
src/
  cardsdockapplet.h/.cpp   插件入口（DAppletDock + dockItemInfo + DBus + 快捷键注册）
  cardsstack.h/.cpp        卡片浮窗（分段切换 + 两张卡片 + 拖入接收 + 毛玻璃 + 透明度跟随）
  clipboardcard.h/.cpp     剪贴板卡片
  clipboardmodel.h/.cpp    剪贴板历史（dataChanged + 1s 轮询双通道）
  filetransfercard.h/.cpp  中转站卡片
  filetransfer.h/.cpp      拖拽入站 + 进度
  systemopacity.h/.cpp     系统透明度代理（DBus Appearance1 + DConfig 兜底）
  icons/cardsdock.svg      dock 图标
package/
  main.qml                 AppletDockItem 图标（点击/右键/拖放）
  metadata.json            插件元数据（含 dock 字段）
  cardsdock.svg            图标
resources.qrc              图标资源
cardsdock.sh               全局快捷键脚本（全部 action 走 DBus）
docs/
  设计书-多卡片dock重构.md   设计终稿
  design/                   HTML 设计稿归档
  DEPLOY-DEEPIN25.md       部署手册
legacy-ddeshell/            旧 dde-shell（Qt6/QML/xmake）实现，不参与构建

构建与部署

依赖：dde-shell（含 libdde-shell-dock）、Qt6 Widgets/DBus、DTK6 Widget/Gui/Core。

# dock library 头文件已内置 3rdparty/，若系统缺无版本号符号链接需补：
#   ln -sf /usr/lib/x86_64-linux-gnu/libdde-shell-dock.so.2.0.52 /usr/local/lib/libdde-shell-dock.so

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

部署（Deepin 25 的 /usr 为 OSTree 只读，手工拷到 /usr/local）：

cp build/plugins/org.deepin.ds.dock.cardsdock.so /usr/local/lib/dde-shell/cardsdock.so
cp build/plugins/org.deepin.ds.dock.cardsdock.so /usr/local/lib/dde-shell/org.deepin.ds.dock.cardsdock.so
mkdir -p /usr/local/share/dde-shell/org.deepin.ds.dock.cardsdock
cp package/* /usr/local/share/dde-shell/org.deepin.ds.dock.cardsdock/
systemctl --user restart dde-shell@DDE.service

全局快捷键（经 Keybinding1，脚本 cardsdock.sh 部署到 /usr/local/bin/）：

名称	热键	action
CardsDock 剪贴板	Ctrl+Alt+V	cardsdock.sh clipboard
CardsDock 文件中转站	Ctrl+Alt+F	cardsdock.sh transfer
CardsDock 关闭	Win+Esc	cardsdock.sh close

实施进度

项	内容	状态
插件骨架	DAppletDock 入口 + 元数据 + dock 图标（AppletDockItem）	✅ 已落地
卡片浮窗	CardsStack 玻璃面板 + DLayerShellWindow 定位 + 毛玻璃	✅ 已落地
剪贴板卡片	唤起触发 + 双向同步 + 复制静默入史 + 搜索/清空	✅ 已落地
中转站卡片	拖入入站 + 拖出传输 + 搜索/清空	✅ 已落地
系统透明度跟随	SystemOpacity（DBus Appearance1 + DConfig 兜底）	✅ 已落地
右键菜单	C++ QMenu（独立原生窗口，不被 dock 裁剪）	✅ 已落地
唤起/退出	toggle 语义 + Esc/Win+Esc + 8s 超时 + DBus	✅ 已落地
全局快捷键	Ctrl+Alt+V/F + Win+Esc（Keybinding1）	✅ 已落地
PR #1 合并 来自[https://www.gitlink.org.cn/yxzl666xx]	DAppletDock 迁移 + 透明度 + 文件拖拽 + 自有图标	✅ 已合并

⚠️ 真机为 Wayland 会话时，纯 Esc 单键全局注册被 Keybinding1 拒绝，关闭用 Win+Esc；X11 会话窗口内 Esc 拦截可直接用。

License

代码 MIT；图标来自 deepin-icon-theme（GPL-3.0，源在 docs/design/assets）。