::: sourceCode
## image
> issues: https://issues.dcloud.net.cn/?mid=component.media.image
:::
> 组件类型:[UniImageElement](/api/dom/uniimageelement.md)
图片
### 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61
### 属性
| 名称 | 类型 | 默认值 | 兼容性 | 描述 |
| :- | :- | :- | :-: | :- |
| src | string([string.ImageURIString](/uts/data-type.md#ide-string)) | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 图片资源地址 |
| mode | string | "scaleToFill" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 图片裁剪、缩放的模式 |
| lazy-load | boolean | false | Web: x; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: x; iOS: 4.11; HarmonyOS(VDOM): -; HarmonyOS(Vapor): x | 图片懒加载。只针对page与scroll-view下的image有效。 安卓默认懒加载不支持修改 |
| fade-show | boolean | false | Web: x; 微信小程序: x; 支付宝小程序: x; Android: 3.9; iOS: x; HarmonyOS: x | 图片显示动画效果 |
| webp | boolean | true | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS(VDOM): -; HarmonyOS(Vapor): x | 是否支持 WebP 格式,web、app平台默认支持 WebP 格式,不支持本属性,无法关闭对 WebP 格式的解析。 |
| show-menu-by-longpress | boolean | false | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 开启长按图片显示识别小程序码菜单 |
| draggable | boolean | false | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 鼠标长按是否能拖动图片(仅H5平台) |
| flatten | boolean | false | Web: x; 微信小程序: x; 支付宝小程序: x; Android(VDOM): x; Android(Vapor): 5.21; iOS(VDOM): x; iOS(Vapor): 5.11; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 是否拍平组件。拍平后存在事件、截图及 CSS 等限制,详见[拍平限制说明](https://doc.dcloud.net.cn/uni-app-x/component/common.html#flatten)。 |
| @error | (event: [UniImageErrorEvent](#uniimageerrorevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 图片加载错误时触发,event.detail = { errMsg } |
| @load | (event: [UniImageLoadEvent](#uniimageloadevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 图片加载完成时触发,event.detail = { width: '图片宽度px', height: '图片高度px' } |
#### mode 的属性描述
| 合法值 | 兼容性 | 描述 |
| :- | :-: | :- |
| scaleToFill | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不保持纵横比缩放图片,使图片的宽高完全拉伸至填满 image 元素 |
| aspectFit | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 保持纵横比缩放图片,使图片的长边能完全显示出来。也就是说,可以完整地将图片显示出来。 |
| aspectFill | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 保持纵横比缩放图片,只保证图片的短边能完全显示出来。也就是说,图片通常只在水平或垂直方向是完整的,另一个方向将会发生截取 |
| widthFix | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 宽度不变,高度自动变化,保持原图宽高比不变 |
| heightFix | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 高度不变,宽度自动变化,保持原图宽高比不变 |
| top | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的顶部区域 |
| bottom | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的底部区域 |
| center | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的中间区域 |
| left | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的左边区域 |
| right | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的右边区域 |
| top left | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的左上边区域 |
| top right | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的右上边区域 |
| bottom left | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的左下边区域 |
| bottom right | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 不缩放图片,只显示图片的右下边区域 |
### 事件
#### UniImageErrorEvent
```mermaid
graph LR
UniImageErrorEvent -- Extends --> UniEvent
style UniEvent color:#42b983
click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent"
```
##### UniImageErrorEvent 的属性值
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| detail | **UniImageErrorEventDetail** | 是 |
#### detail 的属性描述
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| errMsg | string | 是 | 错误信息 |
#### UniImageLoadEvent
```mermaid
graph LR
UniImageLoadEvent -- Extends --> UniEvent
style UniEvent color:#42b983
click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent"
```
##### UniImageLoadEvent 的属性值
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| detail | **UniImageLoadEventDetail** | 是 |
#### detail 的属性描述
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| width | number | 是 | 图片宽度 |
| height | number | 是 | 图片高度 |
### 图片格式
- web平台支持的图片格式,不同浏览器有差异,可查询caniuse。
- 小程序平台支持的图片格式与浏览器类似。但由于不同小程序平台的webview版本不一样,需要具体查阅小程序平台的图片组件介绍。\
注意:webp在不同小程序平台策略不同,有的需要打开 webp 属性,有的仅支持来自服务器的webp。
- App平台支持的图片格式如下:
| 图片格式| Android | iOS | HarmonyOS | 备注 |
| --- | --- | --- | --- | --- |
| BMP | √ | √ | √ | |
| GIF | √ | √ | √ | |
| ICO | √ | √ | √ | |
| JPG | √ | √ | √ | |
| PNG | √ | √ | √ | |
| WebP | √ | √ | √ |iOS 14+ 为硬解码,低版本为软解码(软解性能较低) |
| HEIC | √ (Android10+) | √ | √ | |
| AVIF | √ (HBuilder5.08+) | √ (iOS16+) | x |系统支持硬解才有优势,使用三方软解还不如换用其他格式 |
| TIF | x | √ | x | |
| SVG | √ (HBuilder4.81+) | √ (iOS13+ HBuilder4.81+) | ️√ | 不支持svg动画。某些场景会解成位图渲染,[详见](#svg-support) |
如需其他图片格式,可自行开发uts组件插件或搜索插件市场,如
- [apng插件](https://ext.dcloud.net.cn/search?q=apng&orderBy=Relevance&cat1=8&cat2=82)
### src路径支持说明
- 本地路径/static方式
由于uni-app/uni-app x编译时,只把/static目录下的静态资源copy到app中,所以src均需指向/static目录下。
其他目录的图片由于不会被打包进去,所以无法访问。
app平台文件路径会存在大小写敏感问题,为了有更好的兼容性,建议统一按大小写敏感原则处理 [详情](../api/file-system-spec.md#casesensitive)
- 本地绝对路径file:///方式
app-android平台形如`file:///storage/emulated/0/Android/data/io.dcloud.uniappx/apps/__UNI__4517034/www/static/test-image/logo.png`。
访问本应用内的资源时无需使用本方式,推荐使用/static方式。上述地址受包名、appid影响。
file:///方式一般用于download等公共目录。使用前需确保拥有相关权限。
- 支持网络路径
* 支持http、https。
* 安卓端image组件内部使用facebook的[fresco](https://github.com/facebook/fresco)库(2.5.0),自带缓存策略,也会自动清理缓存。
* iOS端image组件内部使用[SDWebImage](https://github.com/SDWebImage/SDWebImage)库(5.10.0),自带缓存策略,默认7天缓存,缓存过期后会自动清理。
* 鸿蒙平台 VDOM 模式 image 组件使用 arkUI 的 image 组件,缓存策略[另见](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-image?ha_source=Dcloud&ha_sourceId=89000448)
* 鸿蒙平台蒸汽模式image组件使用[imageknifepro](https://gitcode.com/openharmony-sig/imageknifepro)库(1.0.12),自带缓存策略,内存缓存256张128MB,磁盘缓存512张128MB,超限采用LRU淘汰。
### svg注意事项@svg-support
1. web平台以外的平台,均不支持svg动画。动画推荐改用基于lottie的[animation-view](./animation-view.md),全平台均支持。
2. svg图标换色注意事项:
非web平台,不管小程序还是App,均不支持内联svg标签,无法像web那样通过内联标签实现svg图标换色。
- 替代方案1:改用字体图标(推荐)。
- 替代方案2:准备多个svg,动态设置src。可以用独立文件,也可以使用 Data URL。但此方案无法通过css变量设置,暗黑适配时需要写脚本动态修改src。
- 替代方案3:小程序平台,可以利用 filter: drop-shadow 配合 overflow: hidden,可以将原图标的形状“投影”出新的颜色,并把原图标隐藏。App平台不支持此用法。
3. 鸿蒙平台部分情况会按位图渲染,失去矢量能力
svg 是矢量图片,可以无极缩放而不失真。但鸿蒙平台以下情况,会把svg转成位图渲染,此时将丢失矢量能力。
* 如果启用了 `flatten` 拍平,则会转为位图。
* 设置部分 `mode` 属性时会转为位图进行处理。`mode` 设置为 `scaleToFill/aspectFit/aspectFill/widthFix/heightFix` 可以保持矢量能力,设置为其它值会转位图处理。
* 如果 `src` 设置了 `data:image/svg+xml;base64,...` 这种形式的 data url,则会转为位图。
(例外:鸿蒙系统 API ≥ 26 的时候不会转为位图;svg 图片中包含 `text` 内容的时候会被内部转换成 `path` 并本地缓存,实际使用不再是 data url 从而不会转换成位图)
### 子组件 @children-tags
不可以嵌套组件
### 示例
示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/component/image/image.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/component/image/image.uvue)
::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/component/image/image
> appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/component/image/image
>示例
```vue
image样式大合集
右边为拍平
自定义组件:右边拍平
基础(右边为拍平)
```
:::
### 参见
- [参见uni-app相关文档](https://uniapp.dcloud.io/component/image.html)
### tips
- image组件默认宽度为320px、高度为240px
- 在error事件里监听报错,并重新设置image组件的src,可实现自定义错误图。[详见示例代码](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/component/image/image-path.uvue)
- 图片文件需在static目录(项目下或uni_modules下都支持static目录)下,或者import导入文件,否则文件不会被copy到最终的包中,导致无法访问
- app-android平台由于默认启用了图片缩放(即根据组件实际宽高加载图片,以节省内存),所以可能导致load事件返回的图片尺寸并非图片原始尺寸
- app-android平台不支持CMYK色彩的图片,[详见](https://github.com/facebook/fresco/issues/1404)
- app-ios平台 VDOM模式的image组件不支持padding style(padding-top、padding-left、padding-right、padding-bottom)
- 支付宝小程序中,给 `image` 设置 `padding` 时图片仍可能占满组件区域,不能依赖 `padding` 改变图片的实际显示区域。