Image
WdImage
Applicable Scenarios
Used for displaying images on the page.
Basic Capabilities Description
- Basic image properties provide image selection/address input, layout mode, and click-to-preview full-size image configuration. The layout mode defaults to height self-adaptation to better adapt to image display across multiple devices.
- Advanced properties of images support configuring the alternative text (the alt attribute of the img tag) and provide a lazy loading switch (lazy loading is often suitable for pages with many images, reducing the loading of invalid resources).
Extended Scenarios Description
How to choose the layout mode for images with fixed height and width
Example
An image with a width of 300 and height of 150 is designed; how to choose the layout mode
Configuration Method
In Style-Layout, configure the width and height according to the values provided by the design. In Properties-Basic Properties-Layout Mode, you can select either Stretch to Fill or Crop to Fill:
Note: In Mini Programs, setting the image height directly to a percentage 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 the image height to a percentage in a Mini Program, you must define a fixed height for its parent container—meaning the parent container containing the image must have a definite height—for the percentage-based image height setting to be meaningful.
Component Usage Limits
Note that due to styling limitations on the Mini Program side, the height of the image component must not be set to auto; otherwise, it will fail to render.
Example
Interactive Preview
Layout Mode
From left to right: Crop to Fill, Scale Proportionally, Stretch to Fill, Height Auto, Width Auto
Click to Preview Full-size Image
This feature is disabled by default. After enabling this feature, clicking on the image will display the image preview.
Again Click to Close Preview
This feature is disabled by default. You must enable the Click to Preview Full-size Image feature before enabling this feature. After clicking the image to display the image preview, click the pop-up layer again to close the preview.
Alternative Text
The 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 |
|---|
| Replace text | alt | string | The alt attribute of the Example: "[图片]" |
| Long press to display the menu in the mini program | showMenuByLongpress | boolean | Long press the image to display the menu for sending to friends, favorite, save image, search, and recognition code. Support recognition: mini program code, WeChat/WeCom personal code, WeChat group code, and Public Account QR Code. Note: The feature requires directly long-pressing the image component. If "click to preview large image" is enabled and the pop-up large image appears, long-pressing the large image is invalid. Valid only in Mini Program Default value: true |
| lazy loading | lazyLoad | boolean | Load images on demand. If the image is not shown, it will not be loaded. |
| Address. | src | string | The image address supports cloud storage cloudID or HTTPS protocol address. WeChat Mini Program does not support HTTP protocol. Change the image to display Example: "https://qcloudimg.tencent-cloud.cn/raw/4a29d51b504f12b4933ce4490110b4dc.svg" |
| layout mode | fit | string | Change image layout mode Example: "widthFix" |
| Click to preview the large image | imgPreview | boolean | When turned on, click the image to show it in full size. |
| Click again to close preview | maskClosable | boolean | When turned on, click again to close the image preview. 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 |
|---|
| load successfully | load | Compatible with all platforms | - | |
| Loading failed | error | Compatible with all platforms | - | |
| click | tap | Compatible with all platforms | - |
Properties 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 |
|---|
| Address. | src | string | Change the image to display |
| layout mode | fit | string | Change image layout mode |
| Replace text | alt | string | The alt attribute of the |
Method API
NoneStyle 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 |
|---|
| root element | .wd-image | image component root element |
| PC-side root element | .wd-pc-image | Write styles for images on PC |
| H5 root element | .wd-h5-image | Write styles for buttons on the H5 side |
| Mini program root element | .wd-mp-image | Can write styles for images in the mini program |
| Preview popup element | .wd-image-preview-container | Click the preview image to open the pop-up preview |
| Preview background | .wd-image-mask | Click to preview image overlay |
| close button | .wd-image-mask__icon-close | Click to preview the image's close button in the top-right corner |
| 图片加载错误样式 | .wd-image.wd-image__error::before | 图片加载错误时，可以通过以下样式修改默认图片占位 |
CSS Variables
.wd-image-mask,
.wd-image {
/* Desktop Dialog Style */
--wd-image-mask-pc: var(--wd-bg-mask);
/* H5 and Mini Program Dialog Style */
--wd-image-mask-h5: var(--wd-black);
/* Dialog Close Button */
--wd-image-close-icon: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMiIgaGVpZ2h0PSIxMiIgdmlld0JveD0iMCAwIDEyIDEyIiBmaWxsPSJub25lIj4KPHBhdGggZD0iTTUuOTk5NTkgNy4zNzg4NEwxMC42MTM0IDExLjk5MjdMMTEuOTkyMyAxMC42MTM4TDcuMzc4NDQgNS45OTk5OEwxMS45OTIzIDEuMzg2MTNMMTAuNjEzNCAwLjAwNzI3MjYyTDUuOTk5NTkgNC42MjExMkwxLjM4NTY5IDAuMDA3MjMyNjdMMC4wMDY4MzU5NCAxLjM4NjA5TDQuNjIwNzMgNS45OTk5OEwwLjAwNjgzNTk0IDEwLjYxMzlMMS4zODU2OSAxMS45OTI3TDUuOTk5NTkgNy4zNzg4NFoiIGZpbGw9IiNFRUVFRUUiLz4KPC9zdmc+');
/* Fallback image when the image fails to load */
--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=. Simply enter the full https address. For example:
https://example.com/image.jpg
Why do externally linked images not display?
Many websites' images verify the page referrer, likely due to enabled hotlink protection. When accessed directly, there's no referrer source, but when used on your page, access may be blocked by referrer verification. You may try alternative image resources or check the loading failure messages in F12 developer tools.
Possible Causes:
- The image link is set to hotlink protection, only allowing access from specific domains.
- The page referrer is invalid and has been identified as malicious behavior by the image website.
- The image link has expired or does not exist.
- Images using HTTP protocol addresses are not supported on HTTPS pages, which only allow access to images via HTTPS protocol (cloud:// protocol for cloud storage will ultimately be converted to HTTPS)
Please check and fix the above issues before retrying.
Why do images display in the editor but not in the Mini Program?
In the editor, only Web pages can be used to simulate the rendering effects of the Mini Program. Due to the constraints of the Mini Program's rendering mechanism, setting the image height to auto is unsupported; similarly, when the image height is set to 100%, it may fail to display properly if the parent container lacks a defined height.
If encountering the above issues in the Mini Program, verify whether the height is set to auto or 100%. If so, it is recommended to set specific width and height for the image, or define a specific width, then adjust the rendering mode to height: auto.
Setting an http address, but not displaying in the WeChat Mini Program?
The Mini Program will no longer support displaying content via the http protocol; https protocol addresses are required. For details, refer to iOS WeChat 8.0.58 Failure to Load http Images.