触发条件 (Conditions for Occurrence)

  • 在移动端（移动浏览器，Mobile Browser）、iOS Safari、Android Chrome 或各类移动端混合应用（混合开发，Hybrid WebApp / Android WebView）中。
  • 使用原生 HTML 按钮元素（HTML <button> Element）实现胶囊药丸（Filter Chip / Tab）、分类切换卡片、快捷标签等高频点选控件。
  • 样式中针对该元素编写了悬停态（:hover）、聚焦态（:focus / :focus-visible）或按压态（:active），且在这些状态下改变了背景底色（如浅米灰/羊毛色 var(--surface-soft)、边框对比度或文字反色）。

症状或表现 (Symptoms or Manifestations)

  • 按压无法自动弹起：在真机或移动端模拟器上轻触（Tap）该按钮后，手指虽已离开屏幕，但按钮视觉状态并未立即恢复默认，如同“一直被手指死死按住”。
  • 白边白字遮挡：在部分机型（尤其深浅模式交替或开启高对比的 Android WebView）中，按钮上浮现一层白色高亮边框和白色字体，与浅色底色融为一体，导致内部图标与文案被彻底遮挡。
  • 必须点击空白处才复原：只有当用户在屏幕其他任意区域轻点一次（触发失焦事件，Blur Event），刚刚被点过的按钮才会如梦初醒般“弹起来”恢复正常默认形态。

容易误判的排查方向 (Attempted Solutions and Pitfalls)

  1. 误判一：仅仅删除 CSS 中的 :hover
    以为只是桌面端鼠标悬停（Mouse Hover）误伤移动端，把 :hover 删掉后以为大功告成。但在真机实测中，点击依然卡在按下态。因为移动浏览器点击除了虚拟 Hover，还会派发并长期维持原生焦点（Focus）。
  2. 误判二：过度依赖指针媒体查询（Pointer Media Queries）
    使用 @media (pointer: coarse) 或 @media (hover: none) 对触屏进行样式重置。然而 Android 生态碎片化严重，搭载手写笔、高采样率触控芯片的设备常常被内核识别为 pointer: fine，导致媒体查询直接失效。
  3. 误判三：以为只是点击高亮（Tap Highlight）
    试图仅通过 -webkit-tap-highlight-color: transparent; 或 outline: none; 解决。这只能抹去浏览器默认的半透明遮罩与外层焦点圈，但原生 <button> 的内部状态锁死并未解除。

根本原因 (Root Cause)

  1. 触屏设备的合成鼠标事件机制 (Synthetic Mouse Events on Touch)
    移动端浏览器为了向前兼容非触屏网页，在手指发生 touchstart -> touchend 之后，会依次在原地派发虚拟的 mousemove -> mousedown -> focus -> click 事件流。因为触屏没有物理鼠标离开该坐标，内核会把虚拟指针留在该元素上，从而造成长期悬停假象。
  2. HTML <button> 属于原生表单聚焦控件 (Native Form Focusable Control)
    标准 <button> 是天生具备焦点生命周期的表单元素。在桌面端，点击其他地方或晃动鼠标可平滑失焦；而在移动端，用户手指抬起后，系统没有任何理由让这个 <button> 自动主动失焦。它将一直持有 :focus、:focus-visible 及内置按压激活记录，直至下一个接收焦点的元素被点击。
  3. 用户代理默认样式表 (User Agent Stylesheet) 与状态叠加冲突
    某些浏览器内核对 focused <button> 有强行的对比度加深与白色描边处理。若业务代码的激活态（.active）使用了强调色背景与白色文字，当用户切换或点击时，滞留的表单焦点样式与未激活状态强行叠加，便会引发“白字白底”、“边框残影”的诡异现象。

最终解决步骤 (Final Resolution Steps)

1. 架构解耦：移动端卡片切换控件彻底移除 <button>、role="button" 与 tabIndex={0}

<div> 作为通用容器元素，本身不带有原生表单焦点的粘滞机制（Native Form Focus Retention）。
特别注意深坑：切勿画蛇添足地加上 tabIndex={0}！一旦加上 tabIndex={0}，浏览器便会将其视作可获焦控件（Focusable Element），点击后依然会永久持有 :focus 状态，除非用户点击别处，否则不会失焦，等于重新跌回了表单焦点的陷阱中！

{/* 错误写法 1：原生 button，点击后触屏无法自动弹起 */}
<button className={`filter-chip ${active ? 'active' : ''}`} onClick={...}>
  {label}
</button>

{/* 错误写法 2：虽然改成了 div，但保留了 tabIndex={0}，触屏点击后依然死死获焦滞留 */}
<div
  role="button"
  tabIndex={0}
  className={`filter-chip ${active ? 'active' : ''}`}
  onClick={...}
>
  {label}
</div>

{/* 正确写法：干净纯粹、无焦点滞留隐患的 div 卡片 */}
<div
  className={`filter-chip ${active ? 'active' : ''}`}
  onClick={...}
>
  {label}
</div>

2. 警惕选择器特异性冲突（Selector Specificity Trap）导致的“白底白字”

如果项目中存在上层包裹类（如 html.legacy-css），其声明的规则形如：

html.legacy-css .filter-chip:focus {
  background: var(--surface); /* 米白色表面底 */
  border-color: var(--line);
}

该选择器的特异性为 (0, 2, 1)（1个标签 + 1个类名 + 1个伪类），而组件局部的激活态 .filter-chip.active 仅为 (0, 2, 0)！
当用户在触屏上点击卡片使其变为激活态时，由于 tabIndex={0} 导致元素同时处于 :focus，上层的米白底色强制压制了激活态底色，而激活态的文字颜色却依然是白色（#ffffff），最终形成“米白底 + 白字（内容被遮挡消失）”的严重事故。

3. 彻底根治：双向单一信源锁定与零过渡（No Transition）

切换标签必须干净利落，坚决移除 transition（避免颜色与背景渐变不同步时产生的短暂白底白字中间态），并使用 :not(.active) 强制锁死未激活态：

/* 纯轻量 DIV 卡片，无按钮行为、无中间态、无动画过渡 */
.filter-chip {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  height: 31px;
  padding: 0 13px;
  border-radius: 999px;
  background: var(--surface);
  border: 1px solid color-mix(in srgb, var(--line) 85%, transparent);
  color: var(--muted);
  font-size: 12px;
  font-weight: 600;
  cursor: pointer;
  white-space: nowrap;
  flex-shrink: 0;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
  outline: none !important;
  box-shadow: none !important;
  transition: none !important;
  transform: none !important;
}

/* 未激活态：任何伪类均死死锁定普通底色与字色，坚决杜绝任何白底白字与中间态残留 */
.filter-chip:not(.active),
.filter-chip:not(.active):hover,
.filter-chip:not(.active):active,
.filter-chip:not(.active):focus,
.filter-chip:not(.active):focus-visible {
  background: var(--surface) !important;
  color: var(--muted) !important;
  border: 1px solid color-mix(in srgb, var(--line) 85%, transparent) !important;
  outline: none !important;
  box-shadow: none !important;
  transform: none !important;
}

/* 激活态：深蓝底白字，任何伪类下坚决保持，绝不允许被覆盖成米白底 */
.filter-chip.active,
.filter-chip.active:hover,
.filter-chip.active:active,
.filter-chip.active:focus,
.filter-chip.active:focus-visible {
  background: var(--accent) !important;
  color: #ffffff !important;
  border: 1px solid var(--accent) !important;
  font-weight: 700;
  outline: none !important;
  box-shadow: none !important;
  transform: none !important;
}

/* 选中态：严格由 .active 类名单独驱动，杜绝样式撕裂 */
.filter-chip.active,
.filter-chip.active:hover,
.filter-chip.active:focus {
  background: var(--accent);
  color: #ffffff;
  border-color: var(--accent);
  font-weight: 700;
}

3. 移动端防干扰三件套

  • -webkit-tap-highlight-color: transparent;：清除 WebKit 触摸时的半透明高亮闪斑。
  • user-select: none;：防止用户快速连续点击或按住时，选中文本引发原生文本光标或弹出菜单。
  • outline: none;：抹平任何 Android 内核追加的辅助外边框。

下次如何识别 (How to Recognize It Next Time)

  • 识别口诀：“手机点一下卡住不褪色，点别处才弹回原状，必是原生按钮焦点与触屏虚拟 Hover 粘滞”。

  • 速查特征：

    1. 页面表现为“处于按下态（Pressed / Active / Focus）久久不褪”；
    2. 只有在屏幕其他空白处随便点一下，它才瞬间恢复；
    3. 检查 DOM 标签，该元素必然是原生 <button>；
    4. 检查 CSS，该类名必然存在改变 background 的 :hover 或 :focus。
  • 触屏合成事件 (Synthetic Click & Mouse Events)：触摸屏为了兼容传统鼠标网页而模拟派发鼠标事件流的过程。
  • 可访问性角色 (WAI-ARIA role="button")：当使用 <div> 或 <span> 模拟按钮交互时，为辅助功能屏幕阅读器提供的语义映射。
  • 元素焦点模型 (DOM Element Focus Lifecycle)：浏览器管理键盘与指针聚焦焦点的状态机。
  • 移动端点击高亮 (-webkit-tap-highlight-color)：WebKit / Blink 引擎在触屏点按时自动绘制的遮罩反馈。

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Frontend