Img

Enhanced image component that supports fill modes, lazy loading, loading/failed state slots, and click-to-preview.

Component Type

Basic Usage

Basic usage is consistent with the native image tag. You can set src, width, height, and other properties.

When using local resources, it is recommended to pass src through file import. In WeChat Mini Programs, the image tag supports binary data and base64 encoding. When using import paths alone, you need to combine with build configuration processing.

<wd-img :width="100" :height="100" :src="imgURL" />

import blackMao from './black_mao.png'

const imgURL = blackMao

Tip

You can configure transformAssetUrls to give wd-img's src property the same resource conversion experience as the native image.

import uni from '@dcloudio/vite-plugin-uni'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    uni({
      vueOptions: {
        template: {
          transformAssetUrls: {
            tags: {
              'wd-img': ['src']
            }
          }
        }
      }
    })
  ]
})

After modification, restart the development service to take effect. For more background, please refer to uni-app issue#4997.

Component State

Loading Indicator

When the image is loading, default placeholder content is displayed. You can also customize the loading state through the loading slot. If you don't want to display the default loading state, set show-loading to false.

<wd-img width="100%" height="27vw" src="https://www.123.wot.com/a.jpg" />

<wd-img width="100%" height="27vw" src="https://www.123.wot.com/a.jpg">
  <template #loading>
    <wd-loading />
  </template>
</wd-img>

Load Failure Indicator

When the image fails to load, default placeholder content is displayed. You can also customize the failed state through the error slot. If you don't want to display the default failed state, set show-error to false.

<wd-img width="100%" height="27vw" src="https://www.123.wot.com/a.jpg" />

<wd-img width="100%" height="27vw" src="https://www.123.wot.com/a.jpg">
  <template #error>
    <view class="error-wrap">Loading failed</view>
  </template>
</wd-img>

.error-wrap {
  width: 100%;
  height: 100%;
  background-color: red;
  color: white;
  line-height: 100px;
  text-align: center;
}

Component Style

Fill Mode

Set the image fill mode through mode. Optional values are top left, top right, bottom left, bottom right, right, left, center, bottom, top, heightFix, widthFix, scaleToFill, aspectFit, aspectFill.

<wd-img :width="100" :height="100" :src="imgURL" mode="center" />

Round

Display the image as a circle through round.

<wd-img :width="100" :height="100" :src="imgURL" round />

Border Radius

Set the image border radius through radius. The default unit is px.

<wd-img :width="100" :height="100" :src="imgURL" :radius="8" />

Special Usage

Preview Enabled

Enable click-to-preview through enable-preview. Internally implemented using uni.previewImage. The component only triggers preview after the image is successfully loaded.

<wd-img :width="100" :height="100" :src="imgURL" :enable-preview="true" />

Specify Preview Image

Specify the image to display during preview through preview-src, which can be different from the image currently displayed by the component.

<wd-img :width="100" :height="100" :src="imgURL" :preview-src="previewURL" :enable-preview="true" />

import blackMao from './black_mao.png'
import blackMaoPreview from './black_mao_1.png'

const imgURL = blackMao
const previewURL = blackMaoPreview

Attributes

Parameter	Description	Type	Default Value
src	Image link	string	-
preview-src	Preview image link	string	-
width	Width, supports numbers (unit px) or strings	string | number	-
height	Height, supports numbers (unit px) or strings	string | number	-
mode	Fill mode, optional values are top left, top right, bottom left, bottom right, right, left, center, bottom, top, heightFix, widthFix, scaleToFill, aspectFit, aspectFill	ImageMode	scaleToFill
round	Whether to display as a circle	boolean	false
radius	Border radius size, default unit is px	string | number	-
lazy-load	Whether to enable image lazy loading	boolean	false
enable-preview	Whether to support click-to-preview	boolean	false
show-menu-by-longpress	Whether to enable long-press image to show识别小程序码 menu, only valid for WeChat Mini Programs	boolean	false
show-loading	Whether to display default loading state	boolean	true
show-error	Whether to display default failed state	boolean	true
custom-class	Root node custom class name	string	''
custom-style	Root node custom style	string	''
custom-image	Internal image node custom class name	string	''

Events

Event Name	Description	Parameters
click	Triggered when clicking the image	event: MouseEvent
load	Triggered when image loading is complete, returns the image loading event object	event: Event
error	Triggered when image loading fails, returns the image error event object	event: Event

Slots

Name	Description
loading	Customize the display content when the image is loading
error	Customize the display content after the image fails to load

主题定制

CSS 变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 全局配置。

名称	默认值	描述
--wot-img-border-radius	$radius-radius-full	圆形模式圆角
--wot-img-loading-color	$text-placeholder	加载态文字颜色
--wot-img-loading-bg	$filled-bottom	加载态背景色
--wot-img-loading-font-size	$typography-body-size-main	加载态文字字号
--wot-img-loading-icon-color	$text-placeholder	加载态图标颜色
--wot-img-loading-icon-size	$n-32	加载态图标尺寸
--wot-img-error-color	$text-placeholder	失败态文字颜色
--wot-img-error-bg	$filled-bottom	失败态背景色
--wot-img-error-font-size	$typography-body-size-main	失败态文字字号
--wot-img-error-icon-color	$text-placeholder	失败态图标颜色
--wot-img-error-icon-size	$n-32	失败态图标尺寸

Source Code

Documentation

• Component