Rspress 搜索功能键盘导航定位异常问题分析与修复

在 Rspress 文档工具中，搜索功能是用户快速定位内容的重要入口。近期发现了一个影响用户体验的键盘导航定位异常问题：当用户使用键盘方向键浏览搜索结果时，在滚动到可视区域最后一项后继续向下导航，会导致定位项跳转到上方而非预期的下一项。

问题现象

当用户通过键盘方向键向下浏览搜索结果时：

1. 当前高亮项到达可视区域底部
2. 继续按下方向键时，高亮项不会按预期移动到下一项
3. 反而会跳转到上方某个随机项
4. 这种异常行为打断了用户的浏览流程，降低了搜索体验

技术分析

通过代码审查和调试，发现问题的根源在于事件处理的冲突：

1. 键盘事件处理：当按下方向键时，会计算并更新当前高亮项的索引
2. 滚动触发：当高亮项到达可视区域边缘时，浏览器会自动滚动列表
3. 鼠标事件干扰：滚动过程中，鼠标位置可能恰好悬停在某个列表项上
4. 事件冲突：鼠标悬停事件会覆盖键盘事件设置的高亮状态

具体表现为：

• 键盘事件设置了一个高亮索引
• 滚动导致的鼠标悬停又设置了另一个高亮索引
• 最终呈现的是鼠标事件设置的状态，而非键盘导航预期的状态

解决方案

经过深入分析，提出了以下修复方案：

1. 移除冗余的悬停样式：原有的CSS中同时存在:hover和.current两种高亮样式，这会导致视觉不一致
2. 优化事件处理逻辑：通过记录鼠标位置信息，在onMouseEnter事件中判断是否为真实悬停
3. 统一高亮状态管理：确保任何时候只有一个机制（键盘或鼠标）控制高亮状态

实现要点：

• 保留.current类作为唯一的高亮指示器
• 通过鼠标位置追踪区分真实悬停和滚动导致的伪悬停
• 确保键盘导航优先级高于被动触发的鼠标事件

修复效果

修复后：

• 键盘导航可以流畅地遍历所有搜索结果
• 不会出现高亮项意外跳转的情况
• 鼠标悬停和键盘导航的高亮效果保持一致
• 整体搜索体验更加自然和可预测

技术启示

这个问题给我们以下启示：

1. UI状态管理：需要明确不同交互方式对UI状态的控制权
2. 事件处理顺序：要注意浏览器事件的触发顺序和可能的冲突
3. 用户体验一致性：确保不同交互方式产生一致的视觉效果
4. 边界条件测试：特别关注可视区域边缘的交互行为

这类问题的解决不仅修复了功能缺陷，也提升了整个项目的交互质量和用户体验。