fetch-controlled-image

v1.0.0

Published

a month ago

A React component that controls image loading via fetch with AbortController, avoiding browser concurrent request limits and supporting graceful fallback

0High
0Medium
0Low

baikalwangpro

react image fetch abortcontroller lazy-loading image-loading cors fallback

FetchControlledImage

一个使用 fetch + AbortController 控制图片加载的 React 组件。

特性

🚀 使用 fetch 接管图片加载 - 避免浏览器并发请求上限导致的排队问题
⚡ AbortController 支持 - 组件卸载或 src 变化时自动取消未完成的请求
🔄 智能降级 - 加载失败时自动回退到原始 src 或 fallback
🛡️ CORS 错误检测 - 自动检测并上报 CORS 相关错误
💾 内存管理 - 自动清理 Blob URL，防止内存泄漏
📦 轻量级 - 无额外依赖，支持 Tree Shaking

安装

npm install fetch-controlled-image
# 或
yarn add fetch-controlled-image
# 或
pnpm add fetch-controlled-image

快速开始

import { FetchControlledImage } from "fetch-controlled-image";

function App() {
  return (
    <FetchControlledImage
      src="https://example.com/image.jpg"
      fallback="/placeholder.png"
      alt="示例图片"
      onLoad={() => console.log("图片加载成功")}
    />
  );
}

API

Props

| 属性 | 类型 | 必填 | 默认值 | 说明 | | ---------- | ------------------------- | ---- | ------- | --------------------------------------- | | src | string | 是 | - | 图片地址 | | fallback | string | 否 | - | 加载失败后显示的备用图片地址 | | onLoad | () => void | 否 | - | 加载成功后的回调函数 | | as | ComponentType \| string | 否 | 'img' | 自定义 img 元素，支持 styled-components | | alt | string | 否 | '' | 图片描述 | | logger | object | 否 | - | 外部传入的日志记录器 |

组件同时接受所有标准的 ImgHTMLAttributes<HTMLImageElement> 属性。

logger 接口

组件支持传入自定义的 logger 对象，用于错误上报：

const logger = {
  error: (
    eventName: string,
    error: Error,
    context: Record<string, unknown>
  ) => {
    // 上报错误到监控系统
    console.error(eventName, error, context);
  },
};

<FetchControlledImage src="https://example.com/image.jpg" logger={logger} />;

使用示例

基础用法

<FetchControlledImage
  src="https://example.com/image.jpg"
  fallback="/placeholder.png"
  alt="产品图片"
/>

使用 styled-components

import styled from "styled-components";

const StyledImage = styled.img`
  width: 100%;
  height: auto;
  border-radius: 8px;
`;

<FetchControlledImage
  as={StyledImage}
  src="https://example.com/image.jpg"
  fallback="/placeholder.png"
/>;

带加载回调

function ImageWithLoading({ src }) {
  const [loading, setLoading] = useState(true);

  return (
    <div>
      {loading && <Spinner />}
      <FetchControlledImage
        src={src}
        fallback="/placeholder.png"
        onLoad={() => setLoading(false)}
        style={{ display: loading ? "none" : "block" }}
      />
    </div>
  );
}

错误监控

const logger = {
  error: (eventName, error, context) => {
    // 发送到 Sentry
    Sentry.captureException(error, {
      tags: { event: eventName },
      extra: context,
    });
  },
};

<FetchControlledImage src="https://example.com/image.jpg" logger={logger} />;

工作原理

传统 `<img>` 标签的问题

浏览器对每个域名有并发请求限制（通常 6 个），当页面有大量图片时：

后面的请求会排队等待
用户看到的是空白或加载中状态
无法精确控制请求的取消