起因#

上一篇文章刚给博客养了只桌面宠物，左下角一只流萤。转头逛到 zhidongli.top，发现右下角还站着一个更”物理”的东西——一块立在杆子上的角色牌，按住能拖着晃，松手自己回弹。

查了一下，是 dsrkafuu/sakana-widget，更早的原型是 itorr/sakana，也就是那个「石蒜模拟器」。既然本站左侧已经有宠物了，右侧放一只立牌正好——一左一右，互不打扰。

一、先看清它有多大、尺寸怎么算#

这种「一个文件丢进去就能用」的形态很适合博客：不必引 CDN、不必配构建、不会在打包时把依赖图搅乱。

理解它的关键是尺寸链。整个 SDK 对外只有一个 size 参数，其余全是推导出来的：

1
_updateSize(e) {
2
  this._imageSize  = e / 1.25;   // 人物立牌图
3
  this._canvasSize = e * 1.5;    // 杆子与摆动挂点所在的 canvas
4
  this._domApp.style.width  = `${e}px`;
5
  this._domApp.style.height = `${e}px`;
6
}

size = 200 时：人物图 160px、canvas 300px、外层盒子 200px。canvas 比盒子还大，是因为杆子和摇摆的挂点需要伸出盒外——那个 200px 的盒子不是它的视觉大小。

摇幅同样是推出来的：

1
_updateLimit(e) {
2
  let t = e / 5;
3
  if (t < 30) t = 30; else if (t > 60) t = 60;
4
  this._limit = { maxR: t, maxY: e / 4, minY: -e / 4 };
5
}

即 maxR = clamp(size / 5, 30, 60)。记住这行，第五节会用到。

二、挂载：沿用桌面宠物那一套#

配置收在 src/config.ts 的 sakanaConfig，客户端脚本在 src/layouts/Layout.astro 末尾。三件事和宠物完全同构：

1. 宿主挂在 Swup 容器之外——#sakana-host 直接放 body，不放进 main，切页时就不会被连根换掉；
2. 单例守卫——window.__sakanaBooted 兜住，防止 Swup 更新 head 时重跑脚本、挂出第二只；
3. 延迟下发——load 之后交给 requestIdleCallback，87 KB 不与首屏抢带宽。

但 SDK 有一个特性让「宿主」这件事比宠物麻烦一点：

1
// mount(host) 内部
2
const r = host.cloneNode(false);
3
r.appendChild(this._domWrapper);
4
host.replaceChild(r, host);   // 宿主元素被换掉了

mount() 会把宿主元素克隆一份替换掉。也就是说 mount 之后，你手上的那个引用已经不是页面上那个节点了。所以后面所有取宿主的操作都不能缓存引用，只能按 id 重新取：

1
function getHost() {
2
  // mount() 会把宿主替换成克隆体，所以每次都要重新取
3
  return document.getElementById("sakana-host");
4
}

好消息是克隆体继承 inline style，所以挂载前设好的宽高与层级不会丢。

另外宿主必须是有确定尺寸的 BFC——autoFit 靠 ResizeObserver 量它的尺寸反推 size，量不到就没有正确的尺寸。所以宽高由脚本按配置注入：

1
const px = sk.size;
2
host.style.width = `${px}px`;
3
host.style.height = `${px}px`;
4
host.style.zIndex = String(sk.zIndex);

三、四处站内适配#

SDK 的默认值这次我基本照抄（与参考站一致），只动了几处站内必须动的：

第 2 条容易被忽略。宿主是个 position: fixed 的 200×200 盒子，即便挂件已经被关掉，盒子还在那里；不设 pointer-events: none，它就会静静地吃掉右下角的点击。而挂件自身（立牌、控制栏）在 SDK 里本来就设了 pointer-events: auto，所以不会有副作用。

第 3 条：这块空间是被挂件实打实占掉的，所以工具栏上抬规则只在挂件真的出现时生效：

1
html[data-sakana="on"] .floating-toolbar-wrapper {
2
  bottom: 15rem;
3
}

data-sakana 这个属性由脚本断言——配置里关掉、窄屏不加载、或者用户自己点了关闭按钮，它都会被撤掉，工具栏随即回到原位。这样就不会出现「关掉挂件后工具栏孤零零悬在半空」的怪状态。

第 4 条：上游点关闭按钮的行为是 unmount()，也就是彻底移除。我不去改 SDK 的行为，只加收尾——卸载后清掉 window.sakanaWidget、撤掉 data-sakana：

1
closeBtn.addEventListener("click", () => {
2
  requestAnimationFrame(() => {
3
    if (!getHost()?.querySelector(".sakana-widget-wrapper")) {
4
      (window as any).sakanaWidget = null;
5
      syncToolbarLift();
6
    }
7
  });
8
});

requestAnimationFrame 是等 SDK 的卸载逻辑跑完再判断，不然会读到卸载前的 DOM。

四、那个坑：切页之后，人物没了，只剩一根杆子#

这是全篇唯一真正花时间的地方。

1
.sakana-widget-img {
2
  background: 50%/cover no-repeat;
3
  pointer-events: auto;
4
  cursor: move;
5
}

1
document.head.appendChild(styleElement);   // 注入一次，永不重注

1
function captureSdkStyle() {
2
  const w = window as any;
3
  if (w.__sakanaStyleEl && document.head.contains(w.__sakanaStyleEl)) return;
4
  const found = Array.from(document.head.querySelectorAll("style")).find((el) =>
5
    (el.textContent || "").includes("sakana-widget-wrapper"),
6
  );
7
  if (found) {
8
    found.setAttribute("data-swup-theme", "sakana-widget");
9
    w.__sakanaStyleEl = found;
10
  }
11
}
12

13
function restoreSdkStyle() {
14
  const w = window as any;
15
  if (!w.__sakanaStyleEl) { captureSdkStyle(); return; }
16
  if (!document.head.contains(w.__sakanaStyleEl)) document.head.appendChild(w.__sakanaStyleEl);
17
}

1
document.addEventListener("swup:page:view", () => {
2
  applyHostBox();
3
  syncToolbarLift();
4
  restoreSdkStyle();
5
});

1
// ❌ let styleEl = null;      —— 脚本被重跑后归零
2
// ✅ window.__sakanaStyleEl   —— 跨越脚本重跑保留

五、关于手感：我差点把摇晃调没#

上面说 SDK 默认值我基本照抄，但中间走过一段弯路，值得记一笔。

第一版我担心”挂件会不会挡住正文”，自作主张加了矮屏降级：屏幕矮的时候把 size 压到 120。结果——摇晃变得非常生硬，像是被硬掰过去的。

道理就在第一节那行公式里：

maxR = clamp(size / 5, 30, 60)，30 是下限。size 120 算出来是 24°，被钳回 30°——也就是说在这个尺寸下，你没法让它摇得更轻，只能摇 30°，而相对这么小的立牌，30° 的摆幅看着就是在”甩”。我原本以为”挂件小一点、动作收敛一点”，实际是反的。

改法只有一句：把矮屏降级删掉，统一 200，同时删掉所有对物理参数的覆盖，全走默认。参考站用的就是这个尺寸，摇晃幅度也就是那个感觉。

结论：想改手感就调 size，别去动别的——摆幅上限、纵向行程（maxY = size / 4）全都是它的派生量。

小结#

• 87 KB 自包含，一个文件丢进 public/lib/ 就能用，零外部请求，不碰构建链；
• 挂载策略与桌面宠物同构：宿主在 Swup 容器外、单例守卫、延迟下发。外加一个 SDK 细节——mount() 会 cloneNode 换掉宿主，所以宿主只能按 id 重新取；
• 真正的坎是一个只在切页发作的 bug：SDK 运行时注入 <head> 的 <style> 会被 @swup/head-plugin 当作”新页面没有的节点”删掉，.sakana-widget-img 的 background: 50%/cover 退回默认，人物图按原始像素从左上角裁进 128px 盒子——正好是透明区。修法是打 data-swup-theme 免删标记 + 切页兜底重挂，而引用的存放位置必须能跨脚本重跑，挂 window，不能挂模块变量；
• 手感只调 size：摆幅上限和纵向行程都是它的派生量，而 30° 是硬下限，尺寸压得太小反而摇得更凶。

回头看，这两次挂件落地（桌面宠物、石蒜立牌）踩的其实是同一类坑：这些 SDK 是给”整页刷新”的传统网页写的，而本站是 Swup 驱动的单页应用。宠物那次是宿主元素被换掉，这次是运行时样式被删掉。以后再引入任何第三方挂件，第一件事都该问一句：它有没有在运行时往 <head> 里塞东西？