Headless UI Popover：打开导航菜单时禁用页面滚动优化方案

方案1：利用Headless UI Popover的onOpenChange回调（推荐） #

Headless UI的Popover组件自带onOpenChange事件，每次弹窗状态切换时只会触发一次，刚好用来控制页面滚动，避免重复执行冗余代码。

示例代码：

'use client';
import { Popover } from '@headlessui/react';
import { useState } from 'react';

export default function NavigationPopover() {
  const [isOpen, setIsOpen] = useState(false);

  const handlePopoverChange = (open: boolean) => {
    setIsOpen(open);
    // 控制页面滚动，空字符串会恢复元素默认样式，比硬设auto更稳妥
    document.body.style.overflow = open ? 'hidden' : '';
  };

  return (
    <Popover open={isOpen} onOpenChange={handlePopoverChange}>
      <Popover.Button>打开菜单</Popover.Button>
      <Popover.Panel>
        {/* 菜单内容 */}
      </Popover.Panel>
    </Popover>
  );
}

方案2：用useEffect监听弹窗状态（需遵守Hook规则） #

如果要使用useEffect，必须把它放在组件顶层作用域，依赖数组只传入isOpen，确保仅当状态变化时执行：

'use client';
import { Popover } from '@headlessui/react';
import { useState, useEffect } from 'react';

export default function NavigationPopover() {
  const [isOpen, setIsOpen] = useState(false);

  useEffect(() => {
    document.body.style.overflow = isOpen ? 'hidden' : '';
    // 组件卸载时恢复滚动状态，避免页面残留异常样式
    return () => {
      document.body.style.overflow = '';
    };
  }, [isOpen]);

  return (
    <Popover open={isOpen} onOpenChange={setIsOpen}>
      <Popover.Button>打开菜单</Popover.Button>
      <Popover.Panel>
        {/* 菜单内容 */}
      </Popover.Panel>
    </Popover>
  );
}

关键注意事项 #

• 之前用useEffect报错，大概率是Hook没放在组件顶层（比如嵌套在条件判断、循环里），必须保证useEffect在组件最外层调用。
• 若项目存在服务端渲染（SSR/SSG），务必给组件加上'use client'指令，因为服务端无法操作document对象。
• 如果页面原本有自定义的overflow配置，可提前保存原始值，关闭弹窗时再恢复，避免样式覆盖问题。

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