本页目录
注意事项

Image

版本要求:
@ray-js/ray≥0.5.10

描述

图片组件，支持多种裁剪和缩放模式。

属性

属性类型必填默认值说明
srcstring否-图片资源地址
mode"scaleToFill" | "aspectFit" | "aspectFill" | "widthFix" | "heightFix" | "top" | "bottom" | "center" | "left" | "right" | "top left" | "top right" | "bottom left" | "bottom right"否scaleToFill图片裁剪、缩放的模式
lazyLoadboolean否false懒加载，进入一定范围后再加载
fadeDurationnumber否0加载过程中渐显时长，单位 ms
否-加载失败时触发
否-载入完毕时触发

合法值

mode
值说明最低版本
scaleToFill缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素-
aspectFit缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来-
aspectFill缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来-
widthFix缩放模式，宽度不变，高度自动变化，保持原图宽高比不变-
heightFix缩放模式，高度不变，宽度自动变化，保持原图宽高比不变-
top裁剪模式，不缩放图片，只显示图片的顶部区域-
bottom裁剪模式，不缩放图片，只显示图片的底部区域-
center裁剪模式，不缩放图片，只显示图片的中间区域-
left裁剪模式，不缩放图片，只显示图片的左边区域-
right裁剪模式，不缩放图片，只显示图片的右边区域-
top left裁剪模式，不缩放图片，只显示图片的左上边区域-
top right裁剪模式，不缩放图片，只显示图片的右上边区域-
bottom left裁剪模式，不缩放图片，只显示图片的左下边区域-
bottom right裁剪模式，不缩放图片，只显示图片的右下边区域-

示例代码

基础用法

import React from 'react';
import { Image, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Image
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-8d53-258e63d3fe0e-1778036702734.jpeg"
        style={{ width: '200px', height: '200px' }}
        onLoad={(e) => console.log('图片加载完成:', e.detail)}
        onError={(e) => console.log('图片加载失败:', e.detail)}
      />
    </View>
  );
}

缩放模式

import React, { useState } from 'react';
import { Image, View, Text, Button } from '@ray-js/ray';

export default function () {
  const [mode, setMode] = useState<string>('scaleToFill');
  const imgSrc = 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-8d53-258e63d3fe0e-1778036702734.jpeg';

  return (
    <View style={{ padding: '20px' }}>
      <Text style={{ marginBottom: '10px' }}>当前模式: {mode}</Text>
      <Image
        src={imgSrc}
        mode={mode}
        style={{ width: '300px', height: '200px', border: '1px solid #eee' }}
      />
      <View style={{ marginTop: '20px', display: 'flex', flexDirection: 'row', gap: '8px', flexWrap: 'wrap' }}>
        <Button size="mini" onClick={() => setMode('scaleToFill')}>
          scaleToFill
        </Button>
        <Button size="mini" onClick={() => setMode('aspectFit')}>
          aspectFit
        </Button>
        <Button size="mini" onClick={() => setMode('aspectFill')}>
          aspectFill
        </Button>
        <Button size="mini" onClick={() => setMode('widthFix')}>
          widthFix
        </Button>
      </View>
    </View>
  );
}

懒加载与渐显

import React from 'react';
import { Image, View, Text } from '@ray-js/ray';

export default function () {
  const imgSrc = 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-8d53-258e63d3fe0e-1778036702734.jpeg';

  return (
    <View style={{ padding: '20px' }}>
      <Text style={{ marginBottom: '10px' }}>懒加载 + 渐显 500ms:</Text>
      <Image
        src={imgSrc}
        lazyLoad
        fadeDuration={500}
        style={{ width: '300px', height: '200px' }}
        onLoad={(e) => console.log('加载完成:', e.detail)}
        onError={(e) => console.log('加载失败:', e.detail)}
      />
    </View>
  );
}

注意事项

  • 部分低端机型对 WebP 的兼容性较差，可能出现图片无法显示或显示异常。建议优先使用兼容性更稳定的图片格式；如果必须使用 WebP，需要在目标机型上验证展示效果并准备兜底图片。