前言¶
在 DSH Desktop 里使用 dsh-whale-widget 小鲸鱼桌宠时，挂件会自行维护位置与吸附逻辑，但右栏展开、折叠或拖动改宽时，桌宠未必会贴着右栏左缘或窗口右缘对齐。若你希望桌宠始终「跟着右侧 Sidebar 走」，又不想改挂件源码或动它的文件，就需要一层只接管定位与吸附的伴生插件。下面介绍 UniMars 维护的 dsh-whale-widget-dock 做什么、怎么装、怎么用。
这是什么¶
dsh-whale-widget-dock 是 dsh-whale-widget 的伴生插件：通过样式与观察器软接管横向定位，让桌宠在右栏展开时右缘紧贴右栏左缘，折叠时右缘紧贴窗口右缘（间距可配），并在右栏拖动改宽时实时跟随。卸载本插件后挂件立刻恢复原样；插件不修改挂件目录下的任何文件。
维护者：UniMars。仓库：https://github.com/UniMars/dsh-whale-widget-dock。社区目录：https://www.skillhub.cn/plugins/UniMars/dsh-whale-widget-dock。当前 package 版本为 0.3.1，许可证 MIT。
核心功能¶
右栏与桌宠位置的对应关系如下（资料中的默认与说明）：
| 右栏状态 | 桌宠位置 |
|---|---|
| 展开 | 右缘紧贴右栏左缘（gap 默认 0，可配） |
| 折叠 | 右缘紧贴窗口右缘（edgeGap 默认 0，可配；负值可再往里压） |
| 右栏拖动改宽 | 实时跟随，不做过渡跳变 |
| 锁定 | 强制保持「右侧吸附」，并压制挂件贴左时的整只镜像翻转 |
其他已核实能力：
- 菜单中在「吸附与翻转」下一行增加 吸附到右栏 开关；取消勾选即解除接管。
- 快捷键：
Ctrl + Alt + L（macOS 为⌘ + Alt + L）。 - 默认
locked: true，锁定状态存于localStorage，刷新与重启后保持。 - 依赖
dsh-whale-widget的.dshwv-root与 DSH 0.2.x 右侧 Sidebar 的data-sidebar-right-panel/data-sidebar-right-open标记；标记缺失时退化为贴窗口右缘，不会报错。
安装与启用¶
官方推荐用仓库内的 PowerShell 安装脚本（不是 dsh plugin add github:… 这类拼接命令）。装完必须完全重启 DSH Desktop（宿主只在启动时收集一次 Web 外壳注入表）。
方式一：脚本（推荐）
pwsh -File .\install.ps1
脚本会：把本目录复制到 %DSH_HOME%\local-plugins\dsh-whale-widget-dock；在 profiles\desktop\node_modules 里建目录联接；在 profiles\desktop\package.json 的 dependencies 与 dsh.profile.bundles 里登记；改动前自动备份 package.json。
卸载：
pwsh -File .\install.ps1 -Uninstall
方式二：手动
- 把本目录放到
%DSH_HOME%\local-plugins\dsh-whale-widget-dock - 在
%DSH_HOME%\profiles\desktop\package.json里增加依赖与 bundle（示例）：
"dependencies": {
"dsh-whale-widget-dock": "link:../../local-plugins/dsh-whale-widget-dock"
},
"dsh": { "profile": { "bundles": [ "…", "dsh-whale-widget-dock" ] } }
- 确保
profiles\desktop\node_modules\dsh-whale-widget-dock能解析到该目录 - 重启 DSH Desktop
典型用法¶
菜单：打开挂件主菜单（菜单按钮 / 右键 / 长按小鲸鱼），在「吸附与翻转」下一行勾选 吸附到右栏；取消勾选则位置控制权交还给挂件。
开发者工具 Console 调参（这一步用于查看或修改间隙与锁定，改完后可调用 refresh() 立即重算）：
// 查看
__dshWhaleDock.config
// 展开时留 6px 间隙、折叠时贴死（0）；负值表示再往里压几个像素
__dshWhaleDock.set({ gap: 6, edgeGap: 0 })
// 解锁 / 上锁
__dshWhaleDock.locked(false)
// 立即重算一次
__dshWhaleDock.refresh()
| 键 | 默认 | 说明 |
|---|---|---|
locked |
true |
锁定右侧吸附；解锁后完全交还给挂件自己 |
gap |
0 |
展开时，桌宠右缘与右栏左缘的间距（px）；允许负值微调 |
edgeGap |
0 |
折叠时，桌宠右缘与窗口右缘的间距（px）；0 = 贴死，允许负值 |
writeWidgetPos |
true |
同步把 localStorage['dshw-pos'] 写成 hAnchor: "right"，让挂件自己的吸附模型也一致 |
持久化键：localStorage['dsh-whale-widget-dock:v1']。想完全恢复原状可 __dshWhaleDock.locked(false)，或卸载插件后清理上述键并把 localStorage['dsh-whale-widget-dock:pos-backup'] 写回 localStorage['dshw-pos']（见 README 排查节）。
适用场景与注意¶
适合已经安装 dsh-whale-widget、且常用 DSH 右侧 Sidebar 的 Desktop 用户：你希望桌宠与右栏联动，而不是单独拖在屏幕一角。
安装前请自行查看仓库源码与 MIT 许可证。插件随当前 DSH Desktop 进程在 Web 外壳中注入运行，权限与宿主一致；仅在你信任维护者与代码的前提下安装。
若重启后桌宠无变化：确认 dsh.profile.bundles 含 dsh-whale-widget-dock 且 node_modules 可解析；Console 里 __dshWhaleDock 为 undefined 通常表示未重启或未进注入表。贴边差几个像素时，桌宠图像可能有透明留白，可用 gap 微调。
结尾¶
dsh-whale-widget-dock 只改小鲸鱼的定位与吸附表现，不改挂件文件；通过菜单或快捷键即可开关「吸附到右栏」，并用 Console API 微调间隙与锁定。详情与 issue 见 GitHub：https://github.com/UniMars/dsh-whale-widget-dock；目录页：https://www.skillhub.cn/plugins/UniMars/dsh-whale-widget-dock。
