Floating UI 中 useListNavigation 动态列表项移除时的焦点管理问题

在开发基于 Floating UI 的可访问性组件时，动态列表项管理是一个常见需求。本文将深入分析 useListNavigation 钩子在处理动态列表项移除时的焦点管理问题，并提供解决方案。

问题现象

当使用 useListNavigation 构建非浮动 Listbox 组件时，如果列表项被动态移除，会出现焦点被意外移动到列表内部的情况。具体表现为：

1. 用户通过键盘导航选择列表中的某一项（如"Watermelon"）
2. 离开列表焦点到外部按钮
3. 通过按钮动态移除列表项
4. 焦点被自动移回列表内部

技术原理分析

useListNavigation 钩子内部维护了一个 selectedIndex 状态，用于跟踪当前选中的列表项。当列表项发生变化时，钩子会自动处理焦点逻辑：

1. 钩子会监听 selectedIndex 的变化
2. 当 selectedIndex 改变时，会自动将焦点移动到对应的列表项
3. 这种设计在大多数静态列表场景下工作良好

问题根源在于，钩子没有检查当前焦点是否实际位于列表内部，就执行了焦点移动操作。这导致了即使焦点在外部控件上，也会被强制拉回列表。

解决方案

方案一：避免在渲染中读取 ref

在 React 中，渲染期间读取 ref 是反模式行为。重构代码，使用 selectedIndex 代替直接读取 ref 可以避免部分问题：

// 错误做法：在渲染中读取 ref
const selectedLabel = itemsRef.current[selectedIndex]?.textContent;

// 正确做法：使用 selectedIndex 管理状态
const [selectedIndex, setSelectedIndex] = useState(0);

方案二：控制 selectedIndex 的响应性

对于需要完全控制焦点行为的场景，可以使 selectedIndex 成为非响应式状态：

// 使用 useState 而非 useRef 管理 selectedIndex
const [selectedIndex, setSelectedIndex] = useState(initialIndex);

// 在需要更新时显式调用
const handleItemRemove = () => {
  setSelectedIndex(prev => /* 计算新索引 */);
};

方案三：自定义焦点管理

对于高级场景，可以扩展 useListNavigation 的行为，添加焦点位置检查：

const { refs } = useListNavigation({
  // ...其他配置
  onSelectedIndexChange: (index) => {
    if (/* 检查焦点是否在列表内 */) {
      // 执行默认焦点移动
    }
  }
});

最佳实践建议

1. 对于动态列表，优先考虑使用受控组件模式
2. 避免在渲染期间读取 DOM 引用
3. 在列表项变化时，显式管理焦点状态
4. 考虑添加视觉提示，告知用户列表已更新

通过理解 Floating UI 的焦点管理机制，开发者可以构建更健壮的可访问性组件，特别是在处理动态内容场景下。