# ImageViewer

- Page: https://jiguang132.com/resources/ant-design-mobile/docs/image-viewer
- Resource: Ant Design Mobile (https://jiguang132.com/resources/ant-design-mobile.md)
- All guides: https://jiguang132.com/resources/ant-design-mobile/docs.md

See the full picture by zooming in.

## Install

```bash
npm install antd-mobile@5.43.0
```

antd-mobile is for mobile web, not React Native or Mini Programs. React 19 projects must register `createRoot` with `unstableSetRender` at the entry, or imperative APIs such as Toast and Dialog cannot render. Switch dark mode with `<html data-prefers-color-scheme="dark">`.

Examples come from the official Ant Design Mobile repository (MIT) at the commit published as npm 5.43.0. Presentation helpers such as `DemoBlock` are JGuang rewrites, not antd-mobile APIs.

See the full picture by zooming in.

## When to Use

You need to click on the picture to view the details and use it with the thumbnail.

## Demos

## ImageViewer

| Name | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| afterClose | Triggered when it is completely closed | `() => void` | - |  |
| classNames | Semantic structure class | `{ mask?:string,body?:string }` | - | 5.33.1 |
| getContainer | To get the specified mounted HTML node, the default is `null` rendered to the current node | `HTMLElement \| () => HTMLElement \| null` | `null` |  |
| image | The `url` of the image resource | `string` | - |  |
| 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,{ ref, index }: { ref: RefObject<HTMLImageElement>; index: number }) => ReactNode` | - | 5.39.0 |
| visible | Whether to show or hide | `boolean` | `false` |  |
| mask | Attributes of Mask Layer | `{onClick?:(event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void}` | - |  |

## ImageViewer.Multi

On the basis of `ImageViewer`, the following props have been added:

| Name | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| classNames | Semantic structure class | `{ mask?:string,body?:string }` | - | 5.33.1 |
| defaultIndex | Which picture would be displayed by default | `number` | `0` |  |
| 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,{ ref, index }: { ref: RefObject<HTMLImageElement>; index: number }) => ReactNode` | - |  |

At the same time, the `image` prop is removed.

### Ref

| Name | Description | Type |
| --- | --- | --- |
| swipeTo | Switch to the specified index | `(index: number, immediate: boolean) => void` |

### Mask

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| onClick | Triggered when the mask is clicked | `(event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void` | - |

## Imperative

Compared with the component-based usage above, the command-style is more convenient and more commonly used. In most cases, this method is recommended:

```ts | pure
const handler = ImageViewer.show(props)
const handlerMulti = ImageViewer.Multi.show(props)
```

You can directly enter the image view by calling the `show` method on the `ImageViewer`. The type of the `props` parameter is the same as the above table, but the `visible` prop is not supported. When the viewer is closed, the component instance would be automatically destroyed.

The return value of the `show` method is a component controller, which contains the following props:

| Name  | Description                       | Type         |
| ----- | --------------------------------- | ------------ |
| close | Function to close the ImageViewer | `() => void` |

If you want to close all ImageViewers created by the `show` method. You can call `ImageViewer.clear()`.

## FAQ

### Why I updated the value of `defaultIndex`, but the image displayed by ImageViewer.Multi did not switch?

ImageViewer.Multi is an [uncontrolled](https://reactjs.org/docs/glossary.html#controlled-vs-uncontrolled-components) component, `defaultIndex` is only read once when the component is loaded, After this, if you change the value of `defaultIndex`, it will not have any effect on the component. Therefore, the following writing method does not have the effect of switching pictures:

```jsx
<Button
  onClick={() => {
    setIndex(i => i + 1)
  }}
>
  Next
</Button>
<ImageViewer.Multi
  images={images}
  defaultIndex={index}
  visible={visible}
  onClose={() => {
    setVisible(false);
  }}
/>
```

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)
        }}
      />
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt