feat(ImageViewer): support drag and mouse-centered zoom

Author: RSS1102

packages/components/image-viewer/_example/base.vue

@@ -1,6 +1,16 @@
 <template>
   <div class="tdesign-demo-image-viewer__base">
-    <t-image-viewer :images="[img]" :z-index="10000"></t-image-viewer>
+    <t-image-viewer
+      :images="[img]"
+      :z-index="10000"
+      draggable-overlay
+      :image-scale="{
+        // max: 5,
+        // min: 0.2,
+        // step: 0.3,
+        scaleFromMousePosition: true, // 启用鼠标位置缩放
+      }"
+    ></t-image-viewer>
   </div>
 </template>
 <script setup>

packages/components/image-viewer/base/ImageItem.tsx

@@ -15,17 +15,42 @@ export default defineComponent({
     placementSrc: [String, Object] as PropType<string | File>,
     isSvg: Boolean,
     imageReferrerpolicy: String as PropType<TdImageViewerProps['imageReferrerpolicy']>,
+    // 接收外部传入的拖拽状态和处理器
+    transform: {
+      type: Object as PropType<{ translateX: number; translateY: number }>,
+      default: () => ({ translateX: 0, translateY: 0 }),
+    },
+    mouseDownHandler: {
+      type: Function as PropType<(e: MouseEvent) => void>,
+      default: undefined,
+    },
   },
 
-  setup(props) {
-    const { src, placementSrc, isSvg } = toRefs(props);
+  setup(props, { expose }) {
+    const {
+      src,
+      placementSrc,
+      isSvg,
+      transform: transformProp,
+      mouseDownHandler: mouseDownHandlerProp,
+    } = toRefs(props);
     const classPrefix = usePrefixClass();
     const error = ref(false);
     const loaded = ref(false);
-    const { transform, mouseDownHandler } = useDrag({ translateX: 0, translateY: 0 });
+    // 使用外部传入的 transform 和 mouseDownHandler，如果没有则使用内部的
+    const { transform: internalTransform, mouseDownHandler: internalMouseDownHandler } = useDrag({
+      translateX: 0,
+      translateY: 0,
+    });
+    const transform = transformProp.value ? transformProp : internalTransform;
+    const mouseDownHandler = mouseDownHandlerProp.value || internalMouseDownHandler;
     const { globalConfig } = useConfig('imageViewer');
     const errorText = globalConfig.value.errorText;
     const svgElRef = ref<HTMLDivElement>();
+    const modalBoxRef = ref<HTMLDivElement>();
+
+    // 暴露 modal-box ref，用于检测鼠标是否在图片上
+    expose({ modalBoxRef });
 
     const imgStyle = computed(() => ({
       transform: `rotate(${props.rotate}deg)`,
@@ -121,7 +146,7 @@ export default defineComponent({
 
     return () => (
       <div class={`${classPrefix.value}-image-viewer__modal-pic`}>
-        <div class={`${classPrefix.value}-image-viewer__modal-box`} style={boxStyle.value}>
+        <div ref={modalBoxRef} class={`${classPrefix.value}-image-viewer__modal-box`} style={boxStyle.value}>
           {error.value && (
             <div class={`${classPrefix.value}-image-viewer__img-error`}>
               {/* 脱离文档流 */}

packages/components/image-viewer/base/ImageViewerModal.tsx

@@ -44,6 +44,15 @@ export default defineComponent({
     showOverlay: Boolean,
     closeBtn: props.closeBtn,
     imageReferrerpolicy: props.imageReferrerpolicy,
+    // 接收外部传入的拖拽状态和处理器
+    transform: {
+      type: Object as PropType<{ translateX: number; translateY: number }>,
+      default: undefined,
+    },
+    mouseDownHandler: {
+      type: Function as PropType<(e: MouseEvent) => void>,
+      default: undefined,
+    },
   },
   setup(props) {
     const classPrefix = usePrefixClass();
@@ -93,6 +102,8 @@ export default defineComponent({
             placementSrc={props.currentImage.thumbnail}
             isSvg={props.currentImage.isSvg}
             imageReferrerpolicy={props.imageReferrerpolicy}
+            transform={props.transform}
+            mouseDownHandler={props.mouseDownHandler}
           />
         </div>
       </TDialog>

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

@@ -1,14 +1,23 @@
 import { positiveSubtract, positiveAdd } from '@tdesign/common-js/input-number/number';
 import { ref, watch } from 'vue';
 import { ImageScale } from '../type';
-import { throttle } from 'lodash-es';
 
 interface InitTransform {
   translateX: number;
   translateY: number;
 }
 
-export function useDrag(initTransform: InitTransform) {
+interface DragOptions {
+  maxTranslateX?: number;
+  maxTranslateY?: number;
+}
+
+export function useDrag(
+  initTransform: InitTransform,
+  onDragStart?: () => void,
+  onDragEnd?: (distance: number) => void,
+  options?: DragOptions,
+) {
   const transform = ref(initTransform);
 
   const mouseDownHandler = (e: MouseEvent) => {
@@ -17,18 +26,41 @@ export function useDrag(initTransform: InitTransform) {
 
     const { pageX: startX, pageY: startY } = e;
     const { translateX, translateY } = transform.value;
+    let totalDistance = 0;
+
+    onDragStart?.();
+
     const mouseMoveHandler = (e: MouseEvent) => {
       const { pageX, pageY } = e;
+      const deltaX = pageX - startX;
+      const deltaY = pageY - startY;
+
+      // 计算移动距离
+      const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+      totalDistance = distance;
+
+      let newTranslateX = translateX + deltaX;
+      let newTranslateY = translateY + deltaY;
+
+      // 应用边界限制
+      if (options?.maxTranslateX !== undefined) {
+        newTranslateX = Math.max(-options.maxTranslateX, Math.min(options.maxTranslateX, newTranslateX));
+      }
+      if (options?.maxTranslateY !== undefined) {
+        newTranslateY = Math.max(-options.maxTranslateY, Math.min(options.maxTranslateY, newTranslateY));
+      }
+
       transform.value = {
-        translateX: translateX + pageX - startX,
-        translateY: translateY + pageY - startY,
+        translateX: newTranslateX,
+        translateY: newTranslateY,
       };
     };
 
     const removeHandler = () => {
       document.removeEventListener('mousemove', mouseMoveHandler);
       document.removeEventListener('mouseup', mouseUpHandler);
       document.removeEventListener('mouseleave', mouseLeaveHandler);
+      onDragEnd?.(totalDistance);
     };
 
     const mouseUpHandler = () => removeHandler();
@@ -58,34 +90,79 @@ export function useMirror() {
   return { mirror, onMirror, resetMirror };
 }
 
+export interface ZoomOptions {
+  /** 鼠标相对于容器中心的 X 偏移 */
+  mouseOffsetX?: number;
+  /** 鼠标相对于容器中心的 Y 偏移 */
+  mouseOffsetY?: number;
+  /** 当前的位移值 */
+  currentTranslate?: { translateX: number; translateY: number };
+}
+
+export interface ZoomResult {
+  /** 新的位移值（用于替换，而不是累加） */
+  newTranslate?: { translateX: number; translateY: number };
+}
+
 export function useScale(imageScale: ImageScale) {
   const params = { max: 2, min: 0.5, step: 0.2, defaultScale: 1, ...imageScale };
   const { max, min, step, defaultScale } = params;
   const scale = ref(defaultScale);
 
-  const onZoomIn = throttle(() => {
-    const result = positiveAdd(scale.value, step);
-    setScale(result);
-  }, 50);
+  /**
+   * 计算缩放后的位移补偿，保持鼠标指向的图片内容在屏幕上的位置不变
+   *
+   * 公式推导：设 Z = 缩放中心(鼠标位置)，T = 当前位移，λ'/λ = scaleRatio
+   * newTranslate = scaleRatio * T + (1 - scaleRatio) * Z
+   */
+  const calculateTranslateOffset = (
+    oldScale: number,
+    newScale: number,
+    options?: ZoomOptions,
+  ): { translateX: number; translateY: number } | undefined => {
+    // 缺少鼠标位置信息时，不计算位移补偿
+    if (options?.mouseOffsetX == null || options?.mouseOffsetY == null) {
+      return undefined;
+    }
+
+    const scaleRatio = newScale / oldScale;
+    const { translateX = 0, translateY = 0 } = options?.currentTranslate ?? {};
+    const { mouseOffsetX, mouseOffsetY } = options;
+
+    return {
+      translateX: scaleRatio * translateX + (1 - scaleRatio) * mouseOffsetX,
+      translateY: scaleRatio * translateY + (1 - scaleRatio) * mouseOffsetY,
+    };
+  };
 
-  const onZoomOut = throttle(() => {
-    const result = positiveSubtract(scale.value, step);
-    setScale(result);
-  }, 50);
+  const onZoomIn = (options?: ZoomOptions): ZoomResult => {
+    const oldScale = scale.value;
+    const result = positiveAdd(oldScale, step);
+    const newScale = Math.min(result, max);
+    setScale(newScale);
+
+    return {
+      newTranslate: calculateTranslateOffset(oldScale, newScale, options),
+    };
+  };
+
+  const onZoomOut = (options?: ZoomOptions): ZoomResult => {
+    const oldScale = scale.value;
+    const result = positiveSubtract(oldScale, step);
+    const newScale = Math.max(result, min);
+    setScale(newScale);
+
+    return {
+      newTranslate: calculateTranslateOffset(oldScale, newScale, options),
+    };
+  };
 
   const resetScale = () => {
     scale.value = defaultScale;
   };
 
   const setScale = (newScale: number) => {
-    let value = newScale;
-    if (newScale < min) {
-      value = min;
-    }
-    if (newScale > max) {
-      value = max;
-    }
-    scale.value = value;
+    scale.value = Math.max(min, Math.min(max, newScale));
   };
 
   watch(