Skip to main content

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​

组件接收的外部传入的属性

属性名
属性标识
类型
说明
地址srcstring

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

更改需要展示的图片

示例："https://qcloudimg.tencent-cloud.cn/raw/4a29d51b504f12b4933ce4490110b4dc.svg"

布局模式fitstring

更改图片的布局模式

示例："widthFix"

点击预览大图imgPreviewboolean

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

再次点击关闭预览maskClosableboolean

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

默认值：true

替代文字altstring

标签的 alt 属性

示例："[图片]"

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

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

仅小程序端有效

默认值：true

懒加载lazyLoadboolean

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

Events​

组件暴露的事件，可以监听组件的事件来触发一些外部的动作

事件名
事件code
事件出参 event.detail
适用情况
说明
加载成功load兼容三端

-

加载失败error兼容三端

-

点击tap兼容三端

-

Property API​

通过属性 API，可以获取组件内部的状态和属性值，可以通过$w.componentId.propertyName 来访问组件内部的值，如 $w.input1.value ，详请请参考 属性 API

只读属性名
属性标识
类型
说明
地址srcstring

更改需要展示的图片

布局模式fitstring

更改图片的布局模式

替代文字altstring

标签的 alt 属性

Method API​

无

Style API​

通过样式 API，可以覆盖组件中内部元素的样式来实现自定义，例如在低代码编辑器中中通过 #wd-page-root .wd-btn 即可为所有的按钮组件编写样式，通过 :scope 可以控制单个组件样式， 详细说明请参考样式 API

名称
类名
说明和示例
根元素.wd-image图片组件根元素
/* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-image {
  /* 在这里编写CSS 样式 */
}
PC 端根元素.wd-pc-image可以为 PC 端的图片编写样式
/* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-pc-image {
  /* 在这里编写CSS 样式 */
}
H5 端根元素.wd-h5-image可以为 H5 端的按钮编写样式
/* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-h5-image {
  /* 在这里编写CSS 样式 */
}
小程序端根元素.wd-mp-image可以为小程序端的图片编写样式
/* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-mp-image {
  /* 在这里编写CSS 样式 */
}
预览弹窗元素.wd-image-preview-container点击预览图片时打开的预览弹窗
/* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope .wd-image-preview-container {
  /* 在这里编写CSS 样式 */
}
预览背景.wd-image-mask点击预览图片时的蒙层
/* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope .wd-image-mask {
  /* 在这里编写CSS 样式 */
}
关闭按钮.wd-image-mask__icon-close点击预览图片时的右上角的关闭按钮
/* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope .wd-image-mask__icon-close {
  /* 在这里编写CSS 样式 */
}

了解样式 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.