---
name: "Image"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "Image - 图片"
---

## Image

> [VERSION] @ray-js/ray >= 0.5.10

### 描述

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

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `src` | `string` | 否 | - | 图片资源地址 |
| `mode` | `"scaleToFill" \| "aspectFit" \| "aspectFill" \| "widthFix" \| "heightFix" \| "top" \| "bottom" \| "center" \| "left" \| "right" \| "top left" \| "top right" \| "bottom left" \| "bottom right"` | 否 | `"scaleToFill"` | 图片裁剪、缩放的模式 |
| `lazyLoad` | `boolean` | 否 | `false` | 懒加载，进入一定范围后再加载 |
| `fadeDuration` | `number` | 否 | `0` | 加载过程中渐显时长，单位 ms |
| `onError` | `(event: ImageErrorEvent) => void` | 否 | - | 加载失败时触发 |
| `onLoad` | `(event: ImageLoadEvent) => void` | 否 | - | 载入完毕时触发 |

### 引用对象

##### `interface` ImageErrorEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"error"` | 事件类型 |
| `detail` | `ImageErrorDetail` | 事件数据 |

##### `interface` ImageLoadEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"load"` | 事件类型 |
| `detail` | `ImageLoadDetail` | 事件数据 |

##### `interface` ImageErrorDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errMsg` | `string` | 错误信息 |

##### `interface` BaseEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `string` | 事件类型 |
| `timeStamp` | `number` | 页面打开到触发事件所经过的毫秒数 |
| `target` | `Target` | 触发事件的源组件 |
| `currentTarget` | `Target` | 当前组件的一些属性值集合 |
| `mark` | `any` | 事件标记数据 |

##### `interface` ImageLoadDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `width` | `number` | 图片宽度，单位 px |
| `height` | `number` | 图片高度，单位 px |

##### `interface` Target

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 事件源组件的id |
| `dataset` | `Record<string, unknown>` | 事件源组件上的 `dataset` 自定义属性组成的集合 |


### 合法值

##### `mode` 合法值

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


### 示例代码

#### 基础用法

```tsx
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>
  );
}
```

#### 缩放模式

```tsx
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>
  );
}
```

#### 懒加载与渐显

```tsx
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，需要在目标机型上验证展示效果并准备兜底图片。