feat(ImageViewer): 支持视口之外图片向中心缩放

- 重构 useScale hook，新增 ZoomOptions/ZoomResult 接口，支持基于缩放中心的位移补偿算法
- 重构 usePosition hook，暴露 setPosition 和 resetPosition 接口
- ImageModalItem 改为 forwardRef，通过 useImperativeHandle 暴露内部状态
- ImageModal 实现滚轮缩放时视口外图片向中心收敛逻辑
- 缩放操作添加 50ms 节流优化

参考: Tencent/tdesign-vue-next#6406

Author: RSS1102

packages/components/image-viewer/ImageViewerModal.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import classNames from 'classnames';
 import { isArray, isFunction } from 'lodash-es';
 import {
@@ -20,14 +20,26 @@ import { ImageModalMini } from './ImageViewerMini';
 import useIconMap from './hooks/useIconMap';
 import useIndex from './hooks/useIndex';
 import useMirror from './hooks/useMirror';
-import usePosition from './hooks/usePosition';
+import usePosition, { PositionType } from './hooks/usePosition';
 import useRotate from './hooks/useRotate';
 import useScale from './hooks/useScale';
 
 import type { TNode } from '../common';
 import type { ImageViewerProps } from './ImageViewer';
 import type { ImageInfo, ImageScale, ImageViewerScale, TdImageViewerProps } from './type';
 
+/** ImageModalItem 暴露给父组件的接口 */
+export interface ImageModalItemRef {
+  /** modal-box 容器 DOM 引用 */
+  modalBoxRef: React.RefObject<HTMLDivElement>;
+  /** 当前位移 */
+  position: PositionType;
+  /** 设置位移 */
+  setPosition: React.Dispatch<React.SetStateAction<PositionType>>;
+  /** 重置位移 */
+  resetPosition: () => void;
+}
+
 const ImageError = ({ errorText }: { errorText: string }) => {
   const { classPrefix } = useConfig();
   const { ImageErrorIcon } = useGlobalIcon({ ImageErrorIcon: TdImageErrorIcon });
@@ -55,7 +67,7 @@ interface ImageModalItemProps {
 }
 
 // 单个弹窗实例
-export const ImageModalItem: React.FC<ImageModalItemProps> = ({
+export const ImageModalItem = React.forwardRef<ImageModalItemRef, ImageModalItemProps>(({
   rotateZ,
   scale,
   src,
@@ -65,11 +77,12 @@ export const ImageModalItem: React.FC<ImageModalItemProps> = ({
   imageReferrerpolicy,
   isSvg,
   innerClassName,
-}) => {
+}, ref) => {
   const { classPrefix } = useConfig();
 
   const imgRef = useRef<HTMLImageElement>(null);
   const svgRef = useRef<HTMLDivElement>(null);
+  const modalBoxRef = useRef<HTMLDivElement>(null);
 
   const [loaded, setLoaded] = useState(false);
   const [error, setError] = useState(false);
@@ -86,10 +99,18 @@ export const ImageModalItem: React.FC<ImageModalItemProps> = ({
     if (isSvg) return svgRef;
     return imgRef;
   }, [isSvg]);
-  const { position } = usePosition(displayRef);
+  const { position, setPosition, resetPosition } = usePosition(displayRef);
   const preImgStyle = { transform: `rotateZ(${rotateZ}deg) scale(${scale})`, display: !loaded ? 'block' : 'none' };
   const boxStyle = { transform: `translate(${position[0]}px, ${position[1]}px) scale(${mirror}, 1)` };
 
+  // 暴露内部状态，供父组件在缩放时读写 position
+  useImperativeHandle(ref, () => ({
+    modalBoxRef,
+    position,
+    setPosition,
+    resetPosition,
+  }), [position, setPosition, resetPosition]);
+
   const createSvgShadow = async (url: string) => {
     const response = await fetch(url);
     if (!response.ok) {
@@ -148,7 +169,7 @@ export const ImageModalItem: React.FC<ImageModalItemProps> = ({
 
   return (
     <div className={classNames(`${classPrefix}-image-viewer__modal-pic`, innerClassName)}>
-      <div className={`${classPrefix}-image-viewer__modal-box`} style={boxStyle}>
+      <div ref={modalBoxRef} className={`${classPrefix}-image-viewer__modal-box`} style={boxStyle}>
         {error && <ImageError errorText={errorText} />}
         {/* 预览图 */}
         {!error && !!preSrc && preSrcImagePreviewUrl && (
@@ -188,7 +209,9 @@ export const ImageModalItem: React.FC<ImageModalItemProps> = ({
       </div>
     </div>
   );
-};
+});
+
+ImageModalItem.displayName = 'ImageModalItem';
 
 // 旋转角度单位
 const ROTATE_COUNT = 90;
@@ -445,10 +468,14 @@ export const ImageModal: React.FC<ImageModalProps> = (props) => {
   const { scale, onZoom, onZoomOut, onResetScale } = useScale(imageScale, visible);
   const { mirror, onResetMirror, onMirror } = useMirror();
 
+  const containerRef = useRef<HTMLDivElement>(null);
+  const imageItemRef = useRef<ImageModalItemRef>(null);
+
   const onReset = useCallback(() => {
     onResetScale();
     onResetRotate();
     onResetMirror();
+    imageItemRef.current?.resetPosition?.();
   }, [onResetMirror, onResetScale, onResetRotate]);
 
   const onKeyDown = useCallback(
@@ -469,6 +496,80 @@ export const ImageModal: React.FC<ImageModalProps> = (props) => {
     [next, onClose, prev, onZoom, onZoomOut, closeOnEscKeydown],
   );
 
+  // 检测图片是否超出视口
+  const isImageExceedsViewport = useCallback(
+    (container: HTMLDivElement, modalBox: HTMLDivElement): boolean => {
+      const containerRect = container.getBoundingClientRect();
+      const modalRect = modalBox.getBoundingClientRect();
+      return (
+        modalRect.left < containerRect.left ||
+        modalRect.right > containerRect.right ||
+        modalRect.top < containerRect.top ||
+        modalRect.bottom > containerRect.bottom
+      );
+    },
+    [],
+  );
+
+  // 滚轮缩放处理
+  const handleWheelZoom = useCallback(
+    (e: WheelEvent) => {
+      const isZoomingOut = e.deltaY > 0;
+
+      const container = containerRef.current;
+      const modalBox = imageItemRef.current?.modalBoxRef?.current;
+
+      // 无视口信息时，直接缩放
+      if (!container || !modalBox) {
+        isZoomingOut ? onZoomOut() : onZoom();
+        return;
+      }
+
+      // 缩小且图片超出视口：以视口中心为基准，向视口中心收敛
+      if (isZoomingOut && isImageExceedsViewport(container, modalBox)) {
+        const currentPosition = imageItemRef.current?.position ?? [0, 0];
+        const currentTranslate = {
+          translateX: currentPosition[0],
+          translateY: currentPosition[1],
+        };
+
+        const result = onZoomOut({
+          mouseOffsetX: 0,
+          mouseOffsetY: 0,
+          currentTranslate,
+        });
+
+        if (result?.newTranslate) {
+          imageItemRef.current?.setPosition?.([
+            result.newTranslate.translateX,
+            result.newTranslate.translateY,
+          ]);
+        }
+      } else {
+        // 正常缩放
+        isZoomingOut ? onZoomOut() : onZoom();
+      }
+    },
+    [onZoom, onZoomOut, isImageExceedsViewport],
+  );
+
+  // 滚轮事件
+  const onWheel = useCallback(
+    (e: WheelEvent) => {
+      e.preventDefault();
+      handleWheelZoom(e);
+    },
+    [handleWheelZoom],
+  );
+
+  useEffect(() => {
+    if (!visible) return;
+    document.addEventListener('wheel', onWheel, { passive: false });
+    return () => {
+      document.removeEventListener('wheel', onWheel);
+    };
+  }, [visible, onWheel]);
+
   useEffect(() => {
     document.addEventListener('keydown', onKeyDown);
     return () => document.removeEventListener('keydown', onKeyDown);
@@ -537,6 +638,7 @@ export const ImageModal: React.FC<ImageModalProps> = (props) => {
 
   return (
     <div
+      ref={containerRef}
       className={classNames(
         `${classPrefix}-image-viewer-preview-image`,
         {
@@ -594,6 +696,7 @@ export const ImageModal: React.FC<ImageModalProps> = (props) => {
       />
       {closeNode}
       <ImageModalItem
+        ref={imageItemRef}
         innerClassName={innerClassName}
         scale={scale}
         rotateZ={rotateZ}

packages/components/image-viewer/hooks/usePosition.ts

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 import useMouseEvent from '../../hooks/useMouseEvent';
 
 export type PositionType = [number, number];
@@ -33,8 +33,14 @@ const usePosition = (imgRef: React.RefObject<HTMLDivElement>, options?: Position
     },
   });
 
+  const resetPosition = useCallback(() => {
+    setPosition(initPosition);
+  }, [initPosition]);
+
   return {
     position,
+    setPosition,
+    resetPosition,
   };
 };