::: 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 ``` ::: ### 参见 - [参见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` 改变图片的实际显示区域。