Overlayscrollbars-react v2按键滚动失效，如何迁移原有滚动代码？

迁移到v2之后，原来的osInstance().scroll调用失效是因为API发生了变更，下面给你对应解决步骤，能实现按上下键时滚动条跟着选中项同步滚动的效果：

1. 调整实例获取方式 #

v2里不再通过osInstance()获取滚动实例，直接通过组件ref就能拿到实例本身。用useRef绑定OverlayScrollbarsComponent后，ref的current属性就是滚动实例。

代码示例：

import { OverlayScrollbarsComponent } from 'overlayscrollbars-react';
import { useRef, useEffect, useState } from 'react';

const SuggestionList = () => {
  const scrollRef = useRef(null);
  const [selectedIndex, setSelectedIndex] = useState(-1);
  // 滚动配置按需调整
  const scrollOptions = { scrollbars: { autoHide: 'scroll' } };

  // 监听选中索引变化，同步滚动位置
  useEffect(() => {
    if (selectedIndex === -1) return;
    // 定位选中的列表项
    const targetItem = document.querySelector(`.suggestion-item[data-index="${selectedIndex}"]`);
    if (!targetItem || !scrollRef.current) return;

    // v2的scroll方法接收配置对象，指定目标元素与滚动参数
    scrollRef.current.scroll({
      el: targetItem,
      block: 'nearest', // 确保元素进入视图，避免过度滚动
      behavior: 'smooth', // 可选，开启平滑滚动
    });
  }, [selectedIndex]);

  return (
    <OverlayScrollbarsComponent ref={scrollRef} options={scrollOptions}>
      {/* 渲染建议列表，给每个项标记索引和类名 */}
      {suggestions.map((item, idx) => (
        <div
          key={idx}
          className={`suggestion-item ${idx === selectedIndex ? 'active' : ''}`}
          data-index={idx}
        >
          {item.name}
        </div>
      ))}
    </OverlayScrollbarsComponent>
  );
};

2. 关键API变动说明 #

• 实例获取：v2的OverlayScrollbarsComponent ref直接指向滚动实例，无需额外调用osInstance()。
• scroll方法参数：原参数格式作废，现在传递配置对象，el指定要滚动到的DOM元素，block控制垂直对齐方式（可选值：start/center/end/nearest），behavior控制滚动是否平滑。

3. 更稳定的替代方案：使用元素原生滚动 #

如果不想依赖组件的scroll方法，直接让选中项调用原生scrollIntoView也能实现同步效果，还能规避组件API变更的影响：

useEffect(() => {
  if (selectedIndex === -1) return;
  const targetItem = document.querySelector(`.suggestion-item[data-index="${selectedIndex}"]`);
  if (!targetItem) return;

  targetItem.scrollIntoView({
    behavior: 'smooth',
    block: 'nearest',
  });
}, [selectedIndex]);

要是担心DOM选择器出错，还可以用ref数组存储每个列表项的引用，避免DOM查询：

const itemRefs = useRef([]);

// 渲染列表时绑定ref
{suggestions.map((item, idx) => (
  <div
    key={idx}
    ref={el => itemRefs.current[idx] = el}
    className={`suggestion-item ${idx === selectedIndex ? 'active' : ''}`}
  >
    {item.name}
  </div>
))}

// 同步滚动时直接取ref
useEffect(() => {
  if (selectedIndex === -1) return;
  const targetItem = itemRefs.current[selectedIndex];
  if (!targetItem || !scrollRef.current) return;

  scrollRef.current.scroll({
    el: targetItem,
    block: 'nearest',
    behavior: 'smooth',
  });
}, [selectedIndex]);

这种方式完全避免了DOM选择器可能带来的错误，稳定性更高。

内容的提问来源于stack exchange，提问作者rainz