.. _image:

:wx_comp:`image ☁️ <image>`
=============================

.. versionadded::  1.0.0 低版本需做 :ref:`compatibility` 。

.. versionadded:: 2.3.0 起支持云文件ID。

图片。支持JPG、PNG、SVG格式，

+-----------+-------------+-------------+-----+--------------------------------------------------------+----------+
|   属性    |    类型     |   默认值    | 必  |                          说明                          | 最低版本 |
+===========+=============+=============+=====+========================================================+==========+
| src       | string      |             | 否  | 图片资源地址                                           | 1.0.0    |
+-----------+-------------+-------------+-----+--------------------------------------------------------+----------+
| mode      | string      | scaleToFill | 否  | 图片裁剪、缩放的模式                                   | 1.0.0    |
+-----------+-------------+-------------+-----+--------------------------------------------------------+----------+
| lazy-load | boolean     | false       | 否  | 图片懒加载，在即将进入一定范围（上下三屏）时才开始加载 | 1.5.0    |
+-----------+-------------+-------------+-----+--------------------------------------------------------+----------+
| binderror | eventhandle |             | 否  | 当错误发生时触发，，event.detail = {errMsg}            | 1.0.0    |
+-----------+-------------+-------------+-----+--------------------------------------------------------+----------+
| bindload  | eventhandle |             | 否  | 当图片载入完毕时触发，event.detail = {height, width}   | 1.0.0    |
+-----------+-------------+-------------+-----+--------------------------------------------------------+----------+


mode 的合法值

+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| 值           | 说明                                                                                                                                 |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| scaleToFill  | 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素                                                                |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| aspectFit    | 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。                                       |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| aspectFill   | 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。 |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| widthFix     | 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变                                                                                 |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| top          | 裁剪模式，不缩放图片，只显示图片的顶部区域                                                                                           |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| bottom       | 裁剪模式，不缩放图片，只显示图片的底部区域                                                                                           |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| center       | 裁剪模式，不缩放图片，只显示图片的中间区域                                                                                           |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| left         | 裁剪模式，不缩放图片，只显示图片的左边区域                                                                                           |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| right        | 裁剪模式，不缩放图片，只显示图片的右边区域                                                                                           |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| top left     | 裁剪模式，不缩放图片，只显示图片的左上边区域                                                                                         |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| top right    | 裁剪模式，不缩放图片，只显示图片的右上边区域                                                                                         |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| bottom left  | 裁剪模式，不缩放图片，只显示图片的左下边区域                                                                                         |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+
| bottom right | 裁剪模式，不缩放图片，只显示图片的右下边区域                                                                                         |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------+

.. attention:: image组件默认宽度300px、高度225px

.. attention:: image组件中二维码/小程序码图片不支持长按识别。仅在wx.previewImage中支持长按识别

示例代码

在开发者工具中预览效果

.. code:: html

  <view class="page">
    <view class="page__hd">
      <text class="page__title">image</text>
      <text class="page__desc">图片</text>
    </view>
    <view class="page__bd">
      <view class="section section_gap" wx:for="{{array}}" wx:for-item="item">
        <view class="section__title">{{item.text}}</view>
        <view class="section__ctn">
          <image
            style="width: 200px; height: 200px; background-color: #eeeeee;"
            mode="{{item.mode}}"
            src="{{src}}"
          ></image>
        </view>
      </view>
    </view>
  </view>

.. code:: js

  Page({
    data: {
      array: [{
        mode: 'scaleToFill',
        text: 'scaleToFill：不保持纵横比缩放图片，使图片完全适应'
      }, {
        mode: 'aspectFit',
        text: 'aspectFit：保持纵横比缩放图片，使图片的长边能完全显示出来'
      }, {
        mode: 'aspectFill',
        text: 'aspectFill：保持纵横比缩放图片，只保证图片的短边能完全显示出来'
      }, {
        mode: 'top',
        text: 'top：不缩放图片，只显示图片的顶部区域'
      }, {
        mode: 'bottom',
        text: 'bottom：不缩放图片，只显示图片的底部区域'
      }, {
        mode: 'center',
        text: 'center：不缩放图片，只显示图片的中间区域'
      }, {
        mode: 'left',
        text: 'left：不缩放图片，只显示图片的左边区域'
      }, {
        mode: 'right',
        text: 'right：不缩放图片，只显示图片的右边边区域'
      }, {
        mode: 'top left',
        text: 'top left：不缩放图片，只显示图片的左上边区域'
      }, {
        mode: 'top right',
        text: 'top right：不缩放图片，只显示图片的右上边区域'
      }, {
        mode: 'bottom left',
        text: 'bottom left：不缩放图片，只显示图片的左下边区域'
      }, {
        mode: 'bottom right',
        text: 'bottom right：不缩放图片，只显示图片的右下边区域'
      }],
      src: '../resources/cat.jpg'
    },
    imageError(e) {
      console.log('image3发生error事件，携带值为', e.detail.errMsg)
    }
  })

原图

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/0.jpg?t=19041921

scaleToFill

不保持纵横比缩放图片，使图片完全适应

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/1.png?t=19041921

aspectFit

保持纵横比缩放图片，使图片的长边能完全显示出来

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/2.png?t=19041921

aspectFill

保持纵横比缩放图片，只保证图片的短边能完全显示出来

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/3.png?t=19041921

top

不缩放图片，只显示图片的顶部区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/4.png?t=19041921

bottom

不缩放图片，只显示图片的底部区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/5.png?t=19041921

center

不缩放图片，只显示图片的中间区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/6.png?t=19041921

left

不缩放图片，只显示图片的左边区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/7.png?t=19041921

right

不缩放图片，只显示图片的右边边区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/8.png?t=19041921

top left

不缩放图片，只显示图片的左上边区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/9.png?t=19041921

top right

不缩放图片，只显示图片的右上边区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/10.png?t=19041921

bottom left

不缩放图片，只显示图片的左下边区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/11.png?t=19041921

bottom right

不缩放图片，只显示图片的右下边区域

.. image:: https://developers.weixin.qq.com/miniprogram/dev/image/cat/12.png?t=19041921