Skip to main content
Supported Regions:上海

Image

WdImage

Applicable Scenarios​

It is used to display images on the page.

Basic Capabilities Description​

  1. The basic properties of images provide image selection/address input, layout mode, and click-to-preview large image configuration. The layout mode defaults to height adaptive for better adaptation to multi-end image display effects.
  2. The advanced properties of images support configuring alternative text (alt attribute of img tags) and provide a lazy loading switch (lazy loading is suitable for image-heavy pages to reduce unnecessary resource loading).

Extended Scenarios Description​

How to Choose the Layout Mode for Fixed-height and Fixed-width Images​

Example

The design provides an image with a width of 300 and a height of 150, and how to choose the layout mode.

Configuration Method

In the Style-Layout section, configure the width and height according to the values provided by the design. For the Properties-Basic Properties-Layout Mode, either stretch to fill or crop to fill can be selected:

Note: In Mini Programs, setting the image height as a percentage directly in the style panel will not take effect. It is not recommended to configure image height as a percentage in Mini Programs. If you need to set image height as a percentage in Mini Programs, you must define a fixed height for its parent container. That is, the parent container containing the image must have a fixed height for the percentage-based image height setting to take effect.

Component Usage Limitations​

Note that due to styling limitations on the Mini Program side, the height of the image component must not be set to auto; otherwise, rendering will fail.

Example​

Interactive Preview​

Layout Mode​

From left to right: crop to fill, scale proportionally, stretch to fill, height adaptive, width adaptive

Click to preview the full-size image​

This feature is disabled by default. After enabling it, clicking on an image will display the image preview.

Click again to close the preview​

This feature is disabled by default. You must first enable the "Click to preview the full-size image" feature before you can activate this functionality. After clicking on the image to display the preview, clicking again on the overlay will close the preview.

Alternative Text​

alt attribute of the image tag

Style API Custom Styles​

/* Modify the background color of the image preview pop-up layer */
.wd-image-preview-container .wd-image__mask {
  background-color: #ddd;
}
/* Modify the close button in the top-right corner of the image preview pop-up layer */
.wd-image-preview-container .wd-image__mask-close {
  width: 14px;
  height: 14px;
  background-image: url(data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTQiIGhlaWdodD0iMTQiIHZpZXdCb3g9IjAgMCAxNCAxNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xNCA3QzE0IDMuMTM0MDEgMTAuODY2IDEuMTgyOTJlLTA2IDcgMEMzLjEzNDAxIC0yLjE0MTg2ZS0wNiAxLjE4MjkyZS0wNiAzLjEzNCAwIDdDLTIuMTQxODZlLTA2IDEwLjg2NiAzLjEzNCAxNCA3IDE0QzEwLjg2NiAxNCAxNCAxMC44NjYgMTQgN1pNNC42NzA5MSAzLjk0NzU0TDcuMDAwMDEgNi4yOTA3NUw5LjMyOTEyIDMuOTQ3NTRMMTAuMDM4NCA0LjY1MjUxTDcuNzA0OTkgN0wxMC4wMzgzIDkuMzQ3NDlMOS4zMjkxMSAxMC4wNTI1TDcuMDAwMDEgNy43MDkyNUw0LjY3MDkyIDEwLjA1MjVMMy45NjE2OCA5LjM0NzQ5TDYuMjk1MDMgN0wzLjk2MTY3IDQuNjUyNTFMNC42NzA5MSAzLjk0NzU0WiIgZmlsbD0iIzA2MCIvPgo8L3N2Zz4K);
}

Properties​

External properties received by the component

Property Name
Property Identifier
Type
Description
替代文字altstring

标签的 alt 属性

Example: "[图片]"

小程序端长按展示功能菜单showMenuByLongpressboolean

长按图片显示发送给朋友、收藏、保存图片、搜一搜、识别码菜单。支持识别：小程序码、微信/企微个人码、微信群码、公众号二维码。注：该功能需要直接长按图片组件，若开启了“点击预览大图”并且弹出大图，长按大图无效

仅小程序端有效

Default value: true

懒加载lazyLoadboolean

图片按需加载，若图片没有被展示，则不会加载

地址srcstring

图片地址支持云存储cloudID或https协议地址，小程序端不支持 http 协议。

更改需要展示的图片

Example: "https://qcloudimg.tencent-cloud.cn/raw/4a29d51b504f12b4933ce4490110b4dc.svg"

布局模式fitstring

更改图片的布局模式

Example: "widthFix"

点击预览大图imgPreviewboolean

开启后，点击图片后图片会展示为大图

再次点击关闭预览maskClosableboolean

开启后，再次点击蒙层会关闭图片预览

Default value: true

Events​

Events exposed by the component. You can listen to component events to trigger external actions

Event Name
Event Code
Event Output Parameters event.detail
Applicable Scenarios
Description
加载成功loadCompatible with all platforms

-

加载失败errorCompatible with all platforms

-

点击tapCompatible with all platforms

-

Property API​

Through the Property API, you can access the internal state and property values of components. You can access internal values using$w.componentId.propertyName, such as $w.input1.value. For details, please refer to Property API

Read-only Property Name
Property Identifier
Type
Description
地址srcstring

更改需要展示的图片

布局模式fitstring

更改图片的布局模式

替代文字altstring

标签的 alt 属性

Method API​

None

Style API​

Through the Style API, you can override the styles of internal elements in components to achieve customization. For example, in the low-code editor, you can write styles for all button components using #wd-page-root .wd-btn, and control individual component styles with :scope. For detailed instructions, please refer toStyle API

Name
Class Name
Description and Examples
根元素.wd-image图片组件根元素
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-image {
  /* Write CSS styles here */
}
PC 端根元素.wd-pc-image可以为 PC 端的图片编写样式
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-pc-image {
  /* Write CSS styles here */
}
H5 端根元素.wd-h5-image可以为 H5 端的按钮编写样式
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-h5-image {
  /* Write CSS styles here */
}
小程序端根元素.wd-mp-image可以为小程序端的图片编写样式
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-mp-image {
  /* Write CSS styles here */
}
预览弹窗元素.wd-image-preview-container点击预览图片时打开的预览弹窗
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope .wd-image-preview-container {
  /* Write CSS styles here */
}
预览背景.wd-image-mask点击预览图片时的蒙层
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope .wd-image-mask {
  /* Write CSS styles here */
}
关闭按钮.wd-image-mask__icon-close点击预览图片时的右上角的关闭按钮
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope .wd-image-mask__icon-close {
  /* Write CSS styles here */
}

Learn about Style API

CSS Variables​

.wd-image-mask,
.wd-image {
  /* PC Pop-up Style */
  --wd-image-mask-pc: var(--wd-bg-mask);
  /* Popup Style for H5 and Mini Programs */
  --wd-image-mask-h5: var(--wd-black);
  /* Pop-up Close Button */
  --wd-image-close-icon: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMiIgaGVpZ2h0PSIxMiIgdmlld0JveD0iMCAwIDEyIDEyIiBmaWxsPSJub25lIj4KPHBhdGggZD0iTTUuOTk5NTkgNy4zNzg4NEwxMC42MTM0IDExLjk5MjdMMTEuOTkyMyAxMC42MTM4TDcuMzc4NDQgNS45OTk5OEwxMS45OTIzIDEuMzg2MTNMMTAuNjEzNCAwLjAwNzI3MjYyTDUuOTk5NTkgNC42MjExMkwxLjM4NTY5IDAuMDA3MjMyNjdMMC4wMDY4MzU5NCAxLjM4NjA5TDQuNjIwNzMgNS45OTk5OEwwLjAwNjgzNTk0IDEwLjYxMzlMMS4zODU2OSAxMS45OTI3TDUuOTk5NTkgNy4zNzg4NFoiIGZpbGw9IiNFRUVFRUUiLz4KPC9zdmc+');
  /* Fallback image for image loading errors */
  --wd-image-error-image: url('data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTgwIiBoZWlnaHQ9IjE4MSIgdmlld0JveD0iMCAwIDE4MCAxODEiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHdpZHRoPSIxODAiIGhlaWdodD0iMTgwLjAwMiIgZmlsbD0iI0UzRTZFQiIvPgo8cGF0aCBkPSJNNjYgNjkuNjIwNUM2NiA2Ny42MjEgNjcuNjIxIDY2IDY5LjYyMDUgNjZIMTEwLjM4QzExMi4zNzkgNjYgMTE0IDY3LjYyMSAxMTQgNjkuNjIwNVYxMTAuMzhDMTE0IDExMi4zNzkgMTEyLjM3OSAxMTQgMTEwLjM4IDExNEg2OS42MjA1QzY3LjYyMSAxMTQgNjYgMTEyLjM3OSA2NiAxMTAuMzhWNjkuNjIwNVoiIGZpbGw9IndoaXRlIi8+CjxwYXRoIGQ9Ik02NiA2OS41NTU2QzY2IDY3LjU5MTkgNjcuNTkxOSA2NiA2OS41NTU2IDY2SDExMC40NDRDMTEyLjQwOCA2NiAxMTQgNjcuNTkxOSAxMTQgNjkuNTU1NlYxMTAuNDQ0QzExNCAxMTIuNDA4IDExMi40MDggMTE0IDExMC40NDQgMTE0SDY5LjU1NTZDNjcuNTkxOSAxMTQgNjYgMTEyLjQwOCA2NiAxMTAuNDQ0VjY5LjU1NTZaIiBmaWxsPSIjQkNDNEQwIi8+CjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJNMTAwLjY2NiA4MS45OTk5QzEwMC42NjYgODMuNDcyNyA5OS40NzE5IDg0LjY2NjYgOTcuOTk5MiA4NC42NjY2Qzk2LjUyNjQgODQuNjY2NiA5NS4zMzI1IDgzLjQ3MjcgOTUuMzMyNSA4MS45OTk5Qzk1LjMzMjUgODAuNTI3MiA5Ni41MjY0IDc5LjMzMzMgOTcuOTk5MiA3OS4zMzMzQzk5LjQ3MTkgNzkuMzMzMyAxMDAuNjY2IDgwLjUyNzIgMTAwLjY2NiA4MS45OTk5Wk04Ny4wMTk5IDg2LjIxMTlDODYuNDU5OCA4NS41NDEyIDg1LjM4OTcgODUuNTgwOCA4NC44ODk4IDg2LjMzMDdMODQuMjIxNyA4Ny4zMzI4TDg4LjkwODQgOTQuNDI5N0M4OS40MjU2IDk1LjIxMyA4OS4yNDQ4IDk2LjI2MzUgODguNDk1NCA5Ni44Mjg3TDg0LjU1MjYgOTkuODAyNEw4NS4yNjU5IDEwMC42NjdIOTYuNjUzNEw4Ny4wMTk5IDg2LjIxMTlaTTgwLjY1NTUgMTAwLjY2N0w4MC42MjggMTAwLjYzM0M4MC4zMTkyIDEwMC4yNTkgODAuMTc2NyA5OS43NzUzIDgwLjIzMzUgOTkuMjkzNkM4MC4yOTAyIDk4LjgxMTkgODAuNTQxMyA5OC4zNzQzIDgwLjkyODUgOTguMDgyMkw4NS4wMjEyIDk0Ljk5NTZMODIuMDgxMiA5MC41NDM2TDc2LjcxNDUgOTguNTkzN0M3Ni4xMjM3IDk5LjQ3OTcgNzYuNzU4OSAxMDAuNjY3IDc3LjgyMzkgMTAwLjY2N0g4MC42NTU1Wk05OS4wNTY5IDEwMC42NjdMOTUuMTk1MyA5NC44NzI0TDk2Ljg4OTggOTIuMzMwN0M5Ny40MTc1IDkxLjUzOSA5OC41ODA4IDkxLjUzOSA5OS4xMDg2IDkyLjMzMDdMMTAzLjI4NCA5OC41OTM3QzEwMy44NzUgOTkuNDc5NyAxMDMuMjM5IDEwMC42NjcgMTAyLjE3NCAxMDAuNjY3SDk5LjA1NjlaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K');
}

Version Changes​

None

Frequently Asked Questions​

How to correctly set the external URL for an image in an expression?​

When setting an external URL for an image in a Mini Program, do not use src=, directly enter the complete https address. For example:

https://example.com/image.jpg

Why are externally linked images not displaying?​

Many websites' images check the page source, possibly because anti-leech protection is enabled. When accessed directly, there is no referrer, but when used in your page, it verifies the page source to block access. You can try using other image resources or check the loading failure information in the F12 developer tools.

Possible causes:

  1. The image link is set with anti-leech protection, allowing access only from specific domains.
  2. The page source is invalid and identified as malicious behavior by the image website.
  3. The image link is invalid or does not exist.
  4. Images using HTTP protocol addresses cannot be accessed on HTTPS pages, which only support HTTPS protocol images (cloud storage's cloud:// protocol will ultimately be converted to HTTPS).

Please check and fix the above issues before retrying.

Why can images be displayed in the editor but not in the Mini Program?​

In the editor, only Web pages can be used to simulate the rendering effects of Mini Programs. Due to the rendering mechanism limitations of Mini Programs, setting the image height to auto is not supported. Additionally, when the image height is set to 100%, it may also fail to display properly if the parent container lacks a specific height.

It is recommended that when encountering the above issues in Mini Programs, you can check whether the height is set to auto or 100%. If so, it is advised to set specific width and height for the image, or set a specific width, then change the image rendering mode to height auto-adaptation.