TaroifyReact UI

    Image 图片

    介绍

    增强版的 taro Image 组件，提供多种图片填充模式，支持图片懒加载、加载中提示、加载失败提示。

    引入

    import { Image } from "@taroify/core"

    代码演示

    基础用法

    基础用法与 Taro Image 组件一致，支持 webp、fadeIn、showMenuByLongpress 等原生图片属性，也可以设置 H5 的 imgProps。
    通过 width 和 height 设置图片大小，若未指定，会从 style 中读取width,height属性。
    width、height 和 radius 为 number 时，会经过 pxTransform 转换。

    <Image width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />

    填充模式

    通过 mode 属性可以设置图片填充模式，可选值见下方表格。

    <Image width={200} height={200} mode="scaleToFill" src="https://img.yzcdn.cn/vant/cat.jpeg" />

    圆形图片

    通过 shape="circle" 设置圆形图片，可以配合 mode 属性展示不同的填充效果。

    <Image shape="circle" mode="scaleToFill" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
<Image shape="circle" mode="aspectFit" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
<Image shape="circle" mode="aspectFill" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />

    圆角图片 v1.0.2

    通过 shape="rounded" 设置默认圆角，通过 radius 属性自定义圆角大小。

    <Image shape="rounded" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
<Image radius={24} width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />

    图片懒加载

    设置 lazyLoad 属性来开启图片懒加载。

    <Image lazyLoad width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />

    加载中提示

    通过 placeholder 设置加载中提示。设置为 true 时使用默认图标，也可以传入文本或自定义节点。

    import { Photo } from "@taroify/icons"

<Image width={200} height={200} src="image.png" placeholder />
<Image width={200} height={200} src="image.png" placeholder="加载中..." />
<Image width={200} height={200} src="image.png" placeholder={<Photo />} />

    加载失败提示

    通过 fallback 设置加载失败提示。设置为 true 时使用默认图标，也可以传入文本或自定义节点。

    import { PhotoFail } from "@taroify/icons"

<Image width={200} height={200} src="error" fallback />
<Image width={200} height={200} src="error" fallback="加载失败" />
<Image width={200} height={200} src="error" fallback={<PhotoFail />} />

    API

    Props

    参数说明类型默认值
    src图片链接string-
    mode图片填充模式ImageModescaleToFill
    alt替代文本string-
    width宽度string | number-
    height高度string | number-
    shape图片形状 square rounded circleImageShape-
    radius v1.0.2圆角大小string | number-
    lazyLoad是否开启图片懒加载booleanfalse
    placeholder加载中提示boolean | ReactNodefalse
    fallback加载失败提示boolean | ReactNodefalse

    Modes

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

    Events

    事件名说明回调参数
    onClick点击图片时触发event: ITouchEvent
    onLoad图片加载完毕时触发event: ImageLoadEvent
    onError图片加载失败时触发event: ImageErrorEvent

    主题定制

    样式变量

    组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

    名称默认值描述
    --image-placeholder-colorvar(var(--gray-6)-
    --image-placeholder-font-sizevar(--font-size-md)-
    --image-placeholder-icon-size32px * $hd-
    --image-placeholder-icon-colorvar(--gray-4)-
    --image-placeholder-background-colorvar(--background-color)-