React 图像 🏝 🏖 🏜

React Image 是 React.js 的 <img> 标签替代品和钩子，支持在加载图像失败时回退到备用源。

React Image 允许使用一个或多个图像作为备用图像，以防浏览器无法加载先前的图像。使用该组件时，你可以指定任何 React 元素在图像加载前（例如加载动画）或指定图像无法加载时使用。使用钩子时，可以通过将组件包装在 <Suspense> 中并指定 fallback 属性来实现这一点。

React Image 内部使用 useImage 钩子，该钩子封装了所有图像加载逻辑。这个钩子默认与 React Suspense 配合使用，会暂停渲染，直到浏览器下载并解码图像。

入门

要在本地以 ES6、CommonJS 或 UMD 格式包含代码，请使用 npm 安装 react-image：

npm install react-image --save

要从 CDN 全局包含代码：

<script src="https://unpkg.com/react-image/umd/index.js"></script>

依赖

除了支持钩子的 react 和 react-dom 版本以及 @babel/runtime 之外，react-image 没有其他外部依赖。

文档

你可以使用下面记录的独立组件，或者使用 useImage 钩子。

useImage():

useImage 钩子允许在任何组件中整合 react-image 的逻辑。使用钩子时，可以将组件包装在 <Suspense> 中，以防止在图像准备就绪之前进行渲染。指定 fallback 属性可以在浏览器加载时向用户显示加载动画或任何其他组件。如果找不到任何图像，钩子将抛出错误。你可以用错误边界包装你的组件来捕获这种情况并做出相应处理或显示内容。

使用示例：

import React, {Suspense} from 'react'
import {useImage} from 'react-image'

function MyImageComponent() {
  const {src} = useImage({
    srcList: 'https://www.example.com/foo.jpg',
  })

  return <img src={src} />
}

export default function MyComponent() {
  return (
    <Suspense>
      <MyImageComponent />
    </Suspense>
  )
}

`useImage` API:

srcList: 字符串或字符串数组。useImage 将尝试逐个加载这些图像，并在第一个成功加载后返回
imgPromise: 一个接受 URL 并返回 Promise 的函数。如果图像成功加载则解析，如果图像无法加载则拒绝。你可以注入一个替代实现，以实现高级自定义行为，如记录错误或处理返回带有 404 头的图像的服务器
useSuspense: 布尔值。默认情况下，useImage 会告诉 React 暂停渲染，直到图像下载完成。可以通过将此设置为 false 来禁用 Suspense。

返回值:

src：解析后的图片地址
isLoading：当前加载状态。注意：使用 Suspense 时该值永远不会为 true
error：遇到的任何错误（如果有的话）

独立组件（传统方式）

如果可能的话，你应该使用 useImage 钩子。这提供了更大的灵活性，并支持 React Suspense。

在你的组件中引入 react-image：

import {Img} from 'react-image'

然后为图片设置一个源：

const myComponent = () => <Img src="https://www.example.com/foo.jpg" />

这将解析为：

<img src="https://www.example.com/foo.jpg">

如果图片无法加载，<img> 将不会被渲染，从而防止显示"损坏"的图片。

多个备用图片：

当 src 被指定为一个数组时，react-image 将尝试加载数组中指定的所有图片，从第一个开始，直到成功加载一个图片为止。

const myComponent = () => (
  <Img
    src={['https://www.example.com/foo.jpg', 'https://www.example.com/bar.jpg']}
  />
)

如果一个图片之前尝试加载失败，react-image 在页面重新加载之前不会再次尝试加载它。

在图片加载之前显示"加载中"或其他元素：

const myComponent = () => (
  <Img
    src={['https://www.example.com/foo.jpg', 'https://www.example.com/bar.jpg']}
    loader={/*任何有效的 React 元素*/}
  />
)

如果一个图片之前已成功加载（自上次页面加载以来），加载器将不会显示，而是立即渲染图片。

如果所有图片都无法加载，显示一个备用元素：

const myComponent = () => (
  <Img
    src={['https://www.example.com/foo.jpg', 'https://www.example.com/bar.jpg']}
    unloader={/*任何有效的 React 元素*/}
  />
)

注意：

以下选项仅适用于 <Img> 组件，不适用于 useImage 钩子。使用钩子时，你可以注入自定义图片解析器，根据需要实现自定义行为。

绘制前解码

默认情况下，当浏览器支持时，react-image 使用 Image.decode() 来解码图片，只有在完全准备好绘制时才渲染它。虽然这对于立即渲染的矢量图像（如 svg）影响不大，但在绘制之前解码图片可以防止浏览器在解码时卡顿或闪烁。如果不需要这种行为，可以通过将 decode 属性设置为 false 来禁用它：

const myComponent = () => (
  <Img src={'https://www.example.com/foo.jpg'} decode={false} />
)

加载带有 CORS 策略的图片

当从另一个域加载带有 CORS 策略的图片时，你可能需要使用 crossorigin 属性。例如：

const myComponent = () => (
  <Img src={'https://www.example.com/foo.jpg'} crossorigin="anonymous" />
)

动画和其他高级用法

可以使用包装元素 container 来实现超出本项目范围的高级操作。container 接受一个属性 children，它是 React Image 传入的内容（即最终的 <img> 或加载器）。

例如，要给图片显示添加动画效果（并为加载器添加消失动画），可以设置一个包装器：

<Img
  src={'https://www.example.com/foo.jpg'}
  container={(children) => {
    return <div className="foo">{children}</div>
  }}
/>

默认情况下，加载器和卸载器组件也会被 container 组件包装。可以通过传递 loaderContainer 或 unloaderContainer 来单独设置它们。要禁止包装加载器或卸载器，可以向 loaderContainer 或 unloaderContainer 传递一个空操作（如 unloaderContainer={img => img}）。

实用技巧

延迟渲染直到元素可见（懒加载）

根据定义，React Image 会尝试立即加载图片。在某些情况下，这可能是不希望的，比如当页面有很多图片时。与任何 React 元素一样，可以使用流行的库（如 react-visibility-sensor）将渲染延迟到图片实际出现在视口中。以下是一个简单的示例（伪代码/未经测试！）：

import {Img} from 'react-image'
import VisibilitySensor from 'react-visibility-sensor'

const myComponent = () =>
  <VisibilitySensor>
    <Img src='https://www.example.com/foo.jpg'>
  </VisibilitySensor>