Fqzlrのblog

为什么要重构#

博客左下角原本的悬浮音乐播放器是「唱片 + 点击弹出大面板」的结构。功能是够用的，但两个形态之间的视觉关联很弱——唱片在左下角，面板飘在上方，看起来像两个不相干的组件。

参考 Firefly 主题的做法后，我把它重构成了三态一体的 dock：三种形态共享同一棵 DOM 树，唱片本身就是展开形态的一部分，只是位置和周边表面随形态过渡。

三态形态机#

1
type DockShape = "disc" | "pill" | "bar";

形态转移规则（照搬参考实现的约定）：

• 未播放：disc ⇄ bar，点击唱片切换，点击控件外收回唱片；
• 播放中：静置形态由歌词开关决定（开 → pill，关 → disc）；
• 鼠标进入控件任意组件 → 无条件展开 bar；离开 160ms 后收回静置形态；
• 暂停时 pill 收回 bar。

1
/** 播放中静置形态：歌词开关打开为胶囊，关闭为唱片 */
2
function dockRestingShape(): DockShape {
3
  return dockLyricsOn ? "pill" : "disc";
4
}
5

6
// 播放状态变化时同步形态
7
$effect(() => {
8
  if (!playing) {
9
    if (dockShape === "pill") dockShape = "bar";
10
  } else if (dockShape !== "bar" && dockShape !== dockRestingShape()) {
11
    dockShape = dockHover ? "bar" : dockRestingShape();
12
  }
13
});

bar 态的分层表面#

展开形态不是一张大卡片，而是三层独立表面叠出来的：

1
┌──────────────────────┐
2
│ 列表 | 歌词（Tab）     │ ← 面板：dock 上方独立一层
3
│ 封面缩略图 + 当前项高亮 │
4
├──────────────────────┤
5
│  标题                 │ ← 信息层（两侧内缩的卡片）
6
│  艺术家  0:52 ─●─ 4:07│
7
│ (唱片) ⏮ ▶ ⏭ 🔊      │ ← 工具栏胶囊，唱片骑在接缝上
8
└──────────────────────┘

展开/收起的编排是关键：信息层用 grid-template-rows: 0fr → 1fr 过渡高度，工具栏从 scale(0.72) 淡入，面板延迟 120ms 再上浮——三层错峰出现，比整体缩放高级得多。

唱片在三态间的位移也全靠 CSS 过渡：disc 态贴容器左下，pill 态垂直居中进胶囊，bar 态用 bottom: calc(var(--fp-bar-h) - var(--fp-disc) / 2) 让中心正好骑在信息层与工具栏的接缝上。

拖动顺滑：两个实战坑#

1
function onDiscPointerMove(event: PointerEvent): void {
2
  if (!discDragging || event.pointerId !== discPointerId) return;
3
  const dx = event.clientX - discDragStart.px;
4
  const dy = event.clientY - dragStart.py;
5
  if (!discMoved && Math.abs(dx) < 4 && Math.abs(dy) < 4) return;
6
  discMoved = true;
7
  // 拖动中直接写 DOM transform 绕过响应式渲染保证跟手
8
  const next = clampDiscPos(discDragStart.x + dx, discDragStart.y + dy);
9
  if (discEl) {
10
    discEl.style.transform = `translate(${next.x}px, ${next.y}px)`;
11
  }
12
  discPos = next;
13
}

1
dragstart → pointercancel → lostpointercapture

1
<div ondragstart={(e) => e.preventDefault()} ...>
2
  <img draggable="false" ... />

1
&__disc img
2
  -webkit-user-drag: none
3
  user-select: none

歌词开关的互斥联动#

控件上的歌词按钮控制的是控件自身的胶囊歌词，和屏幕上的悬浮歌词条是互斥的——开一个自动关另一个，双向联动且都持久化到 localStorage：

1
function toggleDockLyrics(): void {
2
  dockLyricsOn = !dockLyricsOn;
3
  localStorage.setItem(DOCK_LYRICS_KEY, dockLyricsOn ? "true" : "false");
4
  setFloatingOn(!dockLyricsOn); // 互斥：开此关彼
5
}

胶囊里的文本优先显示当前歌词行，没有活动行时回退到「曲名 - 歌手」。

收尾#

重构完成后：收起是一张会转的唱片，播放中变成「唱片 + 歌词胶囊」，鼠标靠近展开完整控件，移开自动收回；位置可拖动且跨会话记忆；点击外部整体折叠。所有形态共享同一个播放引擎，互斥联动全部落在 UI 层，播放逻辑零侵入。