在🔌按钮上显示待更新插件数量徽章——复用仪表盘缓存而非重复维护状态

---

先说说背景

最近有个客户提了个需求：“我在跨站更新检查之后，能不能在每个站点列表里直接看到还有多少插件待更新？”

视觉上答案很直接——在🔌插件按钮右上角加个小红点徽章，就像未读通知计数那样。设计上很好搞定。真正的难点在于：数据从哪来。

我们完全可以搞一个新的 API 端点，再加个缓存专门存“每个站点的待更新数量”。但那样做就等于重复维护两份状态了——而我们已有的缓存里其实已经知道这些数据。

最后决定：走现有的缓存。下面说说这个决策背后的考量。

复用仪表盘缓存作为数据源

先交代一下背景。我们之前写过一篇关于跨站更新仪表盘的文章（标题是《用缓存优先设计干掉 24.5 秒的空白等待》），那个仪表盘本身就已经把每个站点的待更新插件存在一个叫 _updatesDashState 的 localStorage 状态里了。

它的数据结构长这样：

_updatesDashState = {
  sites: [
    {
      site_id: "abc...",
      plugins: [{...}, {...}, {...}]
    },
    {
      site_id: "def...",
      plugins: [...]
    },
  ],
  total_pending_count: 12,
  loadedAt: 1748600000000,
}

看到没？按 site_id 查一下，取 plugins.length，徽章的数字就有了。不需要新 API，不需要新缓存。

驱动跨站仪表盘的数据，同时也是驱动站点列表徽章的数据。这个设计的好处是静悄悄的，但很实在：

• 当维护运行导致 _updatesDashState 失效时，徽章自动消失（不需要写任何同步代码）
• TTL（最初是7天，后来扩展到30天并支持部分失效）直接从现有设计继承过来
• 徽章和底层计数永远不会出现不一致——因为没有第二份副本会跑偏

说实话，每次看到新 UI 元素，总有一种冲动想给它配个新端点。我们后来定了个规矩：如果现有状态能回答这个问题，就别再加东西了。

挂徽章——逻辑统一到 helper 里

列表视图和网格视图都需要在🔌按钮上显示同样的徽章，所以逻辑统一放在 helper 里。

function _getPendingPluginCountForSite(siteId) {
  // null = 未检查（不显示徽章）；数字 = 实际待更新数量
  const entry = _updatesDashState.sites.find(s => s.site_id === siteId);
  return entry ? entry.plugins.length : null;
}

function _attachPendingPluginCountBadge(pluginsBtn, siteId) {
  const count = _getPendingPluginCountForSite(siteId);
  if (count === null || count === 0) return; // 减少视觉噪音

  const display = count > 99 ? '99+' : String(count);
  const badge = document.createElement('span');
  badge.className = 'plugin-count-badge';
  badge.textContent = display;
  badge.title = _formatPendingPluginCountTooltip(count);
  pluginsBtn.appendChild(badge);
}

有个小细节容易忽略：按钮本身需要设置 position: relative;，否则绝对定位的徽章会飞到父元素外面去。不加这个，徽章就会跑到屏幕角落里，那画面太美不敢看。

阈值设计——减少视觉噪音

如果每个站点都显示徽章——包括“待更新为0”和“从未检查过”的——那站点列表就变成徽章海了。我们做了两个过滤：

• 不显示 0：健康的站点没有徽章。对于清单视图来说，暴露危险信号比暴露安心信号更有意义
• 不显示“未检查”：返回 null，不挂徽章。“我不知道数量”和“数量是0”是两码事，UI 应该保留这个区别

对于三位数的计数，布局会崩，所以必须做上限处理。我们用 99+ 而不是 100+——这样能保持各行的徽章宽度一致，而且这个约定读者从 GitHub 的通知计数器那里已经熟悉了。

单站检查也能更新徽章

只从跨站仪表盘拉数据会漏掉一种情况：“我点击了某个站点的🔌，进去看了看，然后希望徽章能更新。”

客户的诉求是“两种路径都应该刷新徽章”，所以单站检查也要写回同一个缓存。

function _updatePendingPluginCacheForSite(site, plugins) {
  // 从 /api/site_plugins 中只保留“有可用更新”的——排除 must-use 和 dropin
  const pending = plugins.filter(
    p => p.update === 'available' && p.status !== 'must-use' && p.status !== 'dropin'
  );
  const sites = _updatesDashState.sites;
  const idx = sites.findIndex(s => s.site_id === site._id);

  if (pending.length === 0 && idx >= 0) {
    sites.splice(idx, 1); // 当计数归零时，完全删除该条目
  } else if (pending.length > 0) {
    const entry = { site_id: site._id, plugins: pending };
    if (idx >= 0) sites[idx] = entry;
    else sites.push(entry);
  }

  _updatesDashState.total_pending_count = sites.reduce(
    (sum, s) => sum + s.plugins.length, 0
  );
  _saveUpdatesDashStateToLocalStorage();
  filterSites(); // 立即重新渲染站点列表
}

这里 must-use 和 dropin 的排除很重要——那些插件不走标准的 WordPress 更新流程，如果把它们算进去，就会出现“徽章显示有更新，但更新按钮点不了”的 bug。

最后的 filterSites() 会立刻重新渲染站点列表，所以用户在关闭弹窗之前就能看到新的计数。这种“嗯，它生效了”的即时反馈，让整个交互感觉特别扎实。

学到的教训——“如果现有状态能回答，就别再加东西”

三个可以带走的原则：

1. 新的 UI 元素不一定需要新的数据源。 徽章显示的是“待更新数量”，但这个数量跨站仪表盘已经知道了。在加新 API 或新缓存之前，先检查一下现有状态能不能回答这个问题。如果能，就别再加——你能省掉一堆同步代码和状态漂移的风险。

2. 把噪音削减表达为阈值。 隐藏零和未检查状态，意味着“有徽章 = 需要关注”。如果每个站点都显示徽章，那就变成了背景噪音，反而失去了警示意义。

3. 让两条写入路径都汇聚到同一个缓存。 无论用户是通过跨站仪表盘更新，还是通过单站检查更新，都写入同一个缓存。这样，“我喜欢用仪表盘”和“我喜欢逐个站点检查”两种工作流都能得到正确的徽章。

一个站点列表的徽章看起来是个小功能，但底层真正值钱的教训是：能不新增状态就不新增，选择有意义的阈值，以及让更新路径汇聚。下次再需要加个小功能的时候，最省钱的做法就是问一句：这个答案是不是已经在现有的某个地方了？

---

后续问题

后来还冒出来一个问题：当维护以错误结束时，徽章会消失——即使还有插件没更新。原因是完成处理器假设“完成 = 剩余为零”，然后删除了缓存条目。这个假设是如何被打破的，以及我们如何用后端标记行来将真实计数同步到前端的重新设计，可以看另一篇文章：《当维护以错误结束时，插件更新徽章消失了》。