Image 图片

17:06

说明

在 uni-app 原生 image 基础上做了增强：内置加载中 / 加载失败占位，可用 loading、error 插槽或 loading-icon / error-icon 替换；支持 fade 淡入、shape 形状与 border-radius 圆角、bg-color 占位底色、lazy-load 懒加载。width / height 传数值时按 px 处理，不传则宽 100%、高 auto。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持（webp、show-menu-by-longpress 仅微信小程序生效）

示例

基础用法

默认 square（小圆角 4px）展示，可通过 width / height 自定义宽高，形状设置见下方示例。

查看源码

<template>
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" />
        <ux-image custom-class="gap" src="https://placehold.co/200x200.png" width="200" height="200" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

圆角与形状

shape 控制形状：square(小圆角 4px，默认) / circle(正圆)；border-radius 一经传入即优先于 shape，传 0 即为真直角。

查看源码

<template>
    <!-- shape 两档全演示：square 小圆角（4px，不传即此档） / circle 正圆 -->
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" shape="square" />
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png" width="100" height="100" shape="circle" />
    </view>
    <!-- border-radius 一经传入即优先于 shape 预设，传 0 即真直角 -->
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" :border-radius="10" />
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png" width="100" height="100" :border-radius="0" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

加载失败状态

加载失败时显示错误占位图标，可通过 error-icon 自定义。

查看源码

<template>
    <ux-image src="https://invalid.example.com/not-found.png" width="100" height="100" />
</template>

裁剪模式

mode 控制图片裁剪/缩放模式，对比 aspectFit（完整显示） vs aspectFill（填充容器裁剪超出）。

查看源码

<template>
    <view class="row">
        <ux-image src="https://placehold.co/600x200.png" width="100" height="100" mode="aspectFit" />
        <ux-image custom-class="gap" src="https://placehold.co/600x200.png" width="100" height="100" mode="aspectFill" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

淡入动画

fade 控制加载完成淡入过渡，对比 无动画 vs 500ms 淡入。

查看源码

<template>
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" :fade="false" :lazy-load="false" />
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png" width="100" height="100" :fade="true" :duration="500" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

背景色占位

通过 bg-color 设置加载/失败占位的背景色，默认使用主题背景色；示意用失败图片让占位常驻，便于对比。

查看源码

<template>
    <view class="row">
        <ux-image src="https://invalid.example.com/bg-not-found.png" width="100" height="100" />
        <ux-image custom-class="gap" src="https://invalid.example.com/bg-not-found.png" width="100" height="100" :bg-color="'#f5222d'" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

自定义插槽

error 插槽可完全自定义失败占位内容，也可用 loading-icon/error-icon 选用内置图标；左侧自定义、右侧加载中图标。

查看源码

<template>
    <view class="row">
        <ux-image src="https://invalid.example.com/slot-not-found.png" width="100" height="100" :show-error="true">
            <template #error>
                <view class="holder">
                    <ux-icon name="info-circle" color="#f5222d" size="20" />
                    <text class="tip">自定义失败</text>
                </view>
            </template>
        </ux-image>
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png?delay=3000" width="100" height="100" loading-icon="star" :show-loading="true" :show-error="false" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
.holder {
    display: flex;
    flex-direction: column;
    align-items: center;
}
.tip {
    font-size: 10px;
    color: #f5222d;
    margin-top: 4px;
}
</style>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
src	图片地址	string	''	-
mode	裁剪模式	ImgMode	'aspectFit'	-
width	宽度	string | number	'100%'	-
height	高度	string | number	'auto'	-
shape	图片形状（词表见 types/global.uts 的 ImageShape）：square-小圆角 4px（默认），circle-正圆	ImageShape	'square'	-
borderRadius	圆角值；'' 作哨兵表示未设置（传 0 即显式真直角，优先于 shape 档）	string | number	''	-
lazyLoad	是否懒加载	boolean	true	-
showMenuByLongpress	是否开启长按图片显示识别小程序码菜单	boolean	true	-
loadingIcon	加载中的图标	string	'photo'	-
errorIcon	加载失败的图标	string	'error-circle'	-
showLoading	是否显示加载中的图标	boolean	true	-
showError	是否显示加载错误的图标	boolean	true	-
fade	是否需要淡入效果	boolean	true	-
webp	只支持网络资源，仅微信小程序生效	boolean	false	-
duration	过渡时间	string | number	500	-
bgColor	背景颜色	string	''	-

Events

事件名	说明	回调参数	版本
click	点击图片时触发	-	-
error	图片加载失败时触发	err: UniImageErrorEvent	-
load	图片加载成功时触发	-	-

Slots

插槽名	说明	版本
loading	自定义加载中占位内容（默认显示 loading-icon）	-
error	自定义加载失败占位内容（默认显示 error-icon）	-

注意事项

• borderRadius 传 0 表示"显式真直角"，会覆盖 shape 的圆角档位；不传则按 shape 取圆角（square 小圆角 4px / circle 正圆）。
• showMenuByLongpress 默认 true，但仅在微信小程序生效，其余端该属性无效。
• webp 仅微信小程序支持，且只对网络图片生效。
• duration 只在 fade 为 true 时生效，单位为 ms。
• 加载失败时自动切换为错误占位；如需自定义，关闭 showError 或用 error 插槽接管。