关于uniapp微信小程序webview嵌套H5时iOS橡皮回弹与下拉漏白的解决方案

1. 背景与现象

项 说明
场景 微信小程序通过 web-view 打开 H5（示例：战投 H5 Demo）
端 iOS 为主（Android 一般不明显或表现不同）
现象 手指下拉时，导航栏 /「此网页由 xxx 提供」下方出现大块白底，H5 内容整体被拽下，松手回弹
非问题 不是小程序 enablePullDownRefresh 业务下拉刷新；域名提示条为微信能力，无需当 bug 去掉

典型入口（小程序）：

  • 页面：subpkg-tool/webview/index
  • 示例跳转：/subpkg-tool/webview/index?url=<encodeURIComponent(h5Url)>&title=...
  • 战投 Demo H5：/h5/strategic-investment/demo（仓库：h5）

修改前下拉漏白：

修改前下拉漏白

修改后下拉固定：

修改后下拉固定

2. 根因结论

问题由 两层 叠加，主因在 H5 / WKWebView，小程序侧无法单独根治。

2.1 主因：iOS WKWebView 整页橡皮筋（overscroll bounce）

  • 小程序 web-view 在 iOS 上基于 WKWebView。
  • 文档层（html / body）或「非内部滚动容器」上的下拉手势，会被 WebView 整页回弹。
  • 回弹时页面上移，露出 WebView / body 默认浅色底 → 观感为 漏白。
  • 微信 未提供 关闭 web-view 内部 bounces 的官方 API。

2.2 战投 Demo 已有防护为何仍不够

H5：h5 → apps/src/views/strategic-investment/Demo.vue

已做 缺口
内容区 .module-card 使用 overscroll-behavior: none iOS 微信 web-view 内 不可靠，不能当唯一手段
bindElasticScrollGuard 绑定两个详情滚动区 只保护卡片内部；标题、Tab、渐变空白处触摸仍落到文档/WKWebView
.page { overflow: hidden; height: 100vh } 全局 html/body 仍是可参与滚动的文档模型；body 背景偏浅（如 #f7f7f7）

因此：在非滚动区域下拉，或内容区已到顶仍继续下拉时，整页被拖动并漏白。

2.3 次要：小程序 webview 页配置

  • web-view 为原生组件，默认铺满页面；同页自定义节点（loading、safe-area 等）盖不住它，对漏白几乎无助。
  • 页面若未 disableScroll: true，外层小程序页仍可能参与滚动。
  • 页面/顶部背景若为全局浅色（如 #F8FAFC），即使轻微回弹也更像「漏白」。
  • disableScroll 只能禁止小程序页面滚动，不能关闭 web-view 内 H5 的橡皮筋。

3. 调整原则

  1. 治本在 H5：锁文档滚动 + 边界手势拦截；滚动只放在明确的内部容器。
  2. 小程序辅助：禁页滚、顶部背景与 H5 头图主色一致，减轻观感。
  3. 不依赖 单独设置 enablePullDownRefresh: false（默认多为关闭，与本问题无关）。
  4. 不依赖 官方关闭 web-view bounces 的 API（不存在）。

4. 已执行方案步骤

以下内容为本次在战投 Demo 与小程序承载页上已实际落地的处理，不再只是建议项。

4.1 H5：h5/apps/src/views/strategic-investment/Demo.vue

目标：把 iOS WKWebView 的整页回弹拦截在 H5 内部，避免只有内容卡片受保护、标题区和空白区仍漏白。

步骤 已执行内容 目的
H1 新增 lockDocumentScroll()：进入页面时锁定 html/body，设置 overflow: hidden、overscroll-behavior: none，并将 body 固定为 position: fixed；离开路由时还原 避免文档层参与滚动，减少整页被 WKWebView 拖动
H2 新增 bindDocumentElasticGuard()：在 document 捕获阶段监听 touchstart/touchmove，非滚动区或滚动容器到顶/到底继续拖拽时执行 preventDefault() 把标题区、Tab 区、渐变空白区一并纳入防护
H3 保留并继续使用 bindElasticScrollGuard()，仅让 .module-card 作为业务滚动容器 滚动收敛在内部容器，不让 WebView 抢到边界手势
H4 将 body 兜底背景设置为 #fe8647 即使极端情况下仍有轻微回弹，视觉上也不再是大块白底
H5 给 .page、.module-card 增加 touch-action: pan-y，给 .module-card 补 overscroll-behavior-y: none 作为辅助约束，降低系统回弹触发概率
H6 刻意不加 .module-card 的 -webkit-overflow-scrolling: touch 该属性会把容器放到独立合成滚动层，使 overscroll-behavior 失效，并让非 passive 的 preventDefault 在惯性阶段拦不住手势；iOS 13+ 的 overflow: auto 已自带惯性滚动

当前落点（代码）：

  • lockDocumentScroll()
  • bindDocumentElasticGuard()
  • bindElasticScrollGuard()
  • .page { touch-action: pan-y }
  • .module-card { overscroll-behavior-y: none; touch-action: pan-y }（无 -webkit-overflow-scrolling: touch）

说明：

  • overscroll-behavior 在 iOS 微信 web-view 中不能单独依赖，因此此次核心不是单条 CSS，而是“文档层锁定 + 全局 touch 捕获 + 内层唯一滚动”的组合方案。
  • 当前处理仍按页面隔离在 Demo.vue 内，离开该路由会回收 html/body 样式和事件监听，避免污染其它 H5 页面。

4.2 H5：ECharts tooltip 与文档锁滚动的取舍

漏白方案落地后，图表 tooltip 会出现额外约束：

方案 结果
常规：appendToBody: true 挂到 body 可减轻点击时溢出可视区遮挡，但 document 已锁、滚动只在 .module-card；挂 body 的 tip 用文档坐标定位，ECharts 仅在展示/移动时算一次坐标，滚动后与图表脱钩产生漂移
当前采用：留在图表容器内 避免漂移；边缘点击时仍可能有轻微溢出遮挡，观感不明显，且可通过再次点击/滚动关闭规避

当前落地：

文件 处理
apps/src/utils/strategic-investment/chart-option-builder.ts 共享 baseTooltip：confine: true、appendToBody: false、extraCssText: 'max-width:80%;'；各图表 option 复用
apps/src/components/strategic-investment/EChartCard.vue 监听最近滚动祖先（.module-card）的 scroll / touchstart，dispatchAction({ type: 'hideTip' })；滚动后 debounce resize() 
// tooltip 必须留在图表容器内部。页面滚动收敛在 `.module-card`，document 自身被锁住不滚动，
// 挂到 body 的 tooltip 会改用文档坐标定位，而 ECharts 只在展示/移动时算一次坐标，
// 滚动后就与图表脱钩。confine 把 tooltip 约束进画布矩形，既不会碰到祖先容器的裁剪边界，
// 也天然跟着图表一起滚动。max-width 保证 confine 有收拢空间：tooltip 比画布还宽时 confine 会失效。
const baseTooltip = {
  confine: true,
  appendToBody: false,
  extraCssText: 'max-width:80%;',
}

已知限制：尚未找到「漏白防护」与「tooltip 挂 body 且滚动不漂移」两者完全兼容的方案；当前优先保证下拉不漏白与 tip 不漂移，溢出遮挡作为可接受副作用。

4.3 小程序：sales-proposal-miniapp/pages.json

目标：限制小程序承载页自身的滚动能力，并通过背景色降低回弹残留时的漏白观感。

步骤 已执行内容 目的
M1 disableScroll: true 禁止小程序页面本身滚动
M2 enablePullDownRefresh: false 显式关闭页面级下拉刷新，避免误判为业务刷新能力
M3 backgroundColor: "#fe8647"、backgroundColorTop: "#fe8647"、backgroundColorBottom: "#ffffff" 与战投 H5 顶部主色对齐，减轻顶部漏白观感

说明：

  • 这些配置属于治标辅助，不能替代 H5 侧治理。
  • disableScroll 只能限制小程序页本身，不会关闭 web-view 内部 H5 的 WKWebView 回弹。

4.4 小程序承载页：sales-proposal-miniapp/subpkg-tool/webview/index.vue

当前处理原则：保持 web-view 全屏承载，不继续尝试“小窗化”或普通视图遮罩方案。

处理 结论
web-view 全屏铺满 保留。作为原生组件，符合微信端的稳定承载方式
在同页放普通 view 色块/遮罩覆盖 web-view 已验证不可靠。普通节点无法稳定盖住原生 web-view
试图把 web-view 缩成 200rpx * 200rpx 已验证不符合预期，不能作为解决 iOS 灰块问题的方向

结论：

  • subpkg-tool/webview/index.vue 负责承载和 loading，不承担“裁剪原生 web-view 回弹”的职责。
  • 该页适合作为统一 web-view 宿主页，但不能指望通过普通 view 样式把 web-view 裁成局部窗口来规避灰块。

4.5 联合实施顺序

  1. 先在 H5 Demo.vue 内落实 H1-H6，优先解决主因。
  2. 同步落实 tooltip 策略（baseTooltip + EChartCard 滚动关 tip），避免挂 body 漂移。
  3. 再在小程序 pages.json 中补齐 M1-M3，作为辅助配置统一生效。
  4. subpkg-tool/webview/index.vue 保持全屏宿主，不再尝试依赖普通视图层遮罩或小窗布局。
  5. 以 iOS 真机在小程序 web-view 场景中做手势回归，重点验证标题区、Tab 区、列表到顶/到底，以及图表 tip 点击与滚动后位置是否正常。

4.6 H5 代码（h5/apps/src/views/strategic-investment/Demo.vue）

脚本：文档锁滚动 + 全局/内层手势拦截

const sectionCleanupFns: Array<() => void> = []
const pageCleanupFns: Array<() => void> = []
const BOUNCE_GUARD_THRESHOLD = 8

function getScrollableAncestor(target: EventTarget | null) {
  let el = target instanceof Element
    ? target
    : target instanceof Node
      ? target.parentElement
      : null

  while (el && el !== document.body) {
    const style = window.getComputedStyle(el)
    const overflowY = style.overflowY
    const isScrollable = /(auto|scroll|overlay)/.test(overflowY)

    if (isScrollable && el.scrollHeight > el.clientHeight + 1) {
      return el as HTMLElement
    }

    el = el.parentElement
  }

  return null
}

function lockDocumentScroll() {
  const html = document.documentElement
  const body = document.body
  const scrollTop = window.scrollY
  const htmlStyleSnapshot = {
    overflow: html.style.overflow,
    overscrollBehavior: html.style.overscrollBehavior,
    height: html.style.height,
  }
  const bodyStyleSnapshot = {
    position: body.style.position,
    top: body.style.top,
    left: body.style.left,
    right: body.style.right,
    width: body.style.width,
    height: body.style.height,
    overflow: body.style.overflow,
    overscrollBehavior: body.style.overscrollBehavior,
    background: body.style.background,
  }

  html.style.overflow = 'hidden'
  html.style.overscrollBehavior = 'none'
  html.style.height = '100%'

  body.style.position = 'fixed'
  body.style.top = `-${scrollTop}px`
  body.style.left = '0'
  body.style.right = '0'
  body.style.width = '100%'
  body.style.height = '100%'
  body.style.overflow = 'hidden'
  body.style.overscrollBehavior = 'none'
  body.style.background = '#fe8647'

  return () => {
    html.style.overflow = htmlStyleSnapshot.overflow
    html.style.overscrollBehavior = htmlStyleSnapshot.overscrollBehavior
    html.style.height = htmlStyleSnapshot.height

    body.style.position = bodyStyleSnapshot.position
    body.style.top = bodyStyleSnapshot.top
    body.style.left = bodyStyleSnapshot.left
    body.style.right = bodyStyleSnapshot.right
    body.style.width = bodyStyleSnapshot.width
    body.style.height = bodyStyleSnapshot.height
    body.style.overflow = bodyStyleSnapshot.overflow
    body.style.overscrollBehavior = bodyStyleSnapshot.overscrollBehavior
    body.style.background = bodyStyleSnapshot.background

    window.scrollTo({ top: scrollTop })
  }
}

function bindDocumentElasticGuard() {
  let startX = 0
  let startY = 0

  const handleTouchStart = (event: TouchEvent) => {
    const touch = event.touches[0]
    if (!touch) return

    startX = touch.clientX
    startY = touch.clientY
  }

  const handleTouchMove = (event: TouchEvent) => {
    const touch = event.touches[0]
    if (!touch) return

    const scrollEl = getScrollableAncestor(event.target)
    if (!scrollEl) {
      if (event.cancelable) event.preventDefault()
      return
    }

    const maxScrollTop = scrollEl.scrollHeight - scrollEl.clientHeight
    if (maxScrollTop <= 1) {
      if (event.cancelable) event.preventDefault()
      return
    }

    const deltaX = touch.clientX - startX
    const deltaY = touch.clientY - startY
    const isVerticalMove = Math.abs(deltaY) > Math.abs(deltaX)
    if (!isVerticalMove || Math.abs(deltaY) < BOUNCE_GUARD_THRESHOLD) {
      return
    }

    const atTop = scrollEl.scrollTop <= 1
    const atBottom = maxScrollTop - scrollEl.scrollTop <= 1

    if ((atTop && deltaY > 0) || (atBottom && deltaY < 0)) {
      if (event.cancelable) event.preventDefault()
    }
  }

  document.addEventListener('touchstart', handleTouchStart, { capture: true, passive: true })
  document.addEventListener('touchmove', handleTouchMove, { capture: true, passive: false })

  return () => {
    document.removeEventListener('touchstart', handleTouchStart, { capture: true })
    document.removeEventListener('touchmove', handleTouchMove, { capture: true })
  }
}

function bindElasticScrollGuard(el?: HTMLElement) {
  if (!el) return () => {}

  let startX = 0
  let startY = 0

  const handleTouchStart = (event: TouchEvent) => {
    const touch = event.touches[0]
    if (!touch) return

    startX = touch.clientX
    startY = touch.clientY

    const maxScrollTop = el.scrollHeight - el.clientHeight
    if (maxScrollTop <= 1) return

    if (el.scrollTop <= 0) {
      el.scrollTop = 1
    }
    else if (maxScrollTop - el.scrollTop <= 1) {
      el.scrollTop = maxScrollTop - 1
    }
  }

  const handleTouchMove = (event: TouchEvent) => {
    const touch = event.touches[0]
    if (!touch) return

    const maxScrollTop = el.scrollHeight - el.clientHeight
    if (maxScrollTop <= 1) {
      event.preventDefault()
      return
    }

    const deltaX = touch.clientX - startX
    const deltaY = touch.clientY - startY
    const isVerticalMove = Math.abs(deltaY) > Math.abs(deltaX)
    if (!isVerticalMove || Math.abs(deltaY) < BOUNCE_GUARD_THRESHOLD) {
      return
    }

    const atTop = el.scrollTop <= 1
    const atBottom = maxScrollTop - el.scrollTop <= 1

    if ((atTop && deltaY > 0) || (atBottom && deltaY < 0)) {
      event.preventDefault()
    }
  }

  el.addEventListener('touchstart', handleTouchStart, { passive: true })
  el.addEventListener('touchmove', handleTouchMove, { passive: false })

  return () => {
    el.removeEventListener('touchstart', handleTouchStart)
    el.removeEventListener('touchmove', handleTouchMove)
  }
}

onMounted(() => {
  nextTick(() => {
    pageCleanupFns.push(
      lockDocumentScroll(),
      bindDocumentElasticGuard(),
    )
    sectionCleanupFns.push(
      bindElasticScrollGuard(newHouseSection.value),
      bindElasticScrollGuard(secondHandSection.value),
    )
  })
})

onBeforeUnmount(() => {
  pageCleanupFns.splice(0).reverse().forEach((cleanup) => cleanup())
  sectionCleanupFns.splice(0).forEach((cleanup) => cleanup())
})

样式：页面锁溢出 + 内层唯一滚动

.page {
  min-height: 100vh;
  height: 100vh;
  min-height: 100dvh;
  height: 100dvh;
  overflow: hidden;
  display: flex;
  flex-direction: column;
  box-sizing: border-box;
  touch-action: pan-y;
  background: linear-gradient(180deg, #fe8647 0%, #ffffff 38vh);
}

.module-card {
  width: calc(100% - 20px);
  max-width: 1200px;
  flex: 1 1 auto;
  min-height: 0;
  margin: 16px auto 10px;
  padding: 20px 16px 20px;
  border: 1px solid rgba(255, 140, 66, 0.08);
  border-radius: 20px;
  background: rgba(255, 255, 255, 0.9);
  box-shadow: 0 14px 36px rgba(31, 35, 41, 0.06);
  overflow-y: auto;
  overflow-x: hidden;
  overscroll-behavior: none;
  overscroll-behavior-y: none;
  touch-action: pan-y;
  /* 刻意不加 `-webkit-overflow-scrolling: touch`：它会把本容器放到独立的合成滚动层，
     使上面两条 overscroll-behavior 失效，并让 bindDocumentElasticGuard 与
     bindElasticScrollGuard 中非 passive 的 preventDefault 在惯性阶段拦不住手势。
     iOS 13+ 的 overflow: auto 原生已有惯性滚动，无需该遗留属性。 */
  scrollbar-width: none;
  -ms-overflow-style: none;
}

4.7 小程序代码

pages.json（webview 页配置）

{
  "path": "webview/index",
  "style": {
    "navigationBarTitleText": "加载中",
    "navigationBarBackgroundColor": "#fe8647",
    "navigationBarTextStyle": "white",
    "disableScroll": true,
    "enablePullDownRefresh": false,
    "backgroundColor": "#fe8647",
    "backgroundColorTop": "#fe8647",
    "backgroundColorBottom": "#ffffff"
  }
}

subpkg-tool/webview/index.vue（全屏宿主页）

<template>
  <view class="webview-container">
    <page-loading :loading="pageLoading" />
    <web-view
      :src="url"
      :hidden="pageLoading"
      class="webview"
      @load="handleWebviewLoad"
      @error="handleWebviewError"
    ></web-view>
    <view class="safe-area-bottom"></view>
  </view>
</template>

<script>
import { guardPageAccess } from "@/utils/page-guard";
import pageLoading from "@/components/page-loading/index.vue";

const PAGE_URL = "/subpkg-tool/webview/index";

export default {
  components: {
    pageLoading,
  },
  data() {
    return {
      url: "",
      pageLoading: true,
    };
  },
  onLoad(options) {
    if (options.url) {
      this.url = decodeURIComponent(options.url);
    }
    if (options.title) {
      uni.setNavigationBarTitle({
        title: decodeURIComponent(options.title),
      });
    }

    guardPageAccess(PAGE_URL).then((allowed) => {
      if (!allowed) return;
    });
  },
  methods: {
    handleWebviewLoad() {
      this.pageLoading = false;
    },
    handleWebviewError() {
      this.pageLoading = false;
      uni.showToast({
        title: "页面加载失败",
        icon: "none",
      });
    },
  },
};
</script>

<style lang="scss" scoped>
.webview-container {
  height: 100vh;
  display: flex;
  flex-direction: column;
  box-sizing: border-box;
  background: #ffffff;
  overflow: hidden;
}

.webview {
  width: 100%;
  flex: 1 1 auto;
  display: block;
  overflow: hidden;
}

.safe-area-bottom {
  flex: 0 0 auto;
  height: constant(safe-area-inset-bottom);
  height: env(safe-area-inset-bottom);
  background: #ffffff;
}
</style>

5. 总结

本次 iOS 下拉漏白的根因是 web-view 内 WKWebView 整页橡皮筋，微信侧没有关闭 bounces 的官方能力，因此：

  1. 治本在 H5：锁定 html/body 文档滚动，在 document 捕获阶段拦截非滚动区与边界手势，滚动只收敛到 .module-card，并把 body 兜底色设为顶部主色 #fe8647；同时避免给滚动容器加 -webkit-overflow-scrolling: touch，以免手势拦截失效。
  2. 小程序只做辅助：disableScroll、关闭页面级下拉刷新、导航栏/页背景与 H5 头图主色对齐；宿主页保持全屏 web-view，不再尝试用普通 view 遮罩或小窗裁剪原生组件。
  3. 图表 tip：不挂 body，采用 confine: true + appendToBody: false + max-width:80%，并在滚动/触摸时主动 hideTip；优先防漂移，边缘轻微溢出可接受，尚未找到与挂 body 完全兼容的方案。
  4. 落地顺序：先发 H5 验证主因与 tip 行为，再按需发小程序配置；回归重点覆盖标题区/Tab 区下拉、列表到顶/触底、中部正常滚动、图表 tip 点击与滚动后位置，以及离开页面后其它 H5 路由不被污染。
    )
posted @ 2026-08-12 09:35  JocelynFung  阅读(33)  评论(0)    收藏  举报
Live2D 看板娘 / Demo