rax-image
Version:
Image component for Rax.
139 lines (107 loc) • 14.2 kB
Markdown
# Image
[](https://www.npmjs.com/package/rax-image)
> 阿里内部同学推荐使用 `@ali/rax-picture`，对图片尺寸有很多内置的优化策略
## 支持
Web / Weex / 阿里小程序 / 微信小程序 / 字节跳动小程序
## 描述
用于展示图片
## 安装
```bash
$ npm install rax-image --save
```
## 引用
```jsx
import Image from 'rax-image';
```
## 属性
| **属性** | **类型** | **默认值** | **必填** | **描述** | **支持** |
| -------------- | ------------------------------------------------- | ----------- | -------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| source | `object: { width: string, height: string, uri: string}` | - | true | 设置图片的 uri。height和width为可选项，优先级低于style上的同名属性，一般高于其他CSS中的同名属性。 | <img alt="browser" src="https://gw.alicdn.com/tfs/TB1uYFobGSs3KVjSZPiXXcsiVXa-200-200.svg" width="25px" height="25px" /><img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /><img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /><img alt="wechatMiniprogram" src="https://img.alicdn.com/tfs/TB1slcYdxv1gK0jSZFFXXb0sXXa-200-200.svg" width="25px" height="25px"><img alt="bytedanceMicroApp" src="https://gw.alicdn.com/tfs/TB1jFtVzO_1gK0jSZFqXXcpaXXa-200-200.svg" width="25px" height="25px"><img alt="quickApp" src="https://gw.alicdn.com/tfs/TB1MP7EwQT2gK0jSZPcXXcKkpXa-200-200.svg" width="25px" height="25px"> |
| style | `object: { width: number height: number }` | - | true | 图片样式 width 和 height 为必填属性，否则图片无法正常展示，可以补充其他属性 | <img alt="browser" src="https://gw.alicdn.com/tfs/TB1uYFobGSs3KVjSZPiXXcsiVXa-200-200.svg" width="25px" height="25px" /><img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /><img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /><img alt="wechatMiniprogram" src="https://img.alicdn.com/tfs/TB1slcYdxv1gK0jSZFFXXb0sXXa-200-200.svg" width="25px" height="25px"><img alt="bytedanceMicroApp" src="https://gw.alicdn.com/tfs/TB1jFtVzO_1gK0jSZFqXXcpaXXa-200-200.svg" width="25px" height="25px"><img alt="quickApp" src="https://gw.alicdn.com/tfs/TB1MP7EwQT2gK0jSZPcXXcKkpXa-200-200.svg" width="25px" height="25px"> |
| fallbackSource | `object: { width: string, height: string, uri: string}` | - | false | 备用图片的 uri（当主图加载失败时加载）。height和width为可选项，优先级低于style上的同名属性，一般高于其他CSS中的同名属性。 | <img alt="browser" src="https://gw.alicdn.com/tfs/TB1uYFobGSs3KVjSZPiXXcsiVXa-200-200.svg" width="25px" height="25px" /><img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /> |
| loading | `string: 'eager' 'lazy'` | `eager` | false | 客户端如何加载图片，其中 Web 下需要浏览器原生支持`loading`属性。 | <img alt="browser" src="https://gw.alicdn.com/tfs/TB1uYFobGSs3KVjSZPiXXcsiVXa-200-200.svg" width="25px" height="25px" /><img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /><img alt="wechatMiniprogram" src="https://img.alicdn.com/tfs/TB1slcYdxv1gK0jSZFFXXb0sXXa-200-200.svg" width="25px" height="25px"><img alt="bytedanceMicroApp" src="https://gw.alicdn.com/tfs/TB1jFtVzO_1gK0jSZFqXXcpaXXa-200-200.svg" width="25px" height="25px"> |
| resizeMode | `string： 'contain' 'cover' 'stretch'` | - | false | 决定当组件尺寸和图片尺寸不成比例的时候如何调整图片的大小 | <img alt="browser" src="https://gw.alicdn.com/tfs/TB1uYFobGSs3KVjSZPiXXcsiVXa-200-200.svg" width="25px" height="25px" /><img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /><img alt="quickApp" src="https://gw.alicdn.com/tfs/TB1MP7EwQT2gK0jSZPcXXcKkpXa-200-200.svg" width="25px" height="25px"> |
| mode | String: | scaleToFill | false | 小程序中的[图片模式](https://docs.alipay.com/mini/component/image)，可选项更多 | <img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /><img alt="wechatMiniprogram" src="https://img.alicdn.com/tfs/TB1slcYdxv1gK0jSZFFXXb0sXXa-200-200.svg" width="25px" height="25px"><img alt="bytedanceMicroApp" src="https://gw.alicdn.com/tfs/TB1jFtVzO_1gK0jSZFqXXcpaXXa-200-200.svg" width="25px" height="25px"> |
| quality | `string: 'original' 'normal' 'low' 'high' 'auto'` | - | false | 图片质量 | <img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /> |
| placeholder | `string` | - | false | 占位图的 URL，在图片下载过程中将展示占位图， 图片下载完成后将显示 source 中指定的图片。 | <img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /><img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /> |
| onClick | `function` | - | false | 点击图片时的回调函数 | <img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /><img alt="wechatMiniprogram" src="https://img.alicdn.com/tfs/TB1slcYdxv1gK0jSZFFXXb0sXXa-200-200.svg" width="25px" height="25px"><img alt="quickApp" src="https://gw.alicdn.com/tfs/TB1MP7EwQT2gK0jSZPcXXcKkpXa-200-200.svg" width="25px" height="25px"> |
| onLoad | `function` | - | false | 图片加载成功的回调函数 | <img alt="browser" src="https://gw.alicdn.com/tfs/TB1uYFobGSs3KVjSZPiXXcsiVXa-200-200.svg" width="25px" height="25px" /><img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /><img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /><img alt="wechatMiniprogram" src="https://img.alicdn.com/tfs/TB1slcYdxv1gK0jSZFFXXb0sXXa-200-200.svg" width="25px" height="25px"><img alt="bytedanceMicroApp" src="https://gw.alicdn.com/tfs/TB1jFtVzO_1gK0jSZFqXXcpaXXa-200-200.svg" width="25px" height="25px"><img alt="quickApp" src="https://gw.alicdn.com/tfs/TB1MP7EwQT2gK0jSZPcXXcKkpXa-200-200.svg" width="25px" height="25px"> |
| onError | `function` | - | false | 图片加载失败的回调函数 | <img alt="browser" src="https://gw.alicdn.com/tfs/TB1uYFobGSs3KVjSZPiXXcsiVXa-200-200.svg" width="25px" height="25px" /><img alt="weex" src="https://gw.alicdn.com/tfs/TB1jM0ebMaH3KVjSZFjXXcFWpXa-200-200.svg" width="25px" height="25px" /><img alt="miniApp" src="https://gw.alicdn.com/tfs/TB1bBpmbRCw3KVjSZFuXXcAOpXa-200-200.svg" width="25px" height="25px" /><img alt="wechatMiniprogram" src="https://img.alicdn.com/tfs/TB1slcYdxv1gK0jSZFFXXb0sXXa-200-200.svg" width="25px" height="25px"><img alt="bytedanceMicroApp" src="https://gw.alicdn.com/tfs/TB1jFtVzO_1gK0jSZFqXXcpaXXa-200-200.svg" width="25px" height="25px"><img alt="quickApp" src="https://gw.alicdn.com/tfs/TB1MP7EwQT2gK0jSZPcXXcKkpXa-200-200.svg" width="25px" height="25px"> |
| src | `string` | - | false | 图片下载完成后将显示 src 中指定的图片。 | <img alt="bytedanceMicroApp" src="https://gw.alicdn.com/tfs/TB1jFtVzO_1gK0jSZFqXXcpaXXa-200-200.svg" width="25px" height="25px"> |
### onLoad onError 返回
当完成图片加载成功/失败时，将分别触发 onLoad/onError 中的回调函数 function(event) => {}
weex 下（iOS/Android）
| **成员** | **类型** | **描述** |
| ------------------ | --------- | --------------------------------------------------- |
| success | `boolean` | 标记图片是否成功加载，成功为 1/true，失败为 0/false |
| size | `object` | 加载的图片大小对象 |
| size.naturalWidth | `number` | 图片宽度，如果图片加载失败则为 0/-1 |
| size.naturalHeight | `number` | 图片高度，如果图片加载失败则为 0/-1 |
Web 下是 web 原生的 Event 事件
| **成员** | **类型** | **描述** |
| -------------------- | -------- | ------------ |
| target | `dom` | 图片自身元素 |
| target.naturalWidth | `number` | 图片宽度 |
| target.naturalHeight | `number` | 图片高度 |
小程序下
| 成员 | 类型 | 描述 |
| ------------- | -------- | ---------------- |
| type | `string` | 事件类型 |
| detail | `object` | 点击位置信息 |
| target | `object` | 点击对象属性信息 |
| currentTarget | `object` | 同上 |
快应用下
| **成员** | **类型** | **描述** |
| -------------------- | -------- | ------------ |
| target | `object` | 图片自身元素 |
| target.data.width | `number` | 图片宽度 |
| target.data.height | `number` | 图片高度 |
## 示例
### 普通示例
```jsx
import { createElement, render } from 'rax';
import DriverUniversal from 'driver-universal';
import Image from '../src/index';
const App = () => {
const imageRef = useRef(null);
return (
<Image
ref={imageRef}
source={{
uri: 'https://gw.alicdn.com/tfs/TB1bBD0zCzqK1RjSZFpXXakSXXa-68-67.png',
}}
style={{
height: '68rpx',
width: '67rpx',
}}
/>
);
};
render(<App />, document.body, { driver: DriverUniversal });
```
### 使用 fallbackSource 和 resizeMode
```jsx
import { createElement, render } from 'rax';
import DriverUniversal from 'driver-universal';
import Image from '../src/index';
const App = () => {
return (
<Image
source={{
uri:
'https://gw.alicdn.com/tfs/TB1g6AvPVXXXXa7XpXXXXXXXXXX-215-215.png',
}}
fallbackSource={{
uri:
'https://gw.alicdn.com/tps/i3/TB1yeWeIFXXXXX5XFXXuAZJYXXX-210-210.png_70x70.jpg',
}}
style={{
width: '100rpx',
height: '100rpx',
}}
resizeMode="cover"
/>
);
};
render(<App />, document.body, { driver: DriverUniversal });
```