求助：Headless UI Dialog在移动设备上隐藏滚动条的原因

问题背景 #

使用@headlessui/react v1.7.14的滑入式Dialog组件时，出现以下差异表现：

• 桌面端（Chrome/Safari）：滚动时显示自定义滚动条，静止时隐藏，表现正常
• 桌面端模拟iOS移动端：滚动条表现符合预期
• 真实iOS设备（iPhone SE）：打开Dialog后自定义滚动条完全隐藏，影响功能使用

推测问题与Headless UI默认的滚动锁定机制或iOS原生滚动条特性有关，以下是可行的解决方案：

解决方案1：强制显示iOS滚动条 #

iOS Safari默认隐藏滚动条，仅在滚动时短暂显示。要强制保留自定义滚动条，需添加针对性CSS样式：

/* 自定义滚动条样式 */
.custom-scrollbar::-webkit-scrollbar {
  width: 6px; /* 设置滚动条宽度 */
}
.custom-scrollbar::-webkit-scrollbar-thumb {
  background-color: #888; /* 滑块颜色 */
  border-radius: 3px; /* 滑块圆角 */
}
.custom-scrollbar::-webkit-scrollbar-track {
  background-color: #f1f1f1; /* 轨道颜色 */
}

/* 确保iOS平滑滚动 */
.custom-scrollbar {
  overflow-y: auto;
  -webkit-overflow-scrolling: touch;
}

将类名应用到Dialog的内容容器：

<div className="pointer-events-auto w-screen overflow-y-auto custom-scrollbar">
  {/* Dialog内部内容 */}
</div>

解决方案2：禁用自动滚动锁定，手动控制背景滚动 #

Headless UI的Dialog默认会锁定页面背景滚动，该机制在iOS上可能干扰滚动条显示。可以禁用自动锁定，手动处理背景滚动：

1. 给Dialog添加lockScroll={false}属性：

<Dialog
  as="div"
  className="z-30 fixed inset-0 sm:overflow-hidden"
  onClose={handleClose}
  lockScroll={false}
>

2. 用useEffect控制body滚动状态：

import { useEffect } from 'react';

// 组件内添加
useEffect(() => {
  const body = document.body;
  if (open) {
    body.style.overflow = 'hidden';
  } else {
    body.style.overflow = '';
  }
  // 组件卸载时恢复默认样式
  return () => {
    body.style.overflow = '';
  };
}, [open]);

解决方案3：排查容器样式冲突 #

检查Dialog父容器是否存在遮挡滚动条的样式：

• 避免内容容器的父元素设置overflow:hidden（你的代码中sm:overflow-hidden仅在大屏幕生效，移动端无需担心，但需确认）
• 排查是否有clip-path、padding-right等属性挤压滚动条空间

整合后的代码示例 #

import { Fragment, useEffect } from 'react';
import { Transition, Dialog } from '@headlessui/react';

// 控制body滚动
useEffect(() => {
  const body = document.body;
  if (open) {
    body.style.overflow = 'hidden';
  } else {
    body.style.overflow = '';
  }
  return () => {
    body.style.overflow = '';
  };
}, [open]);

return (
  <Transition.Root show={open} as={Fragment}>
    <Dialog
      as="div"
      className="z-30 fixed inset-0 sm:overflow-hidden"
      onClose={handleClose}
      lockScroll={false}
    >
      <div className="absolute inset-0 sm:overflow-hidden">
        <Dialog.Overlay className="absolute inset-0" />

        <div className="pointer-events-none fixed transform sm:top-0 right-0 flex h-full sm:pb-0 sm:w-500">
          <Transition.Child
            as={Fragment}
            enter="transform transition ease-in-out duration-500 sm:duration-700"
            enterFrom="translate-x-full"
            enterTo="translate-x-0"
            leave="transform transition ease-in-out duration-500 sm:duration-700"
            leaveFrom="translate-x-0"
            leaveTo="translate-x-full"
          >
            <div className="pointer-events-auto w-screen overflow-y-auto custom-scrollbar">
              {/* Dialog内部内容 */}
            </div>
          </Transition.Child>
        </div>
      </div>
    </Dialog>
  </Transition.Root>
);

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