Scroll 滚动 | Tuff Docs

属性名	类型	默认值	说明
`native`	`boolean`	`false`	强制原生滚动，跳过 BetterScroll 初始化。
`unified`	`boolean`	`false`	强制 BetterScroll，覆盖 Safari / Chromium 的自动原生；`native` 仍优先。
`nativeAutoFallback`	`boolean`	`true`	在 macOS + Chromium `145+` 上自动改用原生滚动；不影响 Safari。
`noPadding`	`boolean`	`false`	去掉内容内边距；横向与双轴时内容宽度为 `max-content`。
`scrollChaining`	`boolean`	`false`	到达边界后把滚动交给外层。
`direction`	`'vertical' \| 'horizontal' \| 'both'`	`'vertical'`	滚动轴向。
`scrollbar`	`boolean`	`true`	启用 BetterScroll 滚动条插件；原生模式用浏览器滚动条。
`scrollbarFade`	`boolean`	`true`	滚动条闲置时淡出。
`scrollbarInteractive`	`boolean`	`true`	允许拖拽滚动条。
`scrollbarAlwaysVisible`	`boolean`	`false`	滚动条常显，适合回弹或内容不足一屏的场景。
`scrollbarMinSize`	`number`	`18`	滑块最小尺寸，写入 `--tx-scrollbar-min-size`。
`probeType`	`0 \| 1 \| 2 \| 3`	`3`	BetterScroll `probeType`，决定 `scroll` 事件频率。
`bounce`	`boolean`	`true`	边界回弹与滚轮 overshoot。
`click`	`boolean`	`true`	透传 BetterScroll 的 `click` 选项。
`wheel`	`boolean`	`true`	BetterScroll 模式的滚轮桥接；忽略 `ctrl` 滚轮。
`refreshOnContentChange`	`boolean`	`true`	内容变更后自动 `refresh()`。
`pullDownRefresh`	`boolean \| Record<string, unknown>`	`false`	启用下拉刷新；对象作为 BetterScroll 插件选项。
`pullDownThreshold`	`number`	`70`	触发 `pulling-down` 的下拉距离。
`pullDownStop`	`number`	`56`	刷新时的停留位置，仅 BetterScroll 模式生效。
`pullUpLoad`	`boolean \| Record<string, unknown>`	`false`	启用上拉加载；对象作为 BetterScroll 插件选项。
`pullUpThreshold`	`number`	`0`	触发 `pulling-up` 的距底阈值。
`options`	`Record<string, unknown>`	`{}`	额外的 BetterScroll 选项；`wheelOvershoot` 由组件自行消费。

事件

事件名	参数	说明
`scroll`	`{ scrollTop: number; scrollLeft: number }`	滚动时触发，参数为绝对偏移。
`pulling-down`	-	下拉刷新时触发；`finishPullDown()` 之前不再触发。
`pulling-up`	-	上拉加载时触发；`finishPullUp()` 之前不再触发。

插槽

插槽名	说明
`default`	主内容，渲染在 `.tx-scroll__content` 内。
`header`	主内容之前；原生模式在 `.tx-scroll__content` 之前，BetterScroll 模式在其内。
`footer`	主内容之后，常放加载状态。

暴露方法

名称	类型	说明
`nativeScrollRef`	`Ref<HTMLElement \| null>`	原生模式下的滚动元素。
`scrollTo(x, y, time?)`	`(x: number, y: number, time?: number) => void`	滚动到绝对偏移；`time` 仅 BetterScroll 模式生效。
`getScrollInfo()`	`() => TxScrollInfo`	当前偏移、滚动尺寸与可视尺寸。
`refresh()`	`() => void`	重新计算 BetterScroll 的可滚动范围；原生模式无操作。
`finishPullDown()`	`() => void`	结束本轮下拉，允许再次触发。
`finishPullUp()`	`() => void`	结束本轮上拉，允许再次触发。

概述

模式按优先级决定：native → unified（BetterScroll）→ macOS Safari 用原生 → nativeAutoFallback 且 macOS + Chromium ≥ 145 用原生 → 其余用 BetterScroll。
原生模式把 direction 映射为 overflow-x/y，scrollChaining=false 映射为 overscroll-behavior: contain；BetterScroll 模式映射为 scrollX、scrollY 与 freeScroll。
尺寸与内容变化合并到同一帧再 refresh()；refreshOnContentChange=false 只关闭内容变更刷新，尺寸刷新保留。
原生模式的下拉刷新是 scrollTop=0 时基于触摸阈值的降级实现。
macOS 上同时开启 wheel 与 bounce 时默认注入 useTransition: false，可在 options 中覆盖。

技术实现

BetterScroll 模式按需加载 @better-scroll/core 与 @better-scroll/scroll-bar，滚轮由组件自己的桥接处理。
源码：packages/tuffex/packages/components/src/scroll/。

查看源码

packages/tuffex/packages/components/src/scroll/index.ts