Scroll | Tuff Docs

Use native mode for plain article or document scrolling; reach for BetterScroll only when you need consistent scrollbars, wheel bridging, bounce, or pull plugins.
Keep scrollChaining=false in nested panels; enable it only when the parent-child handoff is intentional and tested.
Set noPadding when the child owns its spacing, such as virtualized lists, tables, and full-bleed media.
Give horizontal or both-axis content a definite width, or BetterScroll can't reliably detect horizontal overflow.
Don't pass large mutable objects through options; configure documented behavior through its props.

API Reference

Props

Prop	Type	Default	Description
`native`	`boolean`	`false`	Forces native scrolling and skips BetterScroll initialization.
`unified`	`boolean`	`false`	Forces BetterScroll over Safari / Chromium auto-native; `native` still wins.
`nativeAutoFallback`	`boolean`	`true`	Switches to native scrolling on macOS + Chromium `145+`; doesn't affect Safari.
`noPadding`	`boolean`	`false`	Removes content padding; horizontal and both-axis content becomes `max-content` wide.
`scrollChaining`	`boolean`	`false`	Hands scrolling to the outer container at the edges.
`direction`	`'vertical' \| 'horizontal' \| 'both'`	`'vertical'`	Scroll axes.
`scrollbar`	`boolean`	`true`	Enables the BetterScroll scrollbar plugin; native mode uses browser scrollbars.
`scrollbarFade`	`boolean`	`true`	Fades the scrollbar when idle.
`scrollbarInteractive`	`boolean`	`true`	Lets users drag the scrollbar.
`scrollbarAlwaysVisible`	`boolean`	`false`	Keeps the scrollbar visible, for bounce or content that fits.
`scrollbarMinSize`	`number`	`18`	Minimum thumb size, written to `--tx-scrollbar-min-size`.
`probeType`	`0 \| 1 \| 2 \| 3`	`3`	BetterScroll `probeType`; sets how often `scroll` fires.
`bounce`	`boolean`	`true`	Edge bounce and wheel overshoot.
`click`	`boolean`	`true`	Passes through BetterScroll's `click` option.
`wheel`	`boolean`	`true`	Wheel bridge in BetterScroll mode; ignores `ctrl` wheel gestures.
`refreshOnContentChange`	`boolean`	`true`	Calls `refresh()` after content changes.
`pullDownRefresh`	`boolean \| Record<string, unknown>`	`false`	Enables pull to refresh; an object becomes the BetterScroll plugin options.
`pullDownThreshold`	`number`	`70`	Pull distance that fires `pulling-down`.
`pullDownStop`	`number`	`56`	Hold position while refreshing; BetterScroll mode only.
`pullUpLoad`	`boolean \| Record<string, unknown>`	`false`	Enables load more; an object becomes the BetterScroll plugin options.
`pullUpThreshold`	`number`	`0`	Distance from the bottom that fires `pulling-up`.
`options`	`Record<string, unknown>`	`{}`	Extra BetterScroll options; the component consumes `wheelOvershoot` itself.

Events

Event	Params	Description
`scroll`	`{ scrollTop: number; scrollLeft: number }`	Fires on scroll with absolute offsets.
`pulling-down`	-	Fires on pull to refresh; not again until `finishPullDown()`.
`pulling-up`	-	Fires on load more; not again until `finishPullUp()`.

Slots

Slot	Description
`default`	Main content, rendered inside `.tx-scroll__content`.
`header`	Before the main content: ahead of `.tx-scroll__content` in native mode, inside it in BetterScroll mode.
`footer`	After the main content; often a loading status.

Exposed Methods

Name	Type	Description
`nativeScrollRef`	`Ref<HTMLElement \| null>`	The scroll element in native mode.
`scrollTo(x, y, time?)`	`(x: number, y: number, time?: number) => void`	Scrolls to absolute offsets; `time` applies in BetterScroll mode only.
`getScrollInfo()`	`() => TxScrollInfo`	Current offsets, scroll size, and client size.
`refresh()`	`() => void`	Recomputes BetterScroll's scrollable range; no-op in native mode.
`finishPullDown()`	`() => void`	Ends the current pull-down so it can fire again.
`finishPullUp()`	`() => void`	Ends the current pull-up so it can fire again.

Overview

The mode is chosen in order: native → unified (BetterScroll) → native on macOS Safari → native when nativeAutoFallback is on and macOS + Chromium ≥ 145 → otherwise BetterScroll.
Native mode maps direction to overflow-x/y and scrollChaining=false to overscroll-behavior: contain; BetterScroll mode maps it to scrollX, scrollY, and freeScroll.
Size and content changes are coalesced into one frame before refresh(); refreshOnContentChange=false turns off only the content-change refreshes, not the resize ones.
Native pull to refresh is a touch-threshold fallback at scrollTop=0.
On macOS, with both wheel and bounce on, useTransition: false is injected by default; set useTransition in options to override.

Technologies

BetterScroll mode lazy-loads @better-scroll/core and @better-scroll/scroll-bar; the wheel goes through the component's own bridge.
Source: packages/tuffex/packages/components/src/scroll/.

查看源码

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