docs/en-US/component/image.md
Besides the native features of img, support lazy load, custom placeholder and load failure, etc.
:::demo Indicate how the image should be resized to fit its container by fit, same as native object-fit.
image/basic-usage
:::
:::demo Custom placeholder content when image hasn't loaded yet by slot = placeholder
image/placeholder
:::
:::demo Custom failed content when error occurs to image load by slot = error and slot = viewer-error.
image/load-failed
:::
:::tip
Native loading has been supported since ^(2.2.3), you can use loading = "lazy" to replace lazy = true.
If the current browser supports native lazy loading, the native lazy loading will be used first, otherwise will be implemented through scroll.
:::
:::demo Use lazy load by lazy = true. Image will load until scroll into view when set. You can indicate scroll container that adds scroll listener to by scroll-container. If undefined, will be the nearest parent container whose overflow property is auto or scroll.
image/lazy-load
:::
:::demo allow big image preview by setting previewSrcList prop. You can initialize the position of the first picture previewed by initial-index. The default initial position is 0.
image/image-preview
:::
:::demo
image/manually-preview
:::
:::demo Custom toolbar content by toolbar slot, starting from version ^(2.9.7), the slot has a new setActiveItem function, which can be switched according to the index.
image/custom-toolbar
:::
:::demo By setting the show-progress prop to control whether to display progress when previewing an image. After version ^(2.9.8), the progress content will be displayed as long as the progress slot is used.
image/custom-progress
:::
| Name | Description | Type | Default |
|---|---|---|---|
| src | image source, same as native. | ^[string] | '' |
| fit | indicate how the image should be resized to fit its container, same as object-fit. | ^[enum]'' | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | '' |
| hide-on-click-modal | when enabling preview, use this flag to control whether clicking on backdrop can exit preview mode. | ^[boolean] | false |
| loading ^(2.2.3) | Indicates how the browser should load the image, same as native. | ^[enum]'eager' | 'lazy' | — |
| lazy | whether to use lazy load. | ^[boolean] | false |
| scroll-container | the container to add scroll listener when using lazy load. By default, the container to add scroll listener when using lazy load. | ^[string] / ^[object]HTMLElement | — |
| alt | native attribute alt. | ^[string] | — |
| referrerpolicy | native attribute referrerPolicy. | ^[string] | — |
| crossorigin | native attribute crossorigin. | ^[enum]'' | 'anonymous' | 'use-credentials' | — |
| preview-src-list | allow big image preview. | ^[array]string[] | [] |
| z-index | set image preview z-index. | ^[number] | — |
| initial-index | initial preview image index, less than the length of url-list. | ^[number] | 0 |
| close-on-press-escape | whether the image-viewer can be closed by pressing ESC. | ^[boolean] | true |
| preview-teleported | whether to append image-viewer to body. A nested parent element attribute transform should have this attribute set to true. | ^[boolean] | false |
| infinite | whether the viewer preview is infinite. | ^[boolean] | true |
| zoom-rate | the zoom rate of the image viewer zoom event. | ^[number] | 1.2 |
| scale ^(2.11.3) | the preview image scale. | ^[number] | 1 |
| min-scale ^(2.4.0) | the min scale of the image viewer zoom event. | ^[number] | 0.2 |
| max-scale ^(2.4.0) | the max scale of the image viewer zoom event. | ^[number] | 7 |
| show-progress ^(2.9.4) | whether to display the preview image progress content. | ^[boolean] | false |
| Name | Description | Type |
|---|---|---|
| load | same as native load. | ^[Function](e: Event) => void |
| error | same as native error. | ^[Function](e: Event) => void |
| switch | trigger when switching images. | ^[Function](index: number) => void |
| close | trigger when clicking on close button or when hide-on-click-modal enabled clicking on backdrop. | ^[Function]() => void |
| show | trigger when the viewer displays | ^[Function]() => void |
| Name | Description | Type |
|---|---|---|
| placeholder | custom placeholder content when image hasn't loaded yet. | - |
| error | custom image load failed content. | - |
| image viewer slots | when you allow big image preview, image viewer slots all can be used. | - |
| Name | Description | Type |
|---|---|---|
| showPreview ^(2.9.4) | manually open preview big image | ^[Function]() => void |
| Name | Description | Type | Default |
|---|---|---|---|
| url-list | preview link list. | ^[array]string[] | [] |
| z-index | preview backdrop z-index. | ^[number] / ^[string] | — |
| initial-index | the initial preview image index, less than or equal to the length of url-list. | ^[number] | 0 |
| infinite | whether preview is infinite. | ^[boolean] | true |
| hide-on-click-modal | whether user can emit close event when clicking backdrop. | ^[boolean] | false |
| teleported | whether to append image itself to body. A nested parent element attribute transform should have this attribute set to true. | ^[boolean] | false |
| zoom-rate ^(2.2.27) | the zoom rate of the image viewer zoom event. | ^[number] | 1.2 |
| scale ^(2.11.3) | the preview image scale. | ^[number] | 1 |
| min-scale ^(2.4.0) | the min scale of the image viewer zoom event. | ^[number] | 0.2 |
| max-scale ^(2.4.0) | the max scale of the image viewer zoom event. | ^[number] | 7 |
| close-on-press-escape | whether the image-viewer can be closed by pressing ESC. | ^[boolean] | true |
| show-progress ^(2.9.4) | whether to display the preview image progress content | ^[boolean] | false |
| Name | Description | Type |
|---|---|---|
| close | trigger when clicking on close button or when hide-on-click-modal enabled clicking on backdrop. | ^[Function]() => void |
| error ^(2.11.3) | same as native error. | ^[Function](e: Event) => void |
| switch | trigger when switching images. | ^[Function](index: number) => void |
| rotate ^(2.3.13) | trigger when rotating images. | ^[Function](deg: number) => void |
| Name | Description | Type |
|---|---|---|
| viewer | custom content | - |
| progress ^(2.9.4) | custom progress content (Priority is higher than show-progress prop) | ^[object]{ activeIndex: number, total: number } |
| toolbar ^(2.9.4) | custom toolbar content | ^[object]{actions: (action: ImageViewerAction, options?: ImageViewerActionOptions ) => void, prev: ()=> void, next: () => void,reset: () => void, activeIndex: number }, setActiveItem: (index: number) => void |
| viewer-error ^(2.11.3) | custom image load failed content. | ^[object]{ activeIndex: number, src: string } |
| Name | Description | Type |
|---|---|---|
| setActiveItem | manually switch image | ^[Function](index: number) => void |
type ImageViewerAction = 'zoomIn' | 'zoomOut' | 'clockwise' | 'anticlockwise'
type ImageViewerActionOptions = {
enableTransition?: boolean
zoomRate?: number
rotateDeg?: number
}