fix(ImageViewer): 优化处理自定义渲染内容 (ant-design#6904)

* fix: 优化处理自定义渲染内容

* fix: 优化代码ts类型

* fix: 去掉新增属性限制完全自定义，知道用户使用HOC

* fix: 移除多余逗号

* fix: 修改md和格式化

* fix: 增加FAQ备注

* fix: 优化ref逻辑处理问题

* fix: 优化ref逻辑处理问题

* fix: 增加test case

* fix: 增加test case

* fix: 增加test case

* fix: 优化注释和代码

* fix: 修改ref逻辑，让用户自行决定是否使用

* fix: 修改ref逻辑，让用户自行决定是否使用

* fix: 调整ts类型

* fix: 格式化内容

Author: 984507092

.vscode/settings.json

@@ -46,5 +46,8 @@
   },
   "[jsonc]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
   }
 }

src/components/image-viewer/image-viewer.tsx

@@ -1,5 +1,5 @@
 import classNames from 'classnames'
-import type { FC, ReactNode } from 'react'
+import type { FC, ReactNode, RefObject } from 'react'
 import React, {
   forwardRef,
   useCallback,
@@ -27,7 +27,10 @@ export type ImageViewerProps = {
   onClose?: () => void
   afterClose?: () => void
   renderFooter?: (image: string) => ReactNode
-  imageRender?: (image: string, { index }: { index: number }) => ReactNode
+  imageRender?: (
+    image: string,
+    { ref, index }: { ref: RefObject<HTMLImageElement>; index: number }
+  ) => ReactNode
   classNames?: {
     mask?: string
     body?: string
@@ -88,7 +91,10 @@ export type MultiImageViewerProps = Omit<
   defaultIndex?: number
   onIndexChange?: (index: number) => void
   renderFooter?: (image: string, index: number) => ReactNode
-  imageRender?: (image: string, { index }: { index: number }) => ReactNode
+  imageRender?: (
+    image: string,
+    { ref, index }: { ref: RefObject<HTMLImageElement>; index: number }
+  ) => ReactNode
 }
 
 const multiDefaultProps = {

src/components/image-viewer/index.en.md

@@ -21,7 +21,7 @@ You need to click on the picture to view the details and use it with the thumbna
 | maxZoom | The maximum zoom ratio | `number \| 'auto'` | `3` |  |
 | onClose | Triggered when it is closed | `() => void` | - |  |
 | renderFooter | Render extra content on footer | `(image: string) => ReactNode` | - |  |
-| imageRender | Custom rendering content | `(image: string, { index }: { index: number }) => ReactNode` | - | 5.39.0 |
+| imageRender | Custom rendering content | `(image: string,{ ref, index }: { ref: RefObject<HTMLImageElement>; index: number }) => ReactNode` | - | 5.39.0 |
 | visible | Whether to show or hide | `boolean` | `false` |  |
 
 ## ImageViewer.Multi
@@ -35,7 +35,7 @@ On the basis of `ImageViewer`, the following props have been added:
 | images | Url list of image resources | `string[]` | - |  |
 | onIndexChange | Triggered when the picture is switched | `(index: number) => void` | - |  |
 | renderFooter | Render extra content on footer | `(image: string, index: number) => ReactNode` | - |  |
-| imageRender | Custom rendering content | `(image: string, { index }: { index: number }) => ReactNode` | - |  |
+| imageRender | Custom rendering content | `(image: string,{ ref, index }: { ref: RefObject<HTMLImageElement>; index: number }) => ReactNode` | - |  |
 
 At the same time, the `image` prop is removed.
 
@@ -89,3 +89,26 @@ ImageViewer.Multi is an [uncontrolled](https://reactjs.org/docs/glossary.html#co
 ```
 
 You can use ref for manual manipulation of ImageViewer.Multi, or consider using `ImageViewer.show()`.
+
+### Why doesn't my custom image preview support gestures?
+
+Since the default image preview mechanism is used in ImageViewer, if custom rendering is required, the ref can be manually passed in according to actual needs, and the ref can be bound to the tag element of the custom rendering by itself.
+
+```jsx
+  <ImageViewer.Multi
+        images={demoViewImages}
+        visible={visible}
+        imageRender={(image, info) => {
+          if (info.index === 0)
+            return (
+              <div className={styles['image-render']} ref={info.ref}>
+                <video muted width='100%' controls src={image} />
+              </div>
+            )
+        }}
+        defaultIndex={0}
+        onClose={() => {
+          setVisible(false)
+        }}
+      />
+```

src/components/image-viewer/index.zh.md

@@ -21,7 +21,7 @@
 | maxZoom | 最大缩放比例 | `number \| 'auto'` | `3` |  |
 | onClose | 关闭时触发 | `() => void` | - |  |
 | renderFooter | 渲染底部额外内容 | `(image: string) => ReactNode` | - |  |
-| imageRender | 自定义渲染内容 | `(image: string, { index }: { index: number }) => ReactNode` | - | 5.39.0 |
+| imageRender | 自定义渲染内容 | `(image: string,{ ref, index }: { ref: RefObject<HTMLImageElement>; index: number }) => ReactNode` | - | 5.39.0 |
 | visible | 是否显示 | `boolean` | `false` |  |
 
 ## ImageViewer.Multi
@@ -33,7 +33,7 @@
 | images | 图片资源的 url 列表 | `string[]` | - |  |
 | onIndexChange | 切换图片时触发 | `(index: number) => void` | - |  |
 | renderFooter | 渲染底部额外内容 | `(image: string, index: number) => ReactNode` | - |  |
-| imageRender | 自定义渲染内容 | `(image: string, { index }: { index: number }) => ReactNode` | - |  |
+| imageRender | 自定义渲染内容 | `(image: string,{ ref, index }: { ref: RefObject<HTMLImageElement>; index: number }) => ReactNode` | - |  |
 
 其他属性同 `ImageViewer`，但是去掉了 `image` 属性。
 
@@ -84,3 +84,26 @@ ImageViewer.Multi 是一个[非受控](https://reactjs.org/docs/glossary.html#co
 ```
 
 你可以使用 ref 来对 ImageViewer.Multi 进行手动的操作，也可以考虑使用 `ImageViewer.show()`。
+
+### 为什么我自定义的图片预览不支持手势？
+
+由于在 ImageViewer 中使用了默认的图片预览机制，若需进行自定义渲染，可根据实际需求手动传入 ref，并在自定义渲染的标签元素上自行绑定该 ref。
+
+```jsx
+  <ImageViewer.Multi
+        images={demoViewImages}
+        visible={visible}
+        imageRender={(image, info) => {
+          if (info.index === 0)
+            return (
+              <div className={styles['image-render']} ref={info.ref}>
+                <video muted width='100%' controls src={image} />
+              </div>
+            )
+        }}
+        defaultIndex={0}
+        onClose={() => {
+          setVisible(false)
+        }}
+      />
+```

src/components/image-viewer/methods.tsx

@@ -1,11 +1,11 @@
 import React from 'react'
+import { renderImperatively } from '../../utils/render-imperatively'
 import {
-  ImageViewerProps,
   ImageViewer,
-  MultiImageViewerProps,
+  ImageViewerProps,
   MultiImageViewer,
+  MultiImageViewerProps,
 } from './image-viewer'
-import { renderImperatively } from '../../utils/render-imperatively'
 
 export type ImageViewerShowHandler = {
   close: () => void

src/components/image-viewer/slide.tsx

@@ -1,6 +1,6 @@
 import { animated, useSpring } from '@react-spring/web'
 import { useSize } from 'ahooks'
-import type { FC, MutableRefObject, ReactNode } from 'react'
+import type { FC, MutableRefObject, ReactNode, RefObject } from 'react'
 import React, { useRef } from 'react'
 import { bound } from '../../utils/bound'
 import type { Matrix } from '../../utils/matrix'
@@ -16,7 +16,10 @@ type Props = {
   onTap?: () => void
   onZoomChange?: (zoom: number) => void
   dragLockRef?: MutableRefObject<boolean>
-  imageRender?: (image: string, { index }: { index: number }) => ReactNode
+  imageRender?: (
+    image: string,
+    { ref, index }: { ref: RefObject<HTMLImageElement>; index: number }
+  ) => ReactNode
   index?: number
 }
 
@@ -299,7 +302,7 @@ export const Slide: FC<Props> = props => {
 
   const customRendering =
     typeof imageRender === 'function' &&
-    imageRender(props.image, { index } as { index: number })
+    imageRender(props.image, { ref: imgRef, index: index ?? 0 })
 
   return (
     <div className={`${classPrefix}-slide`}>

src/components/image-viewer/slides.tsx

@@ -2,6 +2,7 @@ import { animated, useSpring } from '@react-spring/web'
 import { useDrag } from '@use-gesture/react'
 import React, {
   ReactNode,
+  RefObject,
   forwardRef,
   useImperativeHandle,
   useRef,
@@ -18,7 +19,10 @@ export type SlidesType = {
   maxZoom: number
   defaultIndex: number
   onIndexChange?: (index: number) => void
-  imageRender?: (image: string, { index }: { index: number }) => ReactNode
+  imageRender?: (
+    image: string,
+    { ref, index }: { ref: RefObject<HTMLImageElement>; index: number }
+  ) => ReactNode
 }
 export type SlidesRef = {
   swipeTo: (index: number, immediate?: boolean) => void

src/components/image-viewer/tests/image-viewer.test.tsx

@@ -275,6 +275,32 @@ describe('ImageViewer.Multi', () => {
     render(<App />)
     expect(document.querySelector('.customize-preview-node-0')).toBeTruthy()
   })
+
+  test('rendering with imageRender and ref', () => {
+    let capturedRef: any = null
+    function App() {
+      return (
+        <ImageViewer.Multi
+          images={demoViewImages}
+          visible
+          imageRender={(image, info) => {
+            capturedRef = info.ref
+            return (
+              <div
+                className={`customize-preview-node-${info.index}`}
+                ref={info.ref}
+              />
+            )
+          }}
+        />
+      )
+    }
+    render(<App />)
+    expect(document.querySelector('.customize-preview-node-0')).toBeTruthy()
+    expect(capturedRef).toBeTruthy()
+    expect(typeof capturedRef).toBe('object')
+    expect(capturedRef.current).toBeDefined()
+  })
 })
 
 describe('ImageViewer', () => {
@@ -319,4 +345,27 @@ describe('ImageViewer', () => {
     })
     await waitFor(() => expect(img).not.toBeVisible())
   })
+
+  test('rendering with imageRender and ref', () => {
+    let capturedRef: any = null
+    function App() {
+      return (
+        <ImageViewer
+          image={demoImages[0]}
+          visible
+          imageRender={(image, { ref, index }) => {
+            capturedRef = ref
+            return (
+              <div className={`customize-preview-node-${index}`} ref={ref} />
+            )
+          }}
+        />
+      )
+    }
+    render(<App />)
+    expect(document.querySelector('.customize-preview-node-0')).toBeTruthy()
+    expect(capturedRef).toBeTruthy()
+    expect(typeof capturedRef).toBe('object')
+    expect(capturedRef.current).toBeDefined()
+  })
 })