前端小宠物 pet-widget 开发日记#

四种状态#

宠物本质上是一个有限状态机，四个状态来回切换：

所有状态都挂在 body 的 class 上，动画交给 CSS，JS 只负责”什么时候切换状态”。

图片资源#

每张图都是 2048×2048 的透明背景 PNG，一个状态一张：

1
assets/
2
  standing.png   # 站姿
3
  blink.png      # 眨眼瞬间（闭眼）
4
  sitting.png    # 坐姿
5
  lifted.png     # 被拎起

图很大（单张 2~5MB），所以做了预加载 + 失败兜底：启动时用 Promise.all 把所有图先拉一遍，onerror 也 resolve（返回 ok:false），加载失败的图就跳过，不阻塞初始化。

动画全用 CSS#

写轮播级粒子动画太奢侈，这种小宠物用 CSS keyframes 就够，还省 JS 主线程。核心几个：

• petFloat：站立时上下漂浮 + 轻微左右摇摆 + 弹性缩放
• petShake：坐下时的摇头晃脑
• petDrop：松手后的落地回弹（下坠 → 弹起 → 落定）
• petSquash：眨眼时身体压扁一下
• petDangle：被拎起时以头顶为轴心左右摆动
• petNote：坐下时头顶飘出的小音符

外加一个 drop-shadow 投影，宠物就”站”在页面上了。

空闲坐下#

1
function resetIdle() {
2
  clearTimeout(idleTimer);
3
  if (state !== 'standing') return;
4
  idleTimer = setTimeout(function () {
5
    if (state === 'standing' && !document.hidden) enterSitting();
6
  }, cfg.idleTime);
7
}

每次有交互（睡醒、放下、鼠标靠近）都会重置这个计时器。标签页切到后台时不触发坐下，回到前台再重新计时——不然宠物在你看不见的时候偷懒就很出戏。

随机眨眼#

1
var delay = cfg.blinkMin + Math.random() * (cfg.blinkMax - cfg.blinkMin);
2
blinkTimer = setTimeout(blinkNow, delay);

间隔在 2.5s~6.5s 之间随机，避免像秒表一样机械。眨眼瞬间换 blink.png，150ms 后换回站姿；如果眨眼图没加载成功，就降级用 CSS 的 petSquash 压扁一下，体验也不至于断档。

拖动#

拖动这块踩了点坑：

1. 平滑跟随：不直接把元素钉在鼠标上，而是用 requestAnimationFrame 每帧朝目标位置插值 += (target - cur) * 0.32，拖起来有”重力跟随”的黏滞感，而不是生硬地瞬移。
2. 惯性摇摆：记录横向速度，拖动时让身体向运动方向倾斜，停下来还能回弹，手感立刻不一样。
3. 指针捕获：用 stage.setPointerCapture()，防止拖太快时指针跑到元素外面导致 pointerup 丢失、宠物卡在”拎起”状态。
4. 边界钳制：坐标 clamp 在可视区内，不会被甩到屏幕外。

图片切换的淡入淡出#

直接换 src 会”啪”地一下变脸，很生硬。写了个 swapImg(src, fade)：先置 opacity:0，180ms 后再换图并淡入，过渡就自然了。

1. 静态资源放进 public#

把 pet-widget/ 整个目录拷到 public/ 下，这样 Astro 会原样发布为 /pet-widget/...：

1
public/pet-widget/
2
  pet-widget.css
3
  pet-widget.js
4
  assets/*.png

2. 全站布局挂载#

在 src/layouts/Layout.astro 的 </body> 前加入挂载点、样式和脚本：

1
<div id="pet-widget"></div>
2
<link rel="stylesheet" href="/pet-widget/pet-widget.css" is:inline />
3
<script is:inline>
4
  window.PetWidgetConfig = {
5
    size: 200,
6
    idleTime: 5000,   // 测试用 5s，正式改回 30000
7
    dock: 'bottom-right',
8
    assets: {
9
      standing: '/pet-widget/assets/standing.png',
10
      blink:    '/pet-widget/assets/blink.png',
11
      sitting:  '/pet-widget/assets/sitting.png',
12
      lifted:   '/pet-widget/assets/lifted.png'
13
    }
14
  };
15
</script>
16
<script src="/pet-widget/pet-widget.js" is:inline defer></script>

3. is:inline 是关键#

Astro 默认会把 <script> 收集起来打包，插件 is:inline 后脚本会原样输出、不被 Astro 处理。这很重要，因为：

• 配置脚本要在宠物 JS 之前执行，一旦被 Astro 重新排序就可能读到空配置
• 宠物脚本用的是全局状态，不需要被打包成模块

另外挂载点放在 body 里、Swup 的容器之外，页面切换时宠物不会被重新初始化、也不会有动画重放的闪断。