# image

> 基础库 1.0.0 开始支持，低版本需做[兼容处理](1003706)。

> __微信 Windows 版__：支持
> 
> __微信 Mac 版__：支持
> 
> __微信 鸿蒙 OS 版__：支持

渲染框架支持情况：Skyline （使用最新 [Nightly](/miniprogram/dev/devtools/nightly.html) 工具调试）、WebView

## 功能描述

图片。支持 JPG、PNG、SVG、WEBP、GIF 等格式，[2.3.0](1003706) 起支持云文件ID。

1. 使用 svg 格式且 mode=scaleToFill 时，WebView 会居中（除非 svg 里加上 preserveAspectRatio="none"），Skyline 则会撑满 

2. svg 格式不支持百分比单位 

3. svg 格式不支持 <style> element

## 通用属性


```json
[
  {
    "属性": "src",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "图片资源地址",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "mode",
    "类型": "string",
    "默认值": "scaleToFill",
    "必填": "否",
    "说明": "图片裁剪、缩放的模式",
    "最低版本": "[1.0.0](1003706)",
    "子项": [
      {
        "合法值": "scaleToFill",
        "说明": "缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素",
        "最低版本": ""
      },
      {
        "合法值": "aspectFit",
        "说明": "缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。",
        "最低版本": ""
      },
      {
        "合法值": "aspectFill",
        "说明": "缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。",
        "最低版本": ""
      },
      {
        "合法值": "widthFix",
        "说明": "缩放模式，宽度不变，高度自动变化，保持原图宽高比不变",
        "最低版本": ""
      },
      {
        "合法值": "heightFix",
        "说明": "缩放模式，高度不变，宽度自动变化，保持原图宽高比不变",
        "最低版本": "[2.10.3](1003706)"
      },
      {
        "合法值": "top",
        "说明": "裁剪模式，不缩放图片，只显示图片的顶部区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "bottom",
        "说明": "裁剪模式，不缩放图片，只显示图片的底部区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "center",
        "说明": "裁剪模式，不缩放图片，只显示图片的中间区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "left",
        "说明": "裁剪模式，不缩放图片，只显示图片的左边区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "right",
        "说明": "裁剪模式，不缩放图片，只显示图片的右边区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "top left",
        "说明": "裁剪模式，不缩放图片，只显示图片的左上边区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "top right",
        "说明": "裁剪模式，不缩放图片，只显示图片的右上边区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "bottom left",
        "说明": "裁剪模式，不缩放图片，只显示图片的左下边区域。仅 Webview 支持。",
        "最低版本": ""
      },
      {
        "合法值": "bottom right",
        "说明": "裁剪模式，不缩放图片，只显示图片的右下边区域。仅 Webview 支持。",
        "最低版本": ""
      }
    ]
  },
  {
    "属性": "show-menu-by-longpress",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "长按图片显示发送给朋友、收藏、保存图片、搜一搜、打开名片/前往群聊/打开小程序（若图片中包含对应二维码或小程序码）的菜单。",
    "最低版本": "[2.7.0](1003706)"
  },
  {
    "属性": "bind:error",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "当错误发生时触发，event.detail = {errMsg}",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:load",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "当图片载入完毕时触发，event.detail = {height, width}",
    "最低版本": "[1.0.0](1003706)"
  }
]
```

## Skyline 特有属性


```json
[
  {
    "属性": "fade-in",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否渐显",
    "最低版本": ""
  },
  {
    "属性": "preload",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否预加载图片，即设置图片 src 时就触发图片下载和解码",
    "最低版本": "[3.15.0](1003706)"
  }
]
```

## WebView 特有属性


```json
[
  {
    "属性": "webp",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "默认不解析 webP 格式，只支持网络资源",
    "最低版本": "[2.9.0](1003706)"
  },
  {
    "属性": "lazy-load",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "图片懒加载，在即将进入一定范围（上下三屏）时才开始加载。Skyline 默认懒加载。",
    "最低版本": "[1.5.0](1003706)"
  },
  {
    "属性": "forceHttps",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "自动将 http 链接替换为 https 链接",
    "最低版本": "[3.9.1](1003706)"
  }
]
```

## 支持长按识别的码

| 类型 | 说明 | 最低版本 |
|------|------| -------|
| 小程序码 |    |
| 微信个人码 |    | [2.18.0](1003706) |
| 企业微信个人码 |    | [2.18.0](1003706) |
| 普通群码 | 指仅包含微信用户的群    | [2.18.0](1003706) |
| 互通群码 |  指既有微信用户也有企业微信用户的群  | [2.18.0](1003706) |
| 公众号二维码 |   | [2.18.0](1003706) |

## Bug & Tip

1. `tip`：image组件默认宽度320px、高度240px
1. `tip`：image组件进行缩放时，计算出来的宽高可能带有小数，在不同webview内核下渲染可能会被抹去小数部分

## 示例代码

[在开发者工具中预览效果](https://developers.weixin.qq.com/s/NwPpTRmS7AJf)

##### 原图

![image](@program/dev/image/cat/0.jpg)