前言¶
在 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。
