原生 overflow: scroll 会拦截 touch 事件以保障滚动流畅性，导致无法获取手势过程数据；需同时满足 touch-action:none/pan-y、overflow:hidden 和手动实现滚动，并设置 passive:false 才能可靠接管手势。
原生 overflow: scroll 完全不兼容手势识别——你监听不到 touchstart，也拿不到滑动过程中的坐标变化，更没法阻止默认滚动来接管逻辑。
为什么 overflow: scroll 会吞掉手势事件
浏览器对带滚动条的容器做了底层优化：iOS Safari 几乎 100% 拦截 touchstart 和 touchmove，Android Chrome 在快速滑动时也会丢事件或延迟派发。即使你加了监听器，event.touches.length 可能始终为 0，或者 touchend 根本不触发。
这不是 bug，是浏览器为保障滚动流畅性主动做的“事件劫持”。它只把最终滚动结果通过 scroll 事件告诉你，但手势识别要的是“正在滑”的过程。
-
touch-action: auto（默认值）会让系统优先处理滚动，JS 层收不到原始触摸数据 -
preventDefault()在未声明touch-action的滚动容器中无效，调了也白调 -
scroll事件本身滞后、节流严重，且无法获取方向、速度、加速度等关键信息
让容器同时支持滚动和手势的三个硬性条件
必须同时满足以下三点，缺一不可：
立即学习“前端免费学习笔记（深入）”；
- 容器 CSS 设置
touch-action: none（交出手势控制权），或更精细地用touch-action: pan-y（允许竖向滚动，保留横向 touch 事件） - 容器明确设置尺寸 +
overflow: hidden（不能是auto或scroll） - 手动实现滚动位移：用
transform: translateY()或element.scrollTop，而不是依赖原生滚动条
示例关键 CSS：
.swipe-container {
height: 300px;
overflow: hidden;
touch-action: pan-y;
}
注意：touch-action: pan-y 不等于“允许滚动 + 同时发 touch 事件”——它只是告诉浏览器“竖向由你管，横向我来”，但你仍需在 touchmove 中根据 Math.abs(dx) > Math.abs(dy) 预判方向，并在确认是横向滑动时立刻调用 preventDefault()，否则中间那几十毫秒的原生滚动已启动，造成“先跳一下再接管”的撕裂感。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
passive: false 是 preventDefault() 起效的前提
Chrome 从 56 版起默认给 touchmove 添加 { passive: true }，意味着你调用 preventDefault() 会被静默忽略。不显式传 { passive: false }，手势接管就注定失败。
正确写法：
el.addEventListener('touchstart', handler, { passive: false });
el.addEventListener('touchmove', handler, { passive: false });
el.addEventListener('touchend', handler);
// 注意：touchend 不需要 passive: false
常见错误：
- 只给
touchstart加{ passive: false }，漏了touchmove→preventDefault()失效 - 在
touchmove里做重计算（如反复查 DOM、调用getBoundingClientRect()）→ 掉帧、位移抖动、阈值误判 - 用
scrollLeft/scrollTop判断方向 → 它们更新慢、有延迟，且受overscroll-behavior干扰，不如直接算touches[0].clientX
React/Vue 中 ref 绑定容易踩的坑
用 useRef 或 ref 拿到 DOM 元素后直接绑定事件，但组件重渲染时没清理旧监听器，或闭包捕获了过期的 state（比如 startX 始终是初始值），会导致手势回调失效。
关键点：
- 务必在
useEffect（React）或onBeforeUnmount（Vue）中调用removeEventListener - 手势中需要持续追踪的状态（如上一次位置、是否激活）建议用
useRef存储，而非useState，避免触发重渲染打断连贯性 - 别在
touchmove里直接setState—— 高频触发会卡顿，应节流后批量更新
最常被忽略的一点：iOS Safari 对 touch-action 的解析比 Chrome 更严格，pan-x pan-y 写法在某些版本下会被当作非法值而回退到 auto，必须用空格分隔的单值（如 pan-x）或完整组合（如 pan-x pan-y），且确保没有多余空格或换行。
