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。

21.1 KB
Raw Blame
/**
 * imageLightboxModel.ts — 全屏图片查看器的手势/布局决策纯函数。
 * ---------------------------------------------------------------------------
 * ImageLightbox 组件里的 worklet 只做数值搬运,所有"判定"(缩放边界、平移钳制、
 * 越界橡皮筋与松手回弹、下滑释放是否关闭、背景透明度、页索引)集中在这里,
 * node 环境可单测。
 */

export const LIGHTBOX_MIN_SCALE = 1;
export const LIGHTBOX_MAX_SCALE = 4;
/** 双击放大的目标倍率(IM 惯例 2~3 倍之间)。 */
export const LIGHTBOX_DOUBLE_TAP_SCALE = 2.5;
/** 视为「已放大」的最小超出量,避免 1.0001 这种浮点噪声锁住翻页。 */
export const LIGHTBOX_ZOOM_EPS = 0.01;
/** 下滑关闭:位移超过此值(px)或速度超过 velocity 阈值即关闭。 */
export const LIGHTBOX_DISMISS_DISTANCE = 120;
export const LIGHTBOX_DISMISS_VELOCITY = 800;
/**
 * 单击(切换 chrome)允许的最大位移(pt)。RNGH Tap 默认 maxDist 为无限(NAN 跳过校验),
 * 与平移 Simultaneous 时,500ms 内的短拖松手会被当成单击,工具栏被意外切掉。
 */
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;

/**
 * 越界量 → 实际显示的越界距离:越拉阻力越大,渐近 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 (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;
}

export function isLightboxZoomed(scale: number): boolean {
  'worklet';
  return scale > LIGHTBOX_MIN_SCALE + LIGHTBOX_ZOOM_EPS;
}

/**
 * contain 适配后的显示尺寸。自然尺寸未知时退回容器(按铺满估算,宁可少拖一点)。
 * 与 annotationBaseRect 同源,但不返回 left/top——平移钳制只需要边长。
 */
export function lightboxContainedSize(
  containerWidth: number,
  containerHeight: number,
  naturalWidth: number,
  naturalHeight: number,
): { width: number; height: number } {
  'worklet';
  if (containerWidth <= 0 || containerHeight <= 0 || naturalWidth <= 0 || naturalHeight <= 0) {
    return { width: containerWidth, height: containerHeight };
  }
  const fit = Math.min(containerWidth / naturalWidth, containerHeight / naturalHeight);
  return { width: naturalWidth * fit, height: naturalHeight * fit };
}

/** 某轴允许的平移半幅:放大后的显示边超出容器的一半;未超出则为 0。 */
export function lightboxPanOverflow(
  containerSize: number,
  displayedSize: number,
  scale: number,
): number {
  'worklet';
  const size = displayedSize <= 0 ? containerSize : displayedSize;
  return Math.max(0, (size * scale - containerSize) / 2);
}

/**
 * 放大后的平移钳制:图片按 contain 显示后再乘 scale,超出容器的部分才允许平移;
 * 未超出的轴锁死在 0,防止把图拖出屏幕。displayedSize 缺省时按铺满容器估算
 * (旧调用点 / 自然尺寸未到)。
 */
export function clampLightboxTranslation(
  value: number,
  containerSize: number,
  scale: number,
  displayedSize?: number,
): number {
  'worklet';
  const overflow = lightboxPanOverflow(
    containerSize,
    displayedSize == null ? containerSize : displayedSize,
    scale,
  );
  if (value < -overflow) return -overflow;
  if (value > overflow) return overflow;
  return value;
}

/**
 * 显示尺寸变化后(自然尺寸到达 / 旋转)按新 contain 边界重钳位移。
 * 未知尺寸按铺满容器估算,横图 onLoad 后高变小,旧位移必须立刻收回,
 * 不能等下次拖动手才跳回边界。
 */
export function reclampLightboxPan(
  translateX: number,
  translateY: number,
  containerWidth: number,
  containerHeight: number,
  scale: number,
  displayedWidth: number,
  displayedHeight: number,
): { x: number; y: number } {
  'worklet';
  return {
    x: clampLightboxTranslation(translateX, containerWidth, scale, displayedWidth),
    y: clampLightboxTranslation(translateY, containerHeight, scale, displayedHeight),
  };
}

/** 捏合焦点相对容器中心,作为 scale 的 transform origin。 */
export function lightboxPinchOrigin(focal: number, containerSize: number): number {
  'worklet';
  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
 *    = p * scale + origin * (1 - scale) + translate
 */
export function bakeLightboxOrigin(translate: number, origin: number, scale: number): number {
  'worklet';
  return translate + origin * (1 - scale);
}

/**
 * bake 的逆运算:已有缩放时再设 origin,从 translate 扣掉 origin*(1-scale),
 * 画面公式不变。二次捏合若不补偿,imageStyle 会立刻加上 origin*(1-scale) 跳一下,
 * 结束时 bake 还会把这次跳变写进位移。
 */
export function compensateLightboxOrigin(translate: number, origin: number, scale: number): number {
  'worklet';
  return translate - origin * (1 - scale);
}

/**
 * 平移的橡皮筋:边界内原样;越过图片边缘(含未溢出、钳在 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 unrubberLightboxVisualPan(
  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(
      unrubberLightboxTranslation(
        bakeLightboxOrigin(translateX, originX, scale),
        containerWidth,
        scale,
        displayedWidth,
      ),
      originX,
      scale,
    ),
    y: compensateLightboxOrigin(
      unrubberLightboxTranslation(
        bakeLightboxOrigin(translateY, originY, scale),
        containerHeight,
        scale,
        displayedHeight,
      ),
      originY,
      scale,
    ),
  };
}

/**
 * 增量拖动(单指平移 / 标注双指平移):当前画面先还原成手指位移,加上本帧增量,
 * 再套橡皮筋。无状态,缩放同时变化(边界随之变化)时也连续。
 */
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 时归零。
 */
export function lightboxDoubleTapTranslate(
  tap: number,
  containerSize: number,
  targetScale: number,
): number {
  'worklet';
  if (!isLightboxZoomed(targetScale)) return 0;
  return lightboxPinchOrigin(tap, containerSize) * (1 - targetScale);
}

/**
 * 下滑手势释放时是否应关闭(距离或甩动速度任一超阈值)。
 * 放大后一律不关:contain 横图即使 2.5x 也常无纵向溢出,同一记向下滑会被 Simultaneous
 * 的关闭手势当成 dismiss;scale 必须参与判定,不能只靠手势 fail()。
 */
export function shouldDismissLightbox(
  translationY: number,
  velocityY: number,
  scale: number = LIGHTBOX_MIN_SCALE,
): boolean {
  'worklet';
  if (isLightboxZoomed(scale)) return false;
  return Math.abs(translationY) > LIGHTBOX_DISMISS_DISTANCE
    || Math.abs(velocityY) > LIGHTBOX_DISMISS_VELOCITY;
}

/** 下滑拖动中的背景不透明度:拖过半屏降到 0.3,跟手渐隐。 */
export function lightboxBackgroundOpacity(translationY: number, containerHeight: number): number {
  'worklet';
  if (containerHeight <= 0) return 1;
  const progress = Math.min(1, Math.abs(translationY) / (containerHeight / 2));
  return 1 - progress * 0.7;
}

/** 双击在 1x 与放大倍率间切换。 */
export function nextDoubleTapScale(currentScale: number): number {
  'worklet';
  return isLightboxZoomed(currentScale) ? LIGHTBOX_MIN_SCALE : LIGHTBOX_DOUBLE_TAP_SCALE;
}

/** 横向分页偏移 → 页索引(pagingEnabled 的 momentum end)。 */
export function lightboxPageIndex(offsetX: number, pageWidth: number, pageCount: number): number {
  if (pageWidth <= 0 || pageCount <= 0) return 0;
  const index = Math.round(offsetX / pageWidth);
  return Math.min(Math.max(index, 0), pageCount - 1);
}

/**
 * 初始页:按 url 定位,找不到回退 0(单图打开必命中)。
 * 两侧都 trim:gallery 键是 trimmed url,而 initialUrl 来自未 trim 的
 * payload.media.url,带空白的 url 不 trim 会静默落回第 0 张。
 */
export function lightboxInitialIndex(urls: readonly string[], initialUrl: string): number {
  const target = initialUrl.trim();
  const index = urls.findIndex((url) => url.trim() === target);
  return index >= 0 ? index : 0;
}

/** 页码指示文案;单图不显示。 */
export function lightboxPageLabel(index: number, count: number): string | null {
  if (count <= 1) return null;
  return `${index + 1} / ${count}`;
}

/** 单页的图像层可见性(见 {@link lightboxImageLayers})。 */
export interface LightboxImageLayers {
  /** 是否渲染缩略图垫底层(在原图层之下)。 */
  showPreview: boolean;
  /** 是否渲染转圈(仅在连缩略图都没有、否则就是纯黑时)。 */
  showSpinner: boolean;
  /** 是否渲染整页失败(原图已确证失败且没有可用显示层,不能永远转圈)。 */
  showFailure: boolean;
}

/**
 * 渐进出图的层决策:打开瞬间必须有像素接住画面。
 *
 * 点开的图在聊天列表里已经解码好了,所以缩略图从**打开那一刻**就垫在底下,
 * 一直垫到原图 `onLoad` 真正落地(有像素)才撤 —— 空档窗口有两段,取件在途
 * (还没有原图地址)与原图地址已拿到、字节仍在下载,两段都必须被垫住。
 * 此前只垫住了第一段(且垫底状态挂在取件态里,取件一完成就连带丢失),于是
 * 第二段裸露成纯黑:用户已经在列表看过这张图,点开反而先黑一段再跳出来。
 *
 * 拿不到缩略图时(直连 http 图、缓存未命中)退一步给转圈:宁可有反馈,
 * 不要纯黑无提示。有缩略图时**不叠**转圈 —— 画面已经完整可读(只是软),
 * 再压一个转圈反而制造"还在加载"的噪声,对齐主流 IM 的渐进出图观感。
 *
 * 但「有地址」不等于「有像素」:缩略图的磁盘文件可能被 LRU / 系统清理掉,而取件
 * 队列的内存缓存仍持有那个永不过期的 file://。这种垫底图根本画不出来,若仍据此
 * 隐藏转圈,整段就退回纯黑、还比旧实现少了转圈反馈,所以 previewFailed 必须参与
 * 判定(PR #1125 review;DESIGN.md 双模式门槛也要求改动触及的 loading / error 态
 * 都被覆盖)。
 */
export function lightboxImageLayers(input: {
  /** 原图可渲染地址;取件完成前为 null。 */
  fullUri: string | null;
  /** 列表缩略图地址;取不到为 null。 */
  previewUri: string | null;
  /** 原图是否已 onLoad。仅在与当前 fullUri 对应时为 true(换图即失效)。 */
  fullLoaded: boolean;
  /** 垫底图是否已确认 onError(文件被清理等);失败的垫底不能顶替转圈。 */
  previewFailed?: boolean;
  /**
   * 原图取件已失败 / 不支持,或原生 onError 的自动恢复已结束。
   * 没有可用原图与预览时给失败终态;保留用户主动重试的入口。
   */
  fullFailedTerminally?: boolean;
}): LightboxImageLayers {
  // fullUri 为空时 fullLoaded 一律不成立:防调用方漏重置造成"已加载"的假阳性
  // (会把垫底和转圈同时撤掉,又回到纯黑)。
  if (input.fullUri && input.fullLoaded) {
    return { showPreview: false, showSpinner: false, showFailure: false };
  }
  // 垫底可用时优先给内容(软图也是内容),胜过失败文案与转圈。
  if (input.previewUri && !input.previewFailed) {
    return { showPreview: true, showSpinner: false, showFailure: false };
  }
  if (input.fullFailedTerminally) {
    return { showPreview: false, showSpinner: false, showFailure: true };
  }
  return { showPreview: false, showSpinner: true, showFailure: false };
}

/** 可分享判定:本地 file:// 直接分享;http(s) 可下载后分享;data: 不支持。 */
export function canShareLightboxImage(displayUri: string | null): boolean {
  if (!displayUri) return false;
  return displayUri.startsWith('file://') || displayUri.startsWith('http://') || displayUri.startsWith('https://');
}