Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(mobile): 图片查看器拖动与缩放加入边缘弹性和惯性 (#5708)

Dash3744122eb3d7
diff --git a/apps/mobile/src/__tests__/imageLightboxInteraction.test.tsx b/apps/mobile/src/__tests__/imageLightboxInteraction.test.tsx
index 70ece03b10..6d93793be8 100644
--- a/apps/mobile/src/__tests__/imageLightboxInteraction.test.tsx
+++ b/apps/mobile/src/__tests__/imageLightboxInteraction.test.tsx
@@ -18,7 +18,11 @@ type GestureNode = {
handlers: Record<string, Handler>;
children?: GestureNode[];
};
-type Animation = { target: number; done?: (finished: boolean) => void };
+type Animation = {
+ target: number;
+ done?: (finished: boolean) => void;
+ decay?: { velocity: number; clamp: [number, number]; rubberBandEffect?: boolean };
+};
type Value = { value: number; animation?: Animation };
const runtime = vi.hoisted(() => ({
nodes: new Map<string, any>(),
@@ -181,6 +185,12 @@ vi.mock("react-native-reanimated", async () => {
cancelAnimation: cancel,
withTiming: timing,
withSpring: timing,
+ // 惯性滑行:测试里按速度方向直接落到 clamp 端点。
+ withDecay: (decay: NonNullable<Animation["decay"]>, done?: Animation["done"]) => ({
+ target: decay.velocity > 0 ? decay.clamp[1] : decay.clamp[0],
+ done,
+ decay,
+ }),
};
});
@@ -424,6 +434,163 @@ describe("image viewer gesture lifecycle", () => {
expect(transform().x).toBe(-195);
});
+ // 双击右下角后:2.5x,T=(-195,-375);未知尺寸按 400×800 铺满,溢出 x=300、y=600。
+ it("keeps following a zoomed pan past the image edge and springs back on release", () => {
+ mount();
+ doubleTapAtCorner();
+ finishAnimations();
+ fire(pan(), "onStart");
+ fire(pan(), "onChange", { changeX: -200, changeY: 0 });
+ const stretched = transform().x;
+ expect(stretched).toBeLessThan(-300);
+ expect(stretched).toBeGreaterThan(-395);
+ // 往回拖同样的距离回到原处,越界段不吞位移
+ fire(pan(), "onChange", { changeX: 200, changeY: 0 });
+ expect(transform().x).toBeCloseTo(-195, 6);
+ fire(pan(), "onChange", { changeX: -200, changeY: 0 });
+ fire(pan(), "onFinalize", { velocityX: 0, velocityY: 0 });
+ finishAnimations();
+ expect(transform()).toEqual({ x: -300, y: -375, scale: 2.5 });
+ });
+
+ it("flings with inertia inside the bounds and a touch catches it in place", () => {
+ mount();
+ doubleTapAtCorner();
+ finishAnimations();
+ fire(pan(), "onStart");
+ fire(pan(), "onChange", { changeX: 10, changeY: 0 });
+ fire(pan(), "onFinalize", { velocityX: 1500, velocityY: 0 });
+ const fling = runtime.values.find((v) => v.animation?.decay)?.animation?.decay;
+ expect(fling).toEqual({ velocity: 1500, clamp: [-300, 300], rubberBandEffect: true });
+ const fail = vi.fn();
+ act(() => pan().handlers.onTouchesDown({}, { fail }));
+ expect(fail).not.toHaveBeenCalled();
+ expect(runtime.values.some((v) => v.animation?.decay)).toBe(false);
+ // 接住后没拖就抬手:在边界内原地停住,不再滑也不回弹
+ const caught = transform();
+ fire(pan(), "onFinalize", {}, false);
+ finishAnimations();
+ expect(transform()).toEqual(caught);
+ });
+
+ it("lets a pinch overshoot the max zoom and settles back around the fingers", () => {
+ mount();
+ doubleTapAtCorner();
+ finishAnimations();
+ // 焦点相对中心 (50,-100),其下图片点 p = (F - T) / 2.5 = (98, 110)
+ fire(pinch(), "onStart", { focalX: 250, focalY: 300 });
+ fire(pinch(), "onChange", { focalX: 250, focalY: 300, scale: 2.4 });
+ expect(transform().scale).toBeGreaterThan(4);
+ expect(transform().scale).toBeLessThan(6);
+ fire(pinch(), "onFinalize");
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(false);
+ finishAnimations();
+ const settled = transform();
+ expect(settled.scale).toBe(4);
+ expect(settled.x + 98 * settled.scale).toBeCloseTo(50, 6);
+ expect(settled.y + 110 * settled.scale).toBeCloseTo(-100, 6);
+ });
+
+ it("zooms a second pinch around the fingers, not the stale screen focal", () => {
+ mount();
+ doubleTapAtCorner();
+ finishAnimations();
+ fire(pinch(), "onStart", { focalX: 250, focalY: 300 });
+ fire(pinch(), "onChange", { focalX: 250, focalY: 300, scale: 1.2 });
+ fire(pinch(), "onFinalize");
+ finishAnimations();
+ const after = transform();
+ expect(after.scale).toBe(3);
+ expect(after.x + 98 * after.scale).toBeCloseTo(50, 6);
+ expect(after.y + 110 * after.scale).toBeCloseTo(-100, 6);
+ });
+
+ it("keeps the point under the fingers when pinching during an edge rebound", () => {
+ mount();
+ doubleTapAtCorner();
+ finishAnimations();
+ // 拖过左边缘松手:回弹尚未落定
+ fire(pan(), "onStart");
+ fire(pan(), "onChange", { changeX: -200, changeY: 0 });
+ fire(pan(), "onFinalize", { velocityX: 0, velocityY: 0 });
+ const start = transform();
+ expect(start.x).toBeLessThan(-300);
+ // 回弹途中在屏幕中心捏到 4x:中心下的图片点 p = (0 - T) / 2.5
+ const pointX = -start.x / 2.5;
+ fire(pinch(), "onStart", { focalX: 200, focalY: 400 });
+ fire(pinch(), "onChange", { focalX: 200, focalY: 400, scale: 1.6 });
+ fire(pinch(), "onFinalize");
+ finishAnimations();
+ const settled = transform();
+ expect(settled.scale).toBe(4);
+ expect(settled.x + pointX * settled.scale).toBeCloseTo(0, 6);
+ });
+
+ it("lets a pinch shrink below 1x and springs back to the fitted image", () => {
+ mount();
+ fire(pinch(), "onStart", { focalX: 200, focalY: 400 });
+ fire(pinch(), "onChange", { focalX: 220, focalY: 420, scale: 0.5 });
+ expect(transform().scale).toBeLessThan(1);
+ expect(transform().scale).toBeGreaterThan(0.5);
+ fire(pinch(), "onFinalize");
+ // 回弹到 1x 落定前不放开翻页:快速横划不能在回弹中途切走当前图。
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(false);
+ finishAnimations();
+ expect(transform()).toEqual({ x: 0, y: 0, scale: 1 });
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(true);
+ });
+
+ it("unlocks paging after a synchronous settle under reduced motion", () => {
+ runtime.immediate = true;
+ mount();
+ fire(pinch(), "onStart", { focalX: 200, focalY: 400 });
+ fire(pinch(), "onChange", { focalX: 220, focalY: 420, scale: 0.5 });
+ fire(pinch(), "onFinalize");
+ expect(transform()).toEqual({ x: 0, y: 0, scale: 1 });
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(true);
+ });
+
+ it("keeps settling into the new bounds when the image size arrives mid-spring", () => {
+ mount();
+ doubleTapAtCorner();
+ finishAnimations();
+ fire(pinch(), "onStart", { focalX: 250, focalY: 300 });
+ fire(pinch(), "onChange", { focalX: 250, focalY: 300, scale: 2.4 });
+ fire(pinch(), "onFinalize");
+ // 横图 1600×900 contain 后 400×225:4x 时纵向溢出只剩 (900-800)/2 = 50
+ act(() => runtime.nodes.get("Image").onLoad({ source: { width: 1600, height: 900 } }));
+ finishAnimations();
+ const settled = transform();
+ expect(settled.scale).toBe(4);
+ expect(Math.abs(settled.y)).toBeLessThanOrEqual(50);
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(false);
+ });
+
+ it("unlocks paging when the image size arrives during a translation-only settle at 1x", () => {
+ mount();
+ // 倍率未变、只有焦点漂移:松手只回弹位移
+ fire(pinch(), "onStart", { focalX: 200, focalY: 400 });
+ fire(pinch(), "onChange", { focalX: 260, focalY: 400, scale: 1 });
+ fire(pinch(), "onFinalize");
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(false);
+ act(() => runtime.nodes.get("Image").onLoad({ source: { width: 1600, height: 900 } }));
+ finishAnimations();
+ expect(transform()).toEqual({ x: 0, y: 0, scale: 1 });
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(true);
+ });
+
+ it("keeps the native edge bounce available for a single image at 1x", () => {
+ const url = "https://example.invalid/solo.png";
+ mount({
+ images: [{
+ key: "solo", url, title: "Solo", subtitle: "",
+ payload: { kind: "media", media: { kind: "image", url, previewable: true } },
+ } as ImageLightboxProps["images"][number]],
+ initialUrl: url,
+ });
+ expect(runtime.nodes.get("FlatList").scrollEnabled).toBe(true);
+ });
+
it("does not accept dragging as the second tap", () => {
mount();
expect(doubleTap().options.maxDistance).toBe(12);
diff --git a/apps/mobile/src/__tests__/imageLightboxModel.test.ts b/apps/mobile/src/__tests__/imageLightboxModel.test.ts
index de53f5357c..d88cd9f09e 100644
--- a/apps/mobile/src/__tests__/imageLightboxModel.test.ts
+++ b/apps/mobile/src/__tests__/imageLightboxModel.test.ts
@@ -7,9 +7,8 @@ import {
bakeLightboxOrigin,
canShareLightboxImage,
compensateLightboxOrigin,
- clampLightboxScale,
clampLightboxTranslation,
- clampLightboxVisualPan,
+ dragLightboxVisualPan,
isLightboxZoomed,
lightboxBackgroundOpacity,
lightboxContainedSize,
@@ -19,18 +18,117 @@ import {
lightboxPageIndex,
lightboxPageLabel,
lightboxPanOverflow,
+ lightboxPanRelease,
+ lightboxPinchAnchor,
lightboxPinchOrigin,
+ lightboxPinchSettle,
+ lightboxPinchTranslation,
+ lightboxRubberBand,
+ lightboxRubberBandInverse,
nextDoubleTapScale,
reclampLightboxPan,
+ rubberBandLightboxScale,
+ rubberBandLightboxTranslation,
+ rubberBandLightboxVisualPan,
shouldCloseLightboxOnTap,
shouldDismissLightbox,
+ unrubberLightboxScale,
+ unrubberLightboxTranslation,
+ unrubberLightboxVisualPan,
} from '@/session/imageLightboxModel';
describe('imageLightboxModel', () => {
- it('clamps scale into [min, max]', () => {
- expect(clampLightboxScale(0.3)).toBe(LIGHTBOX_MIN_SCALE);
- expect(clampLightboxScale(2)).toBe(2);
- expect(clampLightboxScale(99)).toBe(LIGHTBOX_MAX_SCALE);
+ it('rubber-bands pinch scale past both ends instead of hard-stopping', () => {
+ expect(rubberBandLightboxScale(2)).toBe(2);
+ // 捏过两端仍会继续变化,但越捏越沉,且永远到不了渐近线
+ const under = rubberBandLightboxScale(0.5);
+ expect(under).toBeLessThan(LIGHTBOX_MIN_SCALE);
+ expect(under).toBeGreaterThan(0.5);
+ expect(rubberBandLightboxScale(0.3)).toBeLessThan(under);
+ expect(rubberBandLightboxScale(0)).toBeGreaterThan(LIGHTBOX_MIN_SCALE * 0.5);
+ const over = rubberBandLightboxScale(LIGHTBOX_MAX_SCALE + 2);
+ expect(over).toBeGreaterThan(LIGHTBOX_MAX_SCALE);
+ expect(over).toBeLessThan(LIGHTBOX_MAX_SCALE + 2);
+ expect(rubberBandLightboxScale(99)).toBeLessThan(LIGHTBOX_MAX_SCALE * 1.5);
+ // 逆运算:回弹途中再捏时从当前画面接续
+ for (const raw of [0.2, 0.7, 1, 2.5, 4, 5, 9]) {
+ expect(unrubberLightboxScale(rubberBandLightboxScale(raw))).toBeCloseTo(raw, 6);
+ }
+ });
+
+ it('rubber band grows monotonically with diminishing returns and inverts cleanly', () => {
+ expect(lightboxRubberBand(0, 400)).toBe(0);
+ expect(lightboxRubberBand(-10, 400)).toBe(0);
+ expect(lightboxRubberBand(10, 0)).toBe(0);
+ const a = lightboxRubberBand(100, 400);
+ const b = lightboxRubberBand(200, 400);
+ expect(a).toBeGreaterThan(0);
+ expect(a).toBeLessThan(100);
+ // 越拉越沉:第二个 100px 换来的位移少于第一个
+ expect(b - a).toBeGreaterThan(0);
+ expect(b - a).toBeLessThan(a);
+ expect(lightboxRubberBand(1e9, 400)).toBeLessThan(400);
+ expect(lightboxRubberBandInverse(a, 400)).toBeCloseTo(100, 6);
+ expect(Number.isFinite(lightboxRubberBandInverse(400, 400))).toBe(true);
+ });
+
+ it('lets the pan run past the image edge with resistance, including locked axes', () => {
+ // 2x:溢出 200;边界内原样
+ expect(rubberBandLightboxTranslation(150, 400, 2, 400)).toBe(150);
+ const past = rubberBandLightboxTranslation(300, 400, 2, 400);
+ expect(past).toBeGreaterThan(200);
+ expect(past).toBeLessThan(300);
+ expect(rubberBandLightboxTranslation(-300, 400, 2, 400)).toBeCloseTo(-past, 9);
+ // 未溢出的轴(横图纵向)也能拖动一点,而不是锁死在 0
+ const locked = rubberBandLightboxTranslation(80, 800, 2.5, 225);
+ expect(locked).toBeGreaterThan(0);
+ expect(locked).toBeLessThan(80);
+ expect(unrubberLightboxTranslation(past, 400, 2, 400)).toBeCloseTo(300, 6);
+ expect(unrubberLightboxTranslation(-locked, 800, 2.5, 225)).toBeCloseTo(-80, 6);
+ });
+
+ it('drags incrementally: dragging out and back returns to the same spot', () => {
+ let pos = { x: 180, y: 0 };
+ for (let i = 0; i < 10; i += 1) {
+ pos = dragLightboxVisualPan(pos.x, pos.y, 20, 0, 0, 0, 400, 800, 2, 400, 800);
+ }
+ // 手指越界 180px,画面只多走一截
+ expect(pos.x).toBeGreaterThan(200);
+ expect(pos.x).toBeLessThan(380);
+ for (let i = 0; i < 10; i += 1) {
+ pos = dragLightboxVisualPan(pos.x, pos.y, -20, 0, 0, 0, 400, 800, 2, 400, 800);
+ }
+ expect(pos.x).toBeCloseTo(180, 6);
+ });
+
+ it('decides how a released pan settles on each axis', () => {
+ // 越界:弹回最近的边界
+ expect(lightboxPanRelease(260, 0, 400, 2, 400)).toEqual({ kind: 'settle', to: 200 });
+ expect(lightboxPanRelease(-260, 900, 400, 2, 400)).toEqual({ kind: 'settle', to: -200 });
+ expect(lightboxPanRelease(30, 0, 800, 2.5, 225)).toEqual({ kind: 'settle', to: 0 });
+ // 边界内:有速度惯性滑行,慢放手原地停
+ expect(lightboxPanRelease(100, 1200, 400, 2, 400)).toEqual({ kind: 'fling', min: -200, max: 200 });
+ expect(lightboxPanRelease(100, 20, 400, 2, 400)).toEqual({ kind: 'none' });
+ });
+
+ it('settles a pinch back into range around the last focal point', () => {
+ const base = { containerWidth: 400, containerHeight: 800, displayedWidth: 400, displayedHeight: 800 };
+ // 缩到 1x 及以下一律回正
+ expect(lightboxPinchSettle({ ...base, scale: 0.7, translateX: 40, translateY: -30, focalX: 0, focalY: 0 }))
+ .toEqual({ scale: LIGHTBOX_MIN_SCALE, x: 0, y: 0 });
+ // 范围内且边界内:原样(不因浮点误差起一段动画)
+ expect(lightboxPinchSettle({ ...base, scale: 2.1, translateX: -77.3, translateY: 12.9, focalX: 37, focalY: -90 }))
+ .toEqual({ scale: 2.1, x: -77.3, y: 12.9 });
+ // 范围内但越界:位移收回边界
+ expect(lightboxPinchSettle({ ...base, scale: 2, translateX: 260, translateY: 0, focalX: 0, focalY: 0 }))
+ .toEqual({ scale: 2, x: 200, y: 0 });
+ // 捏过最大倍率:绕焦点缩回,焦点下那一点不动
+ const settled = lightboxPinchSettle({ ...base, scale: 5, translateX: -100, translateY: 300, focalX: 50, focalY: 100 });
+ expect(settled.scale).toBe(LIGHTBOX_MAX_SCALE);
+ const pointX = (50 - -100) / 5;
+ const pointY = (100 - 300) / 5;
+ expect(pointX * settled.scale + settled.x).toBeCloseTo(50, 9);
+ expect(pointY * settled.scale + settled.y).toBeCloseTo(100, 9);
});
it('clamps translation to the zoomed overflow and locks it at 1x', () => {
@@ -77,6 +175,44 @@ describe('imageLightboxModel', () => {
expect(bakeLightboxOrigin(-60, 0, 2)).toBe(-60);
});
+ it('anchors a second pinch on the image point under the fingers', () => {
+ // 1x、未平移:锚点就是焦点
+ expect(lightboxPinchAnchor(300, 400, 0, 1)).toBe(100);
+ // 2.5x、T=-195:屏幕中心(焦点相对坐标 0)下是图片坐标 78 的点
+ const anchor = lightboxPinchAnchor(200, 400, -195, 2.5);
+ expect(anchor).toBeCloseTo(78, 9);
+ // 补偿后,锚点在任意倍率下都停在手指下(transform = T + o + s·(p - o))
+ const translate = compensateLightboxOrigin(-195, anchor, 2.5);
+ for (const s of [2.5, 3, 4.2]) {
+ expect(translate + anchor + s * (anchor - anchor)).toBeCloseTo(0, 9);
+ }
+ // 起始帧无跳变:任一图片点的屏幕位置与补偿前一致
+ expect(translate + anchor + 2.5 * (10 - anchor)).toBeCloseTo(-195 + 2.5 * 10, 9);
+ });
+
+ it('keeps the pinch anchor under the fingers even when the pinch starts out of bounds', () => {
+ // 2x、画面位移 300(越界,overflow=200),在屏幕中心捏:锚点 = (0 - 300) / 2 = -150
+ const anchor = lightboxPinchAnchor(200, 400, 300, 2);
+ expect(anchor).toBe(-150);
+ const screenOfAnchor = (raw: number) => raw + anchor; // T + o + s·(o - o)
+ // 第一帧(倍率未变、手指未动)与起点连续:bake 回去仍是 300
+ const first = lightboxPinchTranslation(300, anchor, 2, 2, 0, 400, 400);
+ expect(bakeLightboxOrigin(first, anchor, 2)).toBeCloseTo(300, 9);
+ // 捏到 4x:锚定位移 600 恰在 overflow=600 内,锚点必须停在手指下(不漂)
+ const at4 = lightboxPinchTranslation(300, anchor, 2, 4, 0, 400, 400);
+ expect(screenOfAnchor(at4)).toBeCloseTo(0, 9);
+ // 手指往边界内平移时锚点跟手;往外越界则按阻尼少走一截
+ expect(screenOfAnchor(lightboxPinchTranslation(300, anchor, 2, 4, -25, 400, 400))).toBeCloseTo(-25, 9);
+ const outward = screenOfAnchor(lightboxPinchTranslation(300, anchor, 2, 4, 25, 400, 400));
+ expect(outward).toBeGreaterThan(0);
+ expect(outward).toBeLessThan(25);
+ // 锚定位移越过新边界时才阻尼:画面不越过手指目标
+ const at3 = lightboxPinchTranslation(300, anchor, 2, 2.2, 0, 400, 400);
+ const visual = bakeLightboxOrigin(at3, anchor, 2.2);
+ expect(visual).toBeLessThanOrEqual(300 + 150 * 0.2 + 1e-9);
+ expect(visual).toBeGreaterThan(lightboxPanOverflow(400, 400, 2.2));
+ });
+
it('compensates translation when applying a pinch origin onto an existing scale', () => {
// 双击 2.5x 后 translate=-150;再在 origin=100 处捏合,补偿后画面公式不变
expect(compensateLightboxOrigin(-150, 100, LIGHTBOX_DOUBLE_TAP_SCALE)).toBe(0);
@@ -85,16 +221,19 @@ describe('imageLightboxModel', () => {
expect(compensateLightboxOrigin(0, 100, 1)).toBe(0);
});
- it('clamps baked visual pan then compensates when origin is nonzero', () => {
- // origin=0: bake/补偿恒等,与直接钳 raw 相同
- expect(clampLightboxVisualPan(250, 0, 0, 0, 400, 800, 2, 400, 800)).toEqual({ x: 200, y: 0 });
- // origin=100, scale=2: visual = T + 100*(1-2) = T-100。T=-200 钳 raw 看似贴边,
- // 画面却在 -300,越出 overflow 200。只修捏合、不修标注 pan 的半边修法过不了这条。
- expect(clampLightboxTranslation(-200, 400, 2, 400)).toBe(-200);
- expect(clampLightboxVisualPan(-200, 0, 100, 0, 400, 800, 2, 400, 800)).toEqual({ x: -100, y: 0 });
- expect(bakeLightboxOrigin(-100, 100, 2)).toBe(-200);
+ it('rubber-bands the baked visual pan then compensates when origin is nonzero', () => {
+ // origin=0: bake/补偿恒等,与直接作用于 raw 相同
+ expect(rubberBandLightboxVisualPan(150, 0, 0, 0, 400, 800, 2, 400, 800)).toEqual({ x: 150, y: 0 });
+ // origin=100, scale=2: visual = T + 100*(1-2) = T-100。T=-200 看似贴边,
+ // 画面却在 -300,已越出 overflow 200,必须按画面越界量阻尼。
+ const next = rubberBandLightboxVisualPan(-200, 0, 100, 0, 400, 800, 2, 400, 800);
+ const visual = bakeLightboxOrigin(next.x, 100, 2);
+ expect(visual).toBeCloseTo(rubberBandLightboxTranslation(-300, 400, 2, 400), 9);
+ expect(visual).toBeGreaterThan(-300);
+ expect(visual).toBeLessThan(-200);
// 画面未越界时 raw 保持不动
- expect(clampLightboxVisualPan(250, 0, 100, 0, 400, 800, 2, 400, 800)).toEqual({ x: 250, y: 0 });
+ expect(rubberBandLightboxVisualPan(250, 0, 100, 0, 400, 800, 2, 400, 800)).toEqual({ x: 250, y: 0 });
+ expect(unrubberLightboxVisualPan(next.x, next.y, 100, 0, 400, 800, 2, 400, 800).x).toBeCloseTo(-200, 6);
});
it('double-tap zooms into the tap point and resets when returning to 1x', () => {
diff --git a/apps/mobile/src/__tests__/messageMediaThumbnailWiring.test.ts b/apps/mobile/src/__tests__/messageMediaThumbnailWiring.test.ts
index dd763b2ae4..b5584dd192 100644
--- a/apps/mobile/src/__tests__/messageMediaThumbnailWiring.test.ts
+++ b/apps/mobile/src/__tests__/messageMediaThumbnailWiring.test.ts
@@ -162,8 +162,9 @@ describe('mobile message media thumbnail wiring', () => {
expect(lightboxSource).toContain('if (!finished || !doubleTapBusy.value) return');
// 二次捏合:已有缩放时先补偿 origin,不把 origin*(1-scale) 立刻叠进画面
expect(lightboxSource).toContain('compensateLightboxOrigin(');
- // origin≠0 时平移钳的是 bake 后的画面,浏览捏合与标注双指 pan 共用
- expect(lightboxSource).toContain('clampLightboxVisualPan(');
+ // 越界阻尼按 bake 后的画面与当前倍率边界计算:捏合锚点跟手,标注双指 pan 共用画面阻尼
+ expect(lightboxSource).toContain('lightboxPinchTranslation(');
+ expect(lightboxSource).toContain('dragLightboxVisualPan(');
// chrome 显隐走共享 motion token,不在组件里写死毫秒
expect(lightboxSource).toContain('duration: motionDuration.instant');
expect(lightboxSource).toContain('duration: motionDuration.fast');
diff --git a/apps/mobile/src/session/ImageLightbox.tsx b/apps/mobile/src/session/ImageLightbox.tsx
index 1f8cacc071..5af5fed588 100644
--- a/apps/mobile/src/session/ImageLightbox.tsx
+++ b/apps/mobile/src/session/ImageLightbox.tsx
@@ -2,7 +2,8 @@
* ImageLightbox — IM 级全屏图片查看器。
* ---------------------------------------------------------------------------
* 点缩略图直接全屏黑底看图,交互对齐主流 IM:
- * - 双指捏合绕焦点缩放(1x~4x);放大后单指平移(钳制在 contain 后的图片边界内)
+ * - 双指捏合绕焦点缩放(1x~4x,可捏过两端再弹回);放大后单指平移,
+ * 越过图片边界有橡皮筋阻尼,松手带惯性滑行、越界弹回(对齐系统相册)
* - 双击在 1x / 2.5x 间切换并落到点击点;1x 单击关闭
* - 1x 下竖直下滑跟手关闭(位移 + 背景渐隐),横滑翻会话内图片集
* - 放大后单指只平移;单击不关(双击缩回,或先回到 1x 再单击/下滑)
@@ -39,6 +40,7 @@ import Animated, {
runOnJS,
useAnimatedStyle,
useSharedValue,
+ withDecay,
withSpring,
withTiming,
type SharedValue,
@@ -56,9 +58,8 @@ import {
bakeLightboxOrigin,
canShareLightboxImage,
compensateLightboxOrigin,
- clampLightboxScale,
clampLightboxTranslation,
- clampLightboxVisualPan,
+ dragLightboxVisualPan,
isLightboxZoomed,
lightboxBackgroundOpacity,
lightboxContainedSize,
@@ -67,12 +68,20 @@ import {
lightboxInitialIndex,
lightboxPageIndex,
lightboxPageLabel,
+ lightboxPanRelease,
+ lightboxPinchAnchor,
lightboxPinchOrigin,
+ lightboxPinchSettle,
+ lightboxPinchTranslation,
+ LIGHTBOX_MAX_SCALE,
+ LIGHTBOX_MIN_SCALE,
LIGHTBOX_TAP_MAX_DISTANCE,
nextDoubleTapScale,
reclampLightboxPan,
+ rubberBandLightboxScale,
shouldCloseLightboxOnTap,
shouldDismissLightbox,
+ unrubberLightboxScale,
} from '@/session/imageLightboxModel';
import {
ANNOTATION_OUTLINE_COLOR,
@@ -95,6 +104,9 @@ import {
// retaining the lightbox's native gesture transforms.
const AnimatedImage = Animated.createAnimatedComponent(Image);
+/** 越界 / 捏过两端松手的回弹:接近临界阻尼,约 0.3s 落定,几乎不来回晃。 */
+const LIGHTBOX_SETTLE_SPRING = { damping: 30, stiffness: 260, mass: 1 } as const;
+
// 缩略图垫底**不**挂在取件态里:它要跨过 loading → ready 的边界继续垫住原图
// 下载那一段(见 lightboxImageLayers),挂进 loading 分支会在取件完成的瞬间
// 结构性丢失,把第二段空档裸露成纯黑。垫底地址单独存 previewMap。
@@ -694,7 +706,8 @@ export const ImageLightbox = memo(function ImageLightbox({
width={width}
/>
)}
- scrollEnabled={!zoomed && !isAnnotating && !annotationSubmitting && images.length > 1}
+ // 单图同样开启:iOS 横向拖到边缘有系统回弹,与多图首尾页手感一致。
+ scrollEnabled={!zoomed && !isAnnotating && !annotationSubmitting}
showsHorizontalScrollIndicator={false}
windowSize={3}
/>
@@ -1026,11 +1039,22 @@ const LightboxPage = memo(function LightboxPage({
const originY = useSharedValue(0);
const startFocalX = useSharedValue(0);
const startFocalY = useSharedValue(0);
+ /** 捏合开始时的画面倍率:锚定位移按它与当前倍率之差推算。 */
+ const pinchStartScale = useSharedValue(1);
const displayedW = useSharedValue(width);
const displayedH = useSharedValue(height);
+ /** 捏合最后的焦点(容器坐标):捏过最大倍率松手时绕它缩回。 */
+ const lastFocalX = useSharedValue(0);
+ const lastFocalY = useSharedValue(0);
const pinchBusy = useSharedValue(0);
const panBusy = useSharedValue(0);
const doubleTapBusy = useSharedValue(0);
+ /** 平移松手后的惯性滑行 / 越界回弹进行中:手指按下即可接住。 */
+ const panSettling = useSharedValue(0);
+ /** 本次按下接住了滑行;若没形成拖动就抬手,要补一次回弹,不能停在越界处。 */
+ const panCaught = useSharedValue(0);
+ /** 松手回弹(springToTransform)进行中:位移已有一致的目标,平移松手不另起回弹;落定前锁住翻页。 */
+ const zoomSettling = useSharedValue(0);
const dragY = useSharedValue(0);
/**
* 已 onLoad 成功的原图地址。存地址而不是 boolean:换图 / 强制重取换 url 后
@@ -1065,6 +1089,51 @@ const LightboxPage = memo(function LightboxPage({
onZoomChange(value);
}, [onZoomChange]);
+ /**
+ * 倍率与位移一起弹到合法落点。三者同一弹簧、零初速:归一化进度逐帧相同,
+ * 画面上 p·s + T 线性插值,焦点下那一点全程不漂。调用前 origin 必须已归零。
+ * 手势松手与尺寸变化(回弹途中原图尺寸到达)共用,翻页锁与落定上报只在这一处。
+ */
+ const springToTransform = useCallback((target: { scale: number; x: number; y: number }) => {
+ 'worklet';
+ savedScale.value = target.scale;
+ savedTranslateX.value = target.x;
+ savedTranslateY.value = target.y;
+ const scaleMoves = scale.value !== target.scale;
+ const xMoves = translateX.value !== target.x;
+ const yMoves = translateY.value !== target.y;
+ if (!scaleMoves && !xMoves && !yMoves) {
+ zoomSettling.value = 0;
+ runOnJS(reportZoomed)(isLightboxZoomed(target.scale));
+ return;
+ }
+ // 先置标记、先锁翻页,再启动动画:减少动态效果下回调会在赋值时同步执行,
+ // 落定上报必须是最后一次(与双击路径一致)。回到 1x 的回弹期间锁住翻页,
+ // 否则缩小松手后立刻横划会被翻页抢走、在回弹中途切走当前图。
+ zoomSettling.value = 1;
+ runOnJS(reportZoomed)(true);
+ // 落定回调只挂在一条动画上;被新手势打断(finished=false)时由接管方负责翻页锁。
+ const onSettled = (finished?: boolean) => {
+ 'worklet';
+ if (!finished) return;
+ zoomSettling.value = 0;
+ runOnJS(reportZoomed)(isLightboxZoomed(savedScale.value));
+ };
+ if (scaleMoves) scale.value = withSpring(target.scale, LIGHTBOX_SETTLE_SPRING, onSettled);
+ if (xMoves) {
+ translateX.value = withSpring(target.x, LIGHTBOX_SETTLE_SPRING, scaleMoves ? undefined : onSettled);
+ }
+ if (yMoves) {
+ translateY.value = withSpring(
+ target.y,
+ LIGHTBOX_SETTLE_SPRING,
+ scaleMoves || xMoves ? undefined : onSettled,
+ );
+ }
+ // 共享值引用恒定,只随 reportZoomed 重建
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [reportZoomed]);
+
useEffect(() => {
const size = lightboxContainedSize(
width,
@@ -1093,6 +1162,21 @@ const LightboxPage = memo(function LightboxPage({
savedTranslateY.value = next.y;
return;
}
+ // 松手回弹途中:直接改 live 会打断回弹,落定回调不触发,翻页一直锁着、倍率
+ // 也可能停在范围外。把目标收进新边界,从当前帧重新发起同一次回弹。
+ if (zoomSettling.value) {
+ const next = reclampLightboxPan(
+ savedTranslateX.value,
+ savedTranslateY.value,
+ width,
+ height,
+ savedScale.value,
+ size.width,
+ size.height,
+ );
+ springToTransform({ scale: savedScale.value, x: next.x, y: next.y });
+ return;
+ }
const next = reclampLightboxPan(
translateX.value,
translateY.value,
@@ -1123,6 +1207,9 @@ const LightboxPage = memo(function LightboxPage({
pinchBusy.value = 0;
panBusy.value = 0;
doubleTapBusy.value = 0;
+ panSettling.value = 0;
+ panCaught.value = 0;
+ zoomSettling.value = 0;
dragY.value = 0;
chromeHidden.value = 0;
onChromeBusy(false);
@@ -1135,6 +1222,9 @@ const LightboxPage = memo(function LightboxPage({
const stopTransformAnimation = () => {
'worklet';
doubleTapBusy.value = 0;
+ panSettling.value = 0;
+ panCaught.value = 0;
+ zoomSettling.value = 0;
cancelAnimation(scale);
cancelAnimation(translateX);
cancelAnimation(translateY);
@@ -1150,30 +1240,61 @@ const LightboxPage = memo(function LightboxPage({
chromeHidden.value = withTiming(0, { duration: motionDuration.fast });
runOnJS(onChromeBusy)(false);
};
- const bakePinchOrigin = () => {
+ const settlePinch = () => {
'worklet';
const bakedX = bakeLightboxOrigin(translateX.value, originX.value, scale.value);
const bakedY = bakeLightboxOrigin(translateY.value, originY.value, scale.value);
originX.value = 0;
originY.value = 0;
- if (!isLightboxZoomed(scale.value)) {
- scale.value = withTiming(1);
- savedScale.value = 1;
- translateX.value = withTiming(0);
- translateY.value = withTiming(0);
- savedTranslateX.value = 0;
- savedTranslateY.value = 0;
- runOnJS(reportZoomed)(false);
+ translateX.value = bakedX;
+ translateY.value = bakedY;
+ springToTransform(lightboxPinchSettle({
+ scale: scale.value,
+ translateX: bakedX,
+ translateY: bakedY,
+ focalX: lightboxPinchOrigin(lastFocalX.value, width),
+ focalY: lightboxPinchOrigin(lastFocalY.value, height),
+ containerWidth: width,
+ containerHeight: height,
+ displayedWidth: displayedW.value,
+ displayedHeight: displayedH.value,
+ }));
+ };
+ /** 单轴松手:越界弹簧回边界;边界内有速度则惯性滑行,滑到边界由橡皮筋衰减冲过再回。 */
+ const releasePanAxis = (
+ value: SharedValue<number>,
+ velocity: number,
+ containerSize: number,
+ displayedSize: number,
+ ) => {
+ 'worklet';
+ const release = lightboxPanRelease(value.value, velocity, containerSize, scale.value, displayedSize);
+ if (release.kind === 'settle') {
+ value.value = withSpring(release.to, { ...LIGHTBOX_SETTLE_SPRING, velocity });
+ } else if (release.kind === 'fling') {
+ value.value = withDecay({ velocity, clamp: [release.min, release.max], rubberBandEffect: true });
+ }
+ };
+ const settlePan = (velocityX: number, velocityY: number) => {
+ 'worklet';
+ // 倍率回弹被拖动打断时可能停在两端之外:连同位移按画面中心收回合法落点。
+ if (scale.value > LIGHTBOX_MAX_SCALE || scale.value < LIGHTBOX_MIN_SCALE) {
+ springToTransform(lightboxPinchSettle({
+ scale: scale.value,
+ translateX: translateX.value,
+ translateY: translateY.value,
+ focalX: 0,
+ focalY: 0,
+ containerWidth: width,
+ containerHeight: height,
+ displayedWidth: displayedW.value,
+ displayedHeight: displayedH.value,
+ }));
return;
}
- const cx = clampLightboxTranslation(bakedX, width, scale.value, displayedW.value);
- const cy = clampLightboxTranslation(bakedY, height, scale.value, displayedH.value);
- translateX.value = cx;
- translateY.value = cy;
- savedTranslateX.value = cx;
- savedTranslateY.value = cy;
- savedScale.value = scale.value;
- runOnJS(reportZoomed)(true);
+ releasePanAxis(translateX, velocityX, width, displayedW.value);
+ releasePanAxis(translateY, velocityY, height, displayedH.value);
+ panSettling.value = 1;
};
// 焦点捏合:起点锁定 origin,缩放绕焦点;浏览态跟手质心,标注态只改 scale
@@ -1190,38 +1311,61 @@ const LightboxPage = memo(function LightboxPage({
// 下滑半途改捏合:关掉正在进行的 dismiss 位移,不把图和背景留在半透明上。
dragY.value = 0;
dismissY.value = 0;
- savedScale.value = scale.value;
- originX.value = lightboxPinchOrigin(event.focalX, width);
- originY.value = lightboxPinchOrigin(event.focalY, height);
+ // 倍率起点存「手指量」而非画面量:回弹途中再捏时画面可能处在橡皮筋区,
+ // 直接当起点会让第一帧按阻尼重新映射而跳一下。
+ savedScale.value = unrubberLightboxScale(scale.value);
+ // 锚点取手指下那一点的图片坐标,已放大 / 平移后二次捏合才绕手指缩放。
+ const bakedX = bakeLightboxOrigin(translateX.value, originX.value, scale.value);
+ const bakedY = bakeLightboxOrigin(translateY.value, originY.value, scale.value);
+ originX.value = lightboxPinchAnchor(event.focalX, width, bakedX, scale.value);
+ originY.value = lightboxPinchAnchor(event.focalY, height, bakedY, scale.value);
// 已放大时 origin 会立刻贡献 origin*(1-scale);扣掉等量位移,二次捏合不跳。
- translateX.value = compensateLightboxOrigin(translateX.value, originX.value, scale.value);
- translateY.value = compensateLightboxOrigin(translateY.value, originY.value, scale.value);
- savedTranslateX.value = translateX.value;
- savedTranslateY.value = translateY.value;
+ translateX.value = compensateLightboxOrigin(bakedX, originX.value, scale.value);
+ translateY.value = compensateLightboxOrigin(bakedY, originY.value, scale.value);
+ // 起点存 bake 后的画面位移(几何量);每帧按当前倍率的边界换算手指量,
+ // 不跨倍率复用起始倍率下的换算结果(见 lightboxPinchTranslation)。
+ savedTranslateX.value = bakedX;
+ savedTranslateY.value = bakedY;
+ pinchStartScale.value = scale.value;
startFocalX.value = event.focalX;
startFocalY.value = event.focalY;
+ lastFocalX.value = event.focalX;
+ lastFocalY.value = event.focalY;
})
.onChange((event) => {
- scale.value = clampLightboxScale(savedScale.value * event.scale);
+ // 捏过 1x / 最大倍率不再硬卡:阻尼继续缩放,松手再弹回(settlePinch)。
+ scale.value = rubberBandLightboxScale(savedScale.value * event.scale);
+ lastFocalX.value = event.focalX;
+ lastFocalY.value = event.focalY;
if (annotating) return;
- // 画面中心钳制,再补偿回 raw。origin≠0 时不能钳 raw。
- const next = clampLightboxVisualPan(
- savedTranslateX.value + (event.focalX - startFocalX.value),
- savedTranslateY.value + (event.focalY - startFocalY.value),
- originX.value,
- originY.value,
- width,
- height,
- scale.value,
- displayedW.value,
- displayedH.value,
- );
+ // 锚点跟手;越过图片边界按当前倍率的边界阻尼而不是硬钳,焦点附近捏合时
+ // 图不再「粘」在边上,回弹途中再捏时锚点也不从手指下滑开。
+ const next = {
+ x: lightboxPinchTranslation(
+ savedTranslateX.value,
+ originX.value,
+ pinchStartScale.value,
+ scale.value,
+ event.focalX - startFocalX.value,
+ width,
+ displayedW.value,
+ ),
+ y: lightboxPinchTranslation(
+ savedTranslateY.value,
+ originY.value,
+ pinchStartScale.value,
+ scale.value,
+ event.focalY - startFocalY.value,
+ height,
+ displayedH.value,
+ ),
+ };
translateX.value = next.x;
translateY.value = next.y;
})
.onFinalize(() => {
if (!pinchBusy.value) return;
- bakePinchOrigin();
+ settlePinch();
pinchBusy.value = 0;
maybeShowChrome();
});
@@ -1233,7 +1377,17 @@ const LightboxPage = memo(function LightboxPage({
.minPointers(annotating ? 2 : 1)
.maxPointers(annotating ? 2 : 1)
.onTouchesDown((_event, state) => {
- if (!annotating && !isLightboxZoomed(scale.value)) state.fail();
+ if (!annotating && !isLightboxZoomed(scale.value)) {
+ state.fail();
+ return;
+ }
+ // 手指按住正在滑行 / 回弹的图:就地停住,对齐系统相册的「接住」手感。
+ if (panSettling.value) {
+ cancelAnimation(translateX);
+ cancelAnimation(translateY);
+ panSettling.value = 0;
+ panCaught.value = 1;
+ }
})
.onStart(() => {
panBusy.value = 1;
@@ -1244,10 +1398,13 @@ const LightboxPage = memo(function LightboxPage({
})
.onChange((event) => {
// 标注双指 pan 与 off-center pinch Simultaneous,origin 常非 0;
- // 浏览单指 pan 的 origin 已 bake 归零,helper 退化为钳 raw。
- const next = clampLightboxVisualPan(
- translateX.value + event.changeX,
- translateY.value + event.changeY,
+ // 浏览单指 pan 的 origin 已 bake 归零。越界部分走橡皮筋:到了边缘仍可
+ // 继续拖(越拖越沉),松手再弹回(settlePan)。
+ const next = dragLightboxVisualPan(
+ translateX.value,
+ translateY.value,
+ event.changeX,
+ event.changeY,
originX.value,
originY.value,
width,
@@ -1259,15 +1416,27 @@ const LightboxPage = memo(function LightboxPage({
translateX.value = next.x;
translateY.value = next.y;
})
- .onFinalize(() => {
+ .onFinalize((event) => {
// Tap 也会让未激活的 Pan 走 FAILED → finalize。它不拥有位移,
// 不能把双击缩回的 saved=0 覆盖成动画中途的旧偏移。
- if (!panBusy.value) return;
+ if (!panBusy.value) {
+ // 接住滑行后没拖就抬手:图可能停在越界处,补一次回弹。双击 / 捏合
+ // 已接管时由它们负责落点(stopTransformAnimation 会清掉 panCaught)。
+ if (panCaught.value && !pinchBusy.value && !doubleTapBusy.value) {
+ panCaught.value = 0;
+ settlePan(0, 0);
+ }
+ return;
+ }
savedTranslateX.value = translateX.value;
savedTranslateY.value = translateY.value;
panBusy.value = 0;
- if (!pinchBusy.value)
- runOnJS(reportZoomed)(isLightboxZoomed(scale.value));
+ if (!pinchBusy.value) {
+ // 回弹进行中时位移已随之弹向一致落点,这里不另起动画抢它。
+ if (!zoomSettling.value) settlePan(event.velocityX ?? 0, event.velocityY ?? 0);
+ // 回弹(含刚由 settlePan 发起的)由 springToTransform 管翻页锁,落定时再上报。
+ if (!zoomSettling.value) runOnJS(reportZoomed)(isLightboxZoomed(scale.value));
+ }
maybeShowChrome();
});
@@ -1409,6 +1578,7 @@ const LightboxPage = memo(function LightboxPage({
reportZoomed,
onDrawPoint,
onChromeBusy,
+ springToTransform,
]);
const imageStyle = useAnimatedStyle(() => ({
diff --git a/apps/mobile/src/session/imageLightboxModel.ts b/apps/mobile/src/session/imageLightboxModel.ts
index 4a7695f163..da7791d63a 100644
--- a/apps/mobile/src/session/imageLightboxModel.ts
+++ b/apps/mobile/src/session/imageLightboxModel.ts
@@ -2,7 +2,8 @@
* imageLightboxModel.ts — 全屏图片查看器的手势/布局决策纯函数。
* ---------------------------------------------------------------------------
* ImageLightbox 组件里的 worklet 只做数值搬运,所有"判定"(缩放边界、平移钳制、
- * 下滑释放是否关闭、背景透明度、页索引)集中在这里,node 环境可单测。
+ * 越界橡皮筋与松手回弹、下滑释放是否关闭、背景透明度、页索引)集中在这里,
+ * node 环境可单测。
*/
export const LIGHTBOX_MIN_SCALE = 1;
@@ -19,11 +20,52 @@ export const LIGHTBOX_DISMISS_VELOCITY = 800;
* 与平移 Simultaneous 时,500ms 内的短拖松手会被当成单击,lightbox 直接关掉。
*/
export const LIGHTBOX_TAP_MAX_DISTANCE = 12;
+/** 橡皮筋系数(对齐 UIScrollView 的 0.55):越界量 x 显示为 (1 - 1/(x·c/d + 1))·d。 */
+export const LIGHTBOX_RUBBER_BAND_COEFFICIENT = 0.55;
+/** 捏合越过 1x / 最大倍率时橡皮筋的渐近幅度(倍率),手越用力越难再缩放。 */
+const LIGHTBOX_UNDER_ZOOM_RANGE = LIGHTBOX_MIN_SCALE * 0.5;
+const LIGHTBOX_OVER_ZOOM_RANGE = LIGHTBOX_MAX_SCALE * 0.5;
-export function clampLightboxScale(scale: number): number {
+/**
+ * 越界量 → 实际显示的越界距离:越拉阻力越大,渐近 dimension 永远拉不满。
+ * dimension 取容器边长时,手感与系统滚动视图的边缘回弹一致。
+ */
+export function lightboxRubberBand(overshoot: number, dimension: number): number {
+ 'worklet';
+ if (overshoot <= 0 || dimension <= 0) return 0;
+ return (1 - 1 / ((overshoot * LIGHTBOX_RUBBER_BAND_COEFFICIENT) / dimension + 1)) * dimension;
+}
+
+/** {@link lightboxRubberBand} 的逆运算:已显示的越界距离还原成手指实际越界量。 */
+export function lightboxRubberBandInverse(distance: number, dimension: number): number {
+ 'worklet';
+ if (distance <= 0 || dimension <= 0) return 0;
+ // 显示距离理论上 < dimension;浮点 / 外部写入越过时取极大有限值,避免除零。
+ const ratio = Math.min(distance / dimension, 0.999);
+ return (dimension / LIGHTBOX_RUBBER_BAND_COEFFICIENT) * (1 / (1 - ratio) - 1);
+}
+
+/** 捏合倍率的橡皮筋:范围内原样,捏过 1x / 最大倍率按阻尼继续缩放。 */
+export function rubberBandLightboxScale(rawScale: number): number {
'worklet';
- if (scale < LIGHTBOX_MIN_SCALE) return LIGHTBOX_MIN_SCALE;
- if (scale > LIGHTBOX_MAX_SCALE) return LIGHTBOX_MAX_SCALE;
+ if (rawScale < LIGHTBOX_MIN_SCALE) {
+ return LIGHTBOX_MIN_SCALE - lightboxRubberBand(LIGHTBOX_MIN_SCALE - rawScale, LIGHTBOX_UNDER_ZOOM_RANGE);
+ }
+ if (rawScale > LIGHTBOX_MAX_SCALE) {
+ return LIGHTBOX_MAX_SCALE + lightboxRubberBand(rawScale - LIGHTBOX_MAX_SCALE, LIGHTBOX_OVER_ZOOM_RANGE);
+ }
+ return rawScale;
+}
+
+/** {@link rubberBandLightboxScale} 的逆运算:回弹途中再次捏合时从当前画面接续,不跳。 */
+export function unrubberLightboxScale(scale: number): number {
+ 'worklet';
+ if (scale < LIGHTBOX_MIN_SCALE) {
+ return LIGHTBOX_MIN_SCALE - lightboxRubberBandInverse(LIGHTBOX_MIN_SCALE - scale, LIGHTBOX_UNDER_ZOOM_RANGE);
+ }
+ if (scale > LIGHTBOX_MAX_SCALE) {
+ return LIGHTBOX_MAX_SCALE + lightboxRubberBandInverse(scale - LIGHTBOX_MAX_SCALE, LIGHTBOX_OVER_ZOOM_RANGE);
+ }
return scale;
}
@@ -110,6 +152,23 @@ export function lightboxPinchOrigin(focal: number, containerSize: number): numbe
return focal - containerSize / 2;
}
+/**
+ * 捏合的缩放锚点:手指焦点下那一点在图片自身坐标里的位置(相对图片中心、未缩放)。
+ * transform 为 T + origin + s·(p - origin),只有 p = origin 的点在缩放中不动;
+ * 已放大 / 已平移时这一点不是焦点的屏幕坐标,直接用焦点会让二次捏合绕错的中心
+ * 缩放、图往外漂。translate 为 bake 后(origin=0)的位移。
+ */
+export function lightboxPinchAnchor(
+ focal: number,
+ containerSize: number,
+ translate: number,
+ scale: number,
+): number {
+ 'worklet';
+ if (scale <= 0) return lightboxPinchOrigin(focal, containerSize);
+ return (lightboxPinchOrigin(focal, containerSize) - translate) / scale;
+}
+
/**
* 把 origin 缩放折进 translation,之后 origin 可归零而不跳变。
* p' = (p - origin) * scale + origin + translate
@@ -131,11 +190,106 @@ export function compensateLightboxOrigin(translate: number, origin: number, scal
}
/**
- * 画面中心(bake 后)钳进 contain 边界,再补偿回带 origin 的 raw translate。
- * origin≠0 时钳 raw 会让画面越出边界,松手 bake 再弹回。origin=0 时 bake/补偿
- * 是恒等,与直接钳 translate 相同——浏览捏合与标注双指平移共用这一条。
+ * 平移的橡皮筋:边界内原样;越过图片边缘(含未溢出、钳在 0 的轴)仍可继续拖,
+ * 越界部分按容器边长阻尼。value 是 bake 后的画面中心位移。
+ */
+export function rubberBandLightboxTranslation(
+ value: number,
+ containerSize: number,
+ scale: number,
+ displayedSize: number,
+): number {
+ 'worklet';
+ const overflow = lightboxPanOverflow(containerSize, displayedSize, scale);
+ if (value > overflow) return overflow + lightboxRubberBand(value - overflow, containerSize);
+ if (value < -overflow) return -overflow - lightboxRubberBand(-overflow - value, containerSize);
+ return value;
+}
+
+/** {@link rubberBandLightboxTranslation} 的逆运算:画面位移还原为手指的实际位移。 */
+export function unrubberLightboxTranslation(
+ value: number,
+ containerSize: number,
+ scale: number,
+ displayedSize: number,
+): number {
+ 'worklet';
+ const overflow = lightboxPanOverflow(containerSize, displayedSize, scale);
+ if (value > overflow) return overflow + lightboxRubberBandInverse(value - overflow, containerSize);
+ if (value < -overflow) return -overflow - lightboxRubberBandInverse(-overflow - value, containerSize);
+ return value;
+}
+
+/**
+ * 捏合中某一轴的 raw translate:手指下的锚点跟手,越界部分按**当前倍率**的边界阻尼。
+ * 先算「锚点不动」时的画面位移 anchored = start + anchor·(startScale - scale),
+ * 在当前倍率下还原成手指量、加上焦点位移,再按当前倍率套橡皮筋,最后补偿回带
+ * origin 的 raw。不能把起始倍率下还原的手指量跨倍率复用:起点处在越界回弹区时,
+ * 两套边界的差会被 origin 缩放项放大,锚点从手指下滑开。
+ * startTranslate 为捏合开始时 bake 后的画面位移;起点越界且倍率未变时第一帧连续。
+ */
+export function lightboxPinchTranslation(
+ startTranslate: number,
+ anchor: number,
+ startScale: number,
+ scale: number,
+ focalDelta: number,
+ containerSize: number,
+ displayedSize: number,
+): number {
+ 'worklet';
+ const anchored = startTranslate + anchor * (startScale - scale);
+ const finger = unrubberLightboxTranslation(anchored, containerSize, scale, displayedSize) + focalDelta;
+ const visual = rubberBandLightboxTranslation(finger, containerSize, scale, displayedSize);
+ return compensateLightboxOrigin(visual, anchor, scale);
+}
+
+/**
+ * 跟手位移的橡皮筋:raw translate(可带 origin)先 bake 成画面中心,越界部分阻尼,
+ * 再补偿回 raw。origin≠0 时直接处理 raw 会按错误的边界阻尼(画面实际越界量不同),
+ * 松手 bake 再跳;origin=0 时 bake/补偿是恒等。标注双指平移与捏合同时进行时用它。
+ */
+export function rubberBandLightboxVisualPan(
+ translateX: number,
+ translateY: number,
+ originX: number,
+ originY: number,
+ containerWidth: number,
+ containerHeight: number,
+ scale: number,
+ displayedWidth: number,
+ displayedHeight: number,
+): { x: number; y: number } {
+ 'worklet';
+ return {
+ x: compensateLightboxOrigin(
+ rubberBandLightboxTranslation(
+ bakeLightboxOrigin(translateX, originX, scale),
+ containerWidth,
+ scale,
+ displayedWidth,
+ ),
+ originX,
+ scale,
+ ),
+ y: compensateLightboxOrigin(
+ rubberBandLightboxTranslation(
+ bakeLightboxOrigin(translateY, originY, scale),
+ containerHeight,
+ scale,
+ displayedHeight,
+ ),
+ originY,
+ scale,
+ ),
+ };
+}
+
+/**
+ * {@link rubberBandLightboxVisualPan} 的逆运算:捏合开始时若画面已处在越界回弹中,
+ * 先还原成手指位移再作为起点,第一帧不跳。
*/
-export function clampLightboxVisualPan(
+export function unrubberLightboxVisualPan(
translateX: number,
translateY: number,
originX: number,
@@ -149,7 +303,7 @@ export function clampLightboxVisualPan(
'worklet';
return {
x: compensateLightboxOrigin(
- clampLightboxTranslation(
+ unrubberLightboxTranslation(
bakeLightboxOrigin(translateX, originX, scale),
containerWidth,
scale,
@@ -159,7 +313,7 @@ export function clampLightboxVisualPan(
scale,
),
y: compensateLightboxOrigin(
- clampLightboxTranslation(
+ unrubberLightboxTranslation(
bakeLightboxOrigin(translateY, originY, scale),
containerHeight,
scale,
@@ -171,6 +325,112 @@ export function clampLightboxVisualPan(
};
}
+/**
+ * 增量拖动(单指平移 / 标注双指平移):当前画面先还原成手指位移,加上本帧增量,
+ * 再套橡皮筋。无状态,缩放同时变化(边界随之变化)时也连续。
+ */
+export function dragLightboxVisualPan(
+ translateX: number,
+ translateY: number,
+ deltaX: number,
+ deltaY: number,
+ originX: number,
+ originY: number,
+ containerWidth: number,
+ containerHeight: number,
+ scale: number,
+ displayedWidth: number,
+ displayedHeight: number,
+): { x: number; y: number } {
+ 'worklet';
+ const raw = unrubberLightboxVisualPan(
+ translateX,
+ translateY,
+ originX,
+ originY,
+ containerWidth,
+ containerHeight,
+ scale,
+ displayedWidth,
+ displayedHeight,
+ );
+ return rubberBandLightboxVisualPan(
+ raw.x + deltaX,
+ raw.y + deltaY,
+ originX,
+ originY,
+ containerWidth,
+ containerHeight,
+ scale,
+ displayedWidth,
+ displayedHeight,
+ );
+}
+
+/** 松手甩动低于此速度(px/s)不做惯性滑行,避免慢放手时图片还微微漂一下。 */
+export const LIGHTBOX_FLING_MIN_VELOCITY = 50;
+
+/**
+ * 平移松手后单轴的收尾方式:
+ * - settle:已越界,弹簧回到最近的边界(带松手速度,继续往外甩会先多冲一点再回)。
+ * - fling:边界内且有甩动速度,惯性滑行;滑到边界时由橡皮筋衰减冲过一点再弹回。
+ * - none:边界内慢慢放手,原地停住。
+ */
+export type LightboxPanRelease =
+ | { kind: 'settle'; to: number }
+ | { kind: 'fling'; min: number; max: number }
+ | { kind: 'none' };
+
+export function lightboxPanRelease(
+ value: number,
+ velocity: number,
+ containerSize: number,
+ scale: number,
+ displayedSize: number,
+): LightboxPanRelease {
+ 'worklet';
+ const overflow = lightboxPanOverflow(containerSize, displayedSize, scale);
+ if (value > overflow) return { kind: 'settle', to: overflow };
+ if (value < -overflow) return { kind: 'settle', to: -overflow };
+ if (Math.abs(velocity) < LIGHTBOX_FLING_MIN_VELOCITY) return { kind: 'none' };
+ return { kind: 'fling', min: -overflow, max: overflow };
+}
+
+/**
+ * 捏合松手后的落点:倍率回到 [1, 最大倍率],位移回到该倍率的边界内。
+ * 捏过最大倍率时绕最后的焦点缩回,手指下那一点保持不动;缩到 1x 及以下一律回正。
+ * translate 为 bake 后(origin=0)的位移,focal 为焦点相对容器中心的坐标。
+ */
+export function lightboxPinchSettle(input: {
+ scale: number;
+ translateX: number;
+ translateY: number;
+ focalX: number;
+ focalY: number;
+ containerWidth: number;
+ containerHeight: number;
+ displayedWidth: number;
+ displayedHeight: number;
+}): { scale: number; x: number; y: number } {
+ 'worklet';
+ if (!isLightboxZoomed(input.scale)) return { scale: LIGHTBOX_MIN_SCALE, x: 0, y: 0 };
+ const scale = Math.min(input.scale, LIGHTBOX_MAX_SCALE);
+ let x = input.translateX;
+ let y = input.translateY;
+ if (scale !== input.scale) {
+ // 焦点 F 下的图片点 p 满足 F = p·s + T;缩到 s' 后保持 F 不动:T' = F - (F - T)·s'/s。
+ // 倍率不变时跳过,免得浮点误差让本已合法的落点也起一段动画。
+ const ratio = scale / input.scale;
+ x = input.focalX - (input.focalX - input.translateX) * ratio;
+ y = input.focalY - (input.focalY - input.translateY) * ratio;
+ }
+ return {
+ scale,
+ x: clampLightboxTranslation(x, input.containerWidth, scale, input.displayedWidth),
+ y: clampLightboxTranslation(y, input.containerHeight, scale, input.displayedHeight),
+ };
+}
+
/**
* 双击目标平移:点击点在缩放到 targetScale 后仍停在原处;缩回 1x 时归零。
*/
diff --git a/docs/design-rules/DESIGN.md b/docs/design-rules/DESIGN.md
index 029cda6bf9..5402906564 100644
--- a/docs/design-rules/DESIGN.md
+++ b/docs/design-rules/DESIGN.md
@@ -1064,6 +1064,8 @@ long duration to leak into any other hover or transition.
**Mobile list disclosure rhythm (owner request, 2026-09-30).** On mobile, expanding and collapsing list groups (home pinned / shared / project / conversation groups, automation run groups on the home and device pages, the collapsible Settings debug group) and task-row moves from archive, unarchive, pin or unpin (rows leaving stay visible while the rows below close over them, then fade) follow the iOS system list rhythm instead of the Desktop `base` tier (200ms): 225ms quadratic ease-out with no overshoot, reaching about 90% of the travel within 150ms (the owner asked for the first 450ms version to be halved the same day). The group opens from under its header: list cells clip their content while their position and height animate, new rows sit at their final positions and are revealed as the group grows, and the rows below move down in step; new rows do not fade in place. Collapsing reverses this: removed rows stay visible while the group closes over them and fade only near the end. The disclosure chevron switches without animation. The duration lives in mobile's `listDisclosureMotion` token and the shared implementation is `apps/mobile/src/session/listDisclosureTransition.tsx` (Reanimated layout animations, attached only during the transition window; React Native `LayoutAnimation` is a no-op in this app because Reanimated owns the Fabric mounting layer). Reduced motion switches instantly. This exception does not apply to Desktop, sheets, dialogs, or other panels.
+**Mobile image viewer edge elasticity (owner request, 2026-10-10).** In the mobile full-screen image viewer (`apps/mobile/src/session/ImageLightbox.tsx`), direct manipulation follows the system Photos physics instead of hard stops: a zoomed one-finger pan may run past the image edge with rubber-band resistance (UIScrollView coefficient 0.55 over the container size), and a pinch may overshoot 1x / the maximum zoom with the same resistance. On release, anything out of bounds returns on a near-critically damped spring (no visible oscillation, about 0.3s); an in-bounds release continues with inertial decay that may briefly overrun the edge and return; a touch catches it in place. Scale and translation settle on the same spring so the point under the fingers stays put. These are physics responses to the hand, not duration-tier transitions, so they use spring/decay parameters rather than motion tokens; the parameters and decisions live in `imageLightboxModel.ts`. A single image at 1x keeps the native horizontal edge bounce. This exception does not apply to any other surface.
+
#### Semantics → motion prototypes (one semantic, one motion, app-wide)
| Semantic | Spec | Reference implementation |