@qingwu-ui/scroll-fab 0.9.0-beta.1 → 0.9.0-beta.3

package/README.md

@@ -0,0 +1,115 @@
+# @qingwu-ui/scroll-fab
+
+[青梧UI](https://github.com/apricotdream/qingwu-ui) 的 **悬浮滚动栏** —— 框架无关，纯 DOM + CSS，零强依赖。
+
+- **绕圈翻转**：桌面悬停 / 触屏按住推进描边进度，绕满一圈在「滚动到底部 / 返回顶部」间纯切换（不附带滚动），未绕满移开/松手则描边衰减倒转
+- **点击与描边正交**：轻点恒直接执行当前模式动作；触屏绕满后的释放被消费，避免同一手势既翻转又滚动
+- **键盘语义正确**：Enter/Space 执行当前模式动作（原生按钮激活）；双模式下方向键 `ArrowUp/ArrowDown` 翻转模式
+- **单模式 / 阈值显隐**：`modes` 允许只跑「返回顶部」，`showThreshold` 滚过阈值才出现、不打扰首屏
+- **进度回调**：`onScroll(pct)` 实时吐出 0..1 滚动进度
+- **Lenis 可插拔**：内置 rAF 缓动，可选接入 [Lenis](https://github.com/darkroomengineering/lenis)（未安装静默回退）
+- **异形形状**：银杏叶等自定义外形，进度描边沿外扩轮廓完全包裹
+- 程序滚动支持 wheel / touch / keydown 打断、懒加载变长追击
+- 移动端一等支持：Pointer Events 单路径、ghost click 抑制、safe-area 定位、44px 命中下限
+- 尊重 `prefers-reduced-motion`；window 与自定义容器双支持
+
+## 安装
+
+```bash
+npm install @qingwu-ui/scroll-fab
+# 可选：启用 Lenis 平滑滚动
+npm install lenis
+```
+
+## 使用
+
+```ts
+import { ScrollFab } from "@qingwu-ui/scroll-fab";
+import "@qingwu-ui/scroll-fab/style.css";
+
+// 零配置：右下角圆形悬浮栏
+const fab = new ScrollFab();
+
+// 销毁
+fab.destroy();
+```
+
+### 接入 Lenis
+
+```ts
+// ① 自建实例（仅驱动按钮程序滚动，不劫持页面滚轮）
+new ScrollFab({
+  lenis: true,
+  onLenisReady: (lenis) => console.log("Lenis 就绪", lenis),
+});
+
+// ② 透传 Lenis 配置（target 容器自动映射为 wrapper）
+new ScrollFab({ lenis: { duration: 1.1 } });
+
+// ③ 复用宿主已有的 Lenis 实例（组件永不销毁它）
+const lenis = new Lenis();
+new ScrollFab({ lenis });
+```
+
+未安装 `lenis` 时自动回退内置 rAF，无任何报错。
+
+### 异形形状（银杏叶等）
+
+进度要「完全包裹」形状必须用双 path：`fill` 是叶片实体，`outline` 是外扩一圈的闭合轮廓（SVG 描边居中于路径，单 path 会有一半笔画压进形状内部）。
+
+```ts
+const LEAF = "M24 46 L23.2 34 C16 33 9 28 7 20 Z /* …完整 path d… */";
+
+new ScrollFab({
+  shape: {
+    fill: LEAF,
+    outline: LEAF, // 与 fill 同形
+    outlineTransform: "translate(24 24) scale(1.13) translate(-24 -24)",
+  },
+});
+```
+
+异形模式下圆形外壳自动退场（背景/边框/圆角），阴影改用 `drop-shadow` 跟随叶片真实形状；命中区仍为矩形以保证 44px 触控目标。
+
+### 单模式 / 阈值显隐 / 进度回调
+
+```ts
+// 只跑「返回顶部」：首屏不打扰，滚过 400px 才出现；实时读滚动进度
+new ScrollFab({
+  modes: ["to-top"],
+  showThreshold: 400,
+  onScroll: (pct) => console.log(`${Math.round(pct * 100)}%`),
+});
+```
+
+单模式没有绕环翻转与描边，视觉上即普通按钮；键盘 Enter/Space 执行动作。
+
+## API
+
+```ts
+new ScrollFab(options?: ScrollFabOptions): ScrollFab
+
+interface ScrollFabOptions {
+  target?: HTMLElement | null;          // 滚动容器，默认 window
+  size?: number;                        // 直径 px，默认 48（最小 44）
+  ringDuration?: number;                // 绕圈时长 ms，默认 800
+  decayDuration?: number;               // 衰减倒转 ms，默认 300
+  cancelThreshold?: number;             // 触屏位移放弃阈值 px，默认 10
+  content?: string | HTMLElement;       // 中心内容，默认方向箭头
+  position?: ScrollFabPosition;         // 悬浮位置，默认右下 24/24
+  zIndex?: number;                      // 默认 9999
+  className?: string;
+  animate?: boolean;                    // 默认 true
+  lenis?: boolean | ScrollFabLenisConfig | LenisLike;
+  shape?: ScrollFabShape;
+  onLenisReady?: (lenis: LenisLike) => void;
+  ariaLabelToBottom?: string;
+  ariaLabelToTop?: string;
+  onModeChange?: (mode: "to-bottom" | "to-top") => void;
+  modes?: ("to-bottom" | "to-top")[];    // 缺省双模式；初始取首项；单模式无绕环/描边；空配置抛 TypeError
+  showThreshold?: number;                 // 显示所需最小 scrollPos px，默认 0（行为不变），负数按 0
+  onScroll?: (pct: number) => void;       // 0..1 小数，rAF 节流，隐藏期间照吐，构造/refresh 后补发
+}
+```
+
+实例方法：`scrollToBottom()` / `scrollToTop()` / `refresh()` / `destroy()`；只读属性 `currentMode`、`el`。

package/dist/index.cjs

@@ -74,19 +74,28 @@ S16("<path d=\"m9 18 6-6-6-6\"/>");
 //#endregion
 //#region src/scroll-fab.ts
 /** 青梧UI ScrollFab 悬浮滚动栏：默认“滚动到底部”，桌面悬停/触屏按住绕满描边一圈翻转为“返回顶部”，点击（轻点）直接执行当前模式动作 */
+const SVG_NS = "http://www.w3.org/2000/svg";
 const RADIUS = 21;
+const FALLBACK_PATH_LEN = 100;
 const DEFAULT_LABEL_BOTTOM = "滚动到底部（悬停或按住绕圈可切换为返回顶部）";
 const DEFAULT_LABEL_TOP = "返回顶部（悬停或按住绕圈可切换为滚动到底部）";
+const STATIC_LABEL_BOTTOM = "滚动到底部";
+const STATIC_LABEL_TOP = "返回顶部";
 function easeInOutCubic(p) {
 	return p < .5 ? 4 * p * p * p : 1 - (-2 * p + 2) ** 3 / 2;
 }
+function isLenisInstance(v) {
+	return typeof v === "object" && v !== null && typeof v.scrollTo === "function";
+}
 var ScrollFab = class {
 	el;
 	ring;
 	track;
+	fillPath = null;
 	icon;
 	len;
 	targetEl;
+	shape;
 	ringMs;
 	decayMs;
 	cancelPx;
@@ -94,7 +103,18 @@ var ScrollFab = class {
 	labelBottom;
 	labelTop;
 	onModeChange;
-	mode = "to-bottom";
+	onLenisReady;
+	onScroll;
+	modes;
+	single;
+	threshold;
+	/** 外部注入：宿主实例，组件永不销毁 */
+	externalLenis = null;
+	/** 自建配置：null = 不走 lenis；true 形态也归一成对象 */
+	ownLenisConfig = null;
+	ownLenis = null;
+	ownLenisPromise = null;
+	mode;
 	progress = 0;
 	hovering = false;
 	pressing = false;
@@ -105,41 +125,79 @@ var ScrollFab = class {
 	ringRaf = null;
 	lastTs = null;
 	scrollRaf = null;
+	lenisLoopRaf = null;
+	lenisScrolling = false;
+	lenisDest = null;
 	flashTimer = null;
 	tapResetTimer = null;
 	touchTap = false;
 	ro = null;
+	actionSeq = 0;
+	destroyed = false;
+	emitRaf = null;
+	lastPct = -1;
 	constructor(options = {}) {
 		this.targetEl = options.target ?? null;
+		this.shape = options.shape ?? null;
 		this.ringMs = Math.max(100, Math.min(5e3, options.ringDuration ?? 800));
 		this.decayMs = Math.max(100, options.decayDuration ?? 300);
 		this.cancelPx = Math.max(4, options.cancelThreshold ?? 10);
 		this.animate = options.animate ?? true;
-		this.labelBottom = options.ariaLabelToBottom ?? DEFAULT_LABEL_BOTTOM;
-		this.labelTop = options.ariaLabelToTop ?? DEFAULT_LABEL_TOP;
+		this.threshold = Math.max(0, options.showThreshold ?? 0);
 		this.onModeChange = options.onModeChange;
+		this.onLenisReady = options.onLenisReady;
+		this.onScroll = options.onScroll;
+		this.modes = this.normalizeModes(options.modes);
+		this.single = this.modes.length === 1;
+		this.mode = this.modes[0];
+		this.labelBottom = options.ariaLabelToBottom ?? (this.single ? STATIC_LABEL_BOTTOM : DEFAULT_LABEL_BOTTOM);
+		this.labelTop = options.ariaLabelToTop ?? (this.single ? STATIC_LABEL_TOP : DEFAULT_LABEL_TOP);
+		if (isLenisInstance(options.lenis)) this.externalLenis = options.lenis;
+		else if (options.lenis != null && options.lenis !== false) {
+			const cfg = options.lenis === true ? {} : options.lenis;
+			this.ownLenisConfig = {
+				smoothWheel: false,
+				...cfg
+			};
+		}
 		this.el = document.createElement("button");
 		this.el.type = "button";
 		this.el.className = `qsf-root${options.className ? ` ${options.className}` : ""}`;
 		this.el.dataset.mode = this.mode;
-		this.el.setAttribute("aria-label", this.labelBottom);
+		if (this.shape) this.el.dataset.shape = "on";
+		this.el.setAttribute("aria-label", this.mode === "to-bottom" ? this.labelBottom : this.labelTop);
 		this.el.style.setProperty("--qsf-size", `${Math.max(44, options.size ?? 48)}px`);
 		if (options.zIndex != null) this.el.style.setProperty("--qsf-z", String(options.zIndex));
 		if (options.position?.right != null) this.el.style.setProperty("--qsf-right", `${options.position.right}px`);
 		if (options.position?.bottom != null) this.el.style.setProperty("--qsf-bottom", `${options.position.bottom}px`);
 		if (options.position?.left != null) this.el.style.setProperty("--qsf-left", `${options.position.left}px`);
 		if (options.position?.top != null) this.el.style.setProperty("--qsf-top", `${options.position.top}px`);
-		const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+		const svg = document.createElementNS(SVG_NS, "svg");
 		svg.setAttribute("class", "qsf-svg");
-		svg.setAttribute("viewBox", "0 0 48 48");
+		svg.setAttribute("viewBox", this.shape?.viewBox ?? "0 0 48 48");
 		svg.setAttribute("aria-hidden", "true");
-		this.track = this.makeCircle("qsf-track");
-		this.ring = this.makeCircle("qsf-bar");
-		svg.append(this.track, this.ring);
-		let len = 2 * Math.PI * RADIUS;
+		if (this.shape) {
+			this.fillPath = document.createElementNS(SVG_NS, "path");
+			this.fillPath.setAttribute("class", "qsf-shape-fill");
+			this.fillPath.setAttribute("d", this.shape.fill);
+			this.track = this.makePath("qsf-track", this.shape.outline);
+			this.ring = this.makePath("qsf-bar", this.shape.outline);
+			if (this.shape.outlineTransform) {
+				this.track.setAttribute("transform", this.shape.outlineTransform);
+				this.ring.setAttribute("transform", this.shape.outlineTransform);
+			}
+			svg.append(this.fillPath, this.track, this.ring);
+		} else {
+			this.track = this.makeCircle("qsf-track");
+			this.ring = this.makeCircle("qsf-bar");
+			svg.append(this.track, this.ring);
+		}
+		let len;
+		if (this.shape) len = FALLBACK_PATH_LEN;
+		else len = 2 * Math.PI * RADIUS;
 		try {
 			const measured = this.ring.getTotalLength();
-			if (Number.isFinite(measured)) len = measured;
+			if (Number.isFinite(measured) && measured > 0) len = measured;
 		} catch {}
 		this.len = len;
 		this.ring.style.strokeDasharray = String(this.len);
@@ -152,12 +210,14 @@ var ScrollFab = class {
 		else this.icon.innerHTML = ICON_CHEVRON_DOWN;
 		this.el.append(svg, this.icon);
 		document.body.append(this.el);
-		this.el.addEventListener("pointerenter", this.onEnter);
-		this.el.addEventListener("pointerleave", this.onLeave);
-		this.el.addEventListener("pointerdown", this.onDown);
-		this.el.addEventListener("pointermove", this.onMove);
-		this.el.addEventListener("pointerup", this.onUp);
-		this.el.addEventListener("pointercancel", this.onCancel);
+		if (!this.single) {
+			this.el.addEventListener("pointerenter", this.onEnter);
+			this.el.addEventListener("pointerleave", this.onLeave);
+			this.el.addEventListener("pointerdown", this.onDown);
+			this.el.addEventListener("pointermove", this.onMove);
+			this.el.addEventListener("pointerup", this.onUp);
+			this.el.addEventListener("pointercancel", this.onCancel);
+		}
 		this.el.addEventListener("keydown", this.onKey);
 		this.el.addEventListener("click", this.onClick);
 		window.addEventListener("resize", this.onRecheck);
@@ -167,48 +227,73 @@ var ScrollFab = class {
 			this.ro.observe(this.targetEl ?? document.documentElement);
 		}
 		this.syncVisible();
+		this.emitScroll();
 	}
 	/** 当前模式 */
 	get currentMode() {
 		return this.mode;
 	}
-	/** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估） */
+	/** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估），并强制补发一次进度 */
 	refresh() {
-		this.onRecheck();
+		this.syncVisible();
+		this.lastPct = -1;
+		this.emitScroll();
 	}
 	scrollToBottom() {
 		this.animateScroll("bottom");
 	}
 	scrollToTop() {
-		this.scrollTo(0);
+		this.animateScroll("top");
 	}
 	destroy() {
-		this.el.removeEventListener("pointerenter", this.onEnter);
-		this.el.removeEventListener("pointerleave", this.onLeave);
-		this.el.removeEventListener("pointerdown", this.onDown);
-		this.el.removeEventListener("pointermove", this.onMove);
-		this.el.removeEventListener("pointerup", this.onUp);
-		this.el.removeEventListener("pointercancel", this.onCancel);
+		this.destroyed = true;
+		if (!this.single) {
+			this.el.removeEventListener("pointerenter", this.onEnter);
+			this.el.removeEventListener("pointerleave", this.onLeave);
+			this.el.removeEventListener("pointerdown", this.onDown);
+			this.el.removeEventListener("pointermove", this.onMove);
+			this.el.removeEventListener("pointerup", this.onUp);
+			this.el.removeEventListener("pointercancel", this.onCancel);
+		}
 		this.el.removeEventListener("keydown", this.onKey);
 		this.el.removeEventListener("click", this.onClick);
 		window.removeEventListener("resize", this.onRecheck);
 		(this.targetEl ?? window).removeEventListener("scroll", this.onRecheck);
 		this.ro?.disconnect();
 		this.cancelScroll();
+		this.stopLenisLoop();
+		this.ownLenis?.destroy?.();
+		this.ownLenis = null;
 		if (this.ringRaf != null) cancelAnimationFrame(this.ringRaf);
 		this.ringRaf = null;
+		if (this.emitRaf != null) cancelAnimationFrame(this.emitRaf);
+		this.emitRaf = null;
 		if (this.flashTimer != null) clearTimeout(this.flashTimer);
 		if (this.tapResetTimer != null) clearTimeout(this.tapResetTimer);
 		this.el.remove();
 	}
+	/** 规范化 modes：缺省双模式；去重、过滤非法值；结果为空直接抛错 */
+	normalizeModes(input) {
+		if (!input) return ["to-bottom", "to-top"];
+		const out = [];
+		for (const m of input) if ((m === "to-bottom" || m === "to-top") && !out.includes(m)) out.push(m);
+		if (out.length === 0) throw new TypeError("ScrollFab: modes 至少需要一个有效模式（'to-bottom' | 'to-top'）");
+		return out;
+	}
 	makeCircle(cls) {
-		const c = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+		const c = document.createElementNS(SVG_NS, "circle");
 		c.setAttribute("class", cls);
 		c.setAttribute("cx", "24");
 		c.setAttribute("cy", "24");
 		c.setAttribute("r", String(RADIUS));
 		return c;
 	}
+	makePath(cls, d) {
+		const p = document.createElementNS(SVG_NS, "path");
+		p.setAttribute("class", cls);
+		p.setAttribute("d", d);
+		return p;
+	}
 	onEnter = (e) => {
 		if (e.pointerType !== "mouse") return;
 		this.hovering = true;
@@ -268,9 +353,12 @@ var ScrollFab = class {
 		this.doAction();
 	};
 	onKey = (e) => {
-		if (e.repeat || e.key !== "Enter" && e.key !== " ") return;
+		if (e.repeat || e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
+		if (this.single) return;
+		const want = e.key === "ArrowUp" ? "to-top" : "to-bottom";
+		if (want === this.mode) return;
 		e.preventDefault();
-		this.setMode(this.mode === "to-bottom" ? "to-top" : "to-bottom");
+		this.setMode(want);
 	};
 	holding() {
 		return this.hovering || this.pressing;
@@ -322,12 +410,110 @@ var ScrollFab = class {
 		this.animateScroll(this.mode === "to-bottom" ? "bottom" : "top");
 	}
 	animateScroll(dest) {
+		++this.actionSeq;
 		this.cancelScroll();
 		if (!this.animate || this.reducedMotion()) {
 			this.setScrollPos(this.targetPos(dest));
 			return;
 		}
-		this.attachInterrupt();
+		if (this.externalLenis) {
+			this.scrollWithLenis(this.externalLenis, dest, false);
+			return;
+		}
+		if (this.ownLenisConfig) {
+			const seq = ++this.actionSeq;
+			this.resolveOwnLenis().then((lenis) => {
+				if (this.destroyed || seq !== this.actionSeq) return;
+				if (lenis) this.scrollWithLenis(lenis, dest, true);
+				else this.animateRaf(dest);
+			});
+			return;
+		}
+		this.animateRaf(dest);
+	}
+	/** 首次点击时动态 import lenis 并自建实例；未安装（或加载失败）→ null 永久回退 rAF */
+	resolveOwnLenis() {
+		if (this.ownLenis) return Promise.resolve(this.ownLenis);
+		if (this.ownLenisPromise) return this.ownLenisPromise;
+		this.ownLenisPromise = import("lenis").then((mod) => {
+			const LenisCtor = mod.default ?? mod;
+			const cfg = { ...this.ownLenisConfig };
+			if (this.targetEl) cfg.wrapper = this.targetEl;
+			this.ownLenis = new LenisCtor(cfg);
+			this.onLenisReady?.(this.ownLenis);
+			return this.ownLenis;
+		}).catch(() => {
+			this.ownLenisConfig = null;
+			this.ownLenisPromise = null;
+			return null;
+		});
+		return this.ownLenisPromise;
+	}
+	/**
+	* 用 Lenis 执行程序滚动。
+	* 自建实例（own）：组件自跑 raf loop（Lenis 需外部驱动 raf），保留 wheel/touch/keydown 打断与到底追击；
+	* 外部实例：宿主自带 raf loop 与手势处理，组件只发 scrollTo，不追击不打断。
+	*/
+	scrollWithLenis(lenis, dest, own) {
+		const immediate = !this.animate || this.reducedMotion();
+		const target = this.targetPos(dest);
+		this.lenisDest = dest;
+		if (own) {
+			lenis.start?.();
+			lenis.scrollTo(target, {
+				immediate,
+				onComplete: () => this.endLenisScroll()
+			});
+			if (!immediate) {
+				this.lenisScrolling = true;
+				this.attachInterrupt();
+				this.startLenisLoop(lenis, dest);
+			} else this.endLenisScroll();
+		} else {
+			lenis.scrollTo(target, { immediate });
+			this.lenisDest = null;
+		}
+	}
+	/** 自建实例的 raf 驱动 + 懒加载到底追击（对齐内置 rAF 语义） */
+	startLenisLoop(lenis, dest) {
+		let lastEnd = this.targetPos(dest);
+		const loop = (time) => {
+			if (!this.lenisScrolling) return;
+			if (dest === "bottom") {
+				const live = this.targetPos("bottom");
+				if (Math.abs(live - lastEnd) > 2) {
+					lastEnd = live;
+					lenis.scrollTo(live, {
+						force: true,
+						onComplete: () => this.endLenisScroll()
+					});
+				}
+			}
+			lenis.raf?.(time);
+			this.lenisLoopRaf = requestAnimationFrame(loop);
+		};
+		this.lenisLoopRaf = requestAnimationFrame(loop);
+	}
+	stopLenisLoop() {
+		if (this.lenisLoopRaf != null) {
+			cancelAnimationFrame(this.lenisLoopRaf);
+			this.lenisLoopRaf = null;
+		}
+	}
+	/** 打断自建 Lenis 程序滚动：stop 冻结动画（下次发起前 start 复位） */
+	onLenisInterrupt = () => {
+		if (!this.lenisScrolling) return;
+		this.ownLenis?.stop?.();
+		this.endLenisScroll();
+	};
+	endLenisScroll() {
+		this.lenisScrolling = false;
+		this.lenisDest = null;
+		this.stopLenisLoop();
+		this.detachInterrupt();
+	}
+	animateRaf(dest) {
+		this.attachRafInterrupt();
 		let init = false;
 		let start = 0;
 		let end = 0;
@@ -354,7 +540,7 @@ var ScrollFab = class {
 			if (p < 1) this.scrollRaf = requestAnimationFrame(step);
 			else {
 				this.scrollRaf = null;
-				this.detachInterrupt();
+				this.detachRafInterrupt();
 			}
 		};
 		this.scrollRaf = requestAnimationFrame(step);
@@ -368,15 +554,33 @@ var ScrollFab = class {
 	interruptSource() {
 		return this.targetEl ?? window;
 	}
+	/** 自建 Lenis 路线的打断监听 */
 	attachInterrupt() {
 		const src = this.interruptSource();
 		for (const ev of [
 			"wheel",
 			"touchstart",
 			"keydown"
-		]) src.addEventListener(ev, this.onInterrupt, { passive: true });
+		]) src.addEventListener(ev, this.onLenisInterrupt, { passive: true });
 	}
 	detachInterrupt() {
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) src.removeEventListener(ev, this.onLenisInterrupt);
+	}
+	/** 内置 rAF 路线的打断监听 */
+	attachRafInterrupt() {
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) src.addEventListener(ev, this.onInterrupt, { passive: true });
+	}
+	detachRafInterrupt() {
 		const src = this.interruptSource();
 		for (const ev of [
 			"wheel",
@@ -389,7 +593,16 @@ var ScrollFab = class {
 			cancelAnimationFrame(this.scrollRaf);
 			this.scrollRaf = null;
 		}
-		this.detachInterrupt();
+		if (this.lenisScrolling) this.endLenisScroll();
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) {
+			src.removeEventListener(ev, this.onInterrupt);
+			src.removeEventListener(ev, this.onLenisInterrupt);
+		}
 	}
 	maxScroll() {
 		if (this.targetEl) return Math.max(0, this.targetEl.scrollHeight - this.targetEl.clientHeight);
@@ -406,14 +619,28 @@ var ScrollFab = class {
 		if (this.targetEl) this.targetEl.scrollTop = v;
 		else window.scrollTo(0, v);
 	}
-	scrollTo(v) {
-		this.animateScroll(v === 0 ? "top" : "bottom");
-	}
 	onRecheck = () => {
 		this.syncVisible();
+		this.scheduleScroll();
 	};
 	syncVisible() {
-		this.el.hidden = this.maxScroll() <= 1;
+		this.el.hidden = this.maxScroll() <= 1 || this.scrollPos() < this.threshold;
+	}
+	/** rAF 节流：一帧内多次重估只吐一次；按钮隐藏期间照常调度 */
+	scheduleScroll() {
+		if (this.emitRaf != null || this.destroyed) return;
+		this.emitRaf = requestAnimationFrame(() => {
+			this.emitRaf = null;
+			this.emitScroll();
+		});
+	}
+	emitScroll() {
+		if (this.destroyed) return;
+		const max = this.maxScroll();
+		const pct = max <= 0 ? 0 : Math.min(1, Math.max(0, this.scrollPos() / max));
+		if (pct === this.lastPct) return;
+		this.lastPct = pct;
+		this.onScroll?.(pct);
 	}
 };
 //#endregion