React粘性头部导航跳转异常：offsetTop读取null报错

核心问题定位 #

报错Uncaught TypeError: Cannot read properties of null (reading 'offsetTop')的本质是：你通过document.querySelector(targetAttr)获取的DOM元素不存在（返回null），尽管targetAttr的值正确，但要么元素还未渲染，要么选择器与DOM结构不匹配。

分步解决方案 #

1. 先确认选择器与DOM的匹配性 #

直接在控制台打印document.querySelector(targetAttr)，判断是否为null：

• 如果是null，先检查targetAttr格式：比如目标元素是<div id="about"></div>，targetAttr必须是"#about"（带#前缀）；如果是类名，要带.前缀，别漏了标识符号。
• 再检查目标元素是否在当前页面存在：比如其他导航项对应的组件是路由懒加载的，点击时组件还未挂载，自然找不到DOM。

2. 用React Ref替代原生querySelector（推荐） #

原生DOM操作易受React渲染机制影响，改用Ref能确保获取到已渲染的元素：

// 第一步：给每个目标区块添加Ref
import { useRef } from 'react';

const BlogSection = () => {
  const blogRef = useRef(null);
  return <div ref={blogRef} id="blog">Blog内容</div>;
};

const AboutSection = () => {
  const aboutRef = useRef(null);
  return <div ref={aboutRef} id="about">About内容</div>;
};

// 第二步：在导航组件中维护Ref映射，点击时直接用Ref跳转
import { useRef } from 'react';

const Nav = () => {
  // 定义所有区块的Ref
  const sectionRefs = {
    blog: useRef(null),
    about: useRef(null),
    services: useRef(null)
  };

  const handleNavClick = (sectionKey) => {
    const targetRef = sectionRefs[sectionKey].current;
    if (targetRef) {
      // 减去粘性头部高度，避免锚点内容被头部遮挡
      const headerHeight = document.querySelector('.sticky-header').offsetHeight;
      window.scrollTo({
        top: targetRef.offsetTop - headerHeight,
        behavior: 'smooth'
      });
    }
  };

  // map渲染导航菜单
  const navItems = [
    { key: 'blog', label: 'Blog' },
    { key: 'about', label: 'About' },
    { key: 'services', label: 'Services' }
  ];

  return (
    <nav className="sticky-header">
      {navItems.map(item => (
        <button key={item.key} onClick={() => handleNavClick(item.key)}>
          {item.label}
        </button>
      ))}
    </nav>
  );
};

3. 路由场景下的处理（多页面路由） #

如果导航对应不同的路由页面，点击时要等路由组件挂载后再执行滚动：

import { useNavigate, useLocation, useEffect } from 'react-router-dom';

const Nav = () => {
  const navigate = useNavigate();
  const location = useLocation();

  // 路由切换完成后执行滚动逻辑
  useEffect(() => {
    const hash = location.hash;
    if (hash) {
      const targetElement = document.querySelector(hash);
      if (targetElement) {
        const headerHeight = document.querySelector('.sticky-header').offsetHeight;
        window.scrollTo({
          top: targetElement.offsetTop - headerHeight,
          behavior: 'smooth'
        });
      }
    }
  }, [location]);

  const handleNavClick = (targetAttr) => {
    // 跳转到对应路由并携带hash
    navigate(`/${targetAttr.slice(1)}${targetAttr}`);
  };

  // 渲染菜单...
};

4. 异步渲染/条件渲染的情况 #

如果目标元素是异步加载数据后才显示的，用requestAnimationFrame确保DOM更新完成再滚动：

const handleNavClick = (targetAttr) => {
  // 假设这里有异步数据加载逻辑
  loadSectionData().then(() => {
    requestAnimationFrame(() => {
      const targetElement = document.querySelector(targetAttr);
      if (targetElement) {
        const headerHeight = document.querySelector('.sticky-header').offsetHeight;
        window.scrollTo({
          top: targetElement.offsetTop - headerHeight,
          behavior: 'smooth'
        });
      }
    });
  });
};

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