veImageX 的 React 加载 SDK 支持图片加载和图片监控功能，可帮助您一站式进行图片处理和数据监控。以下将为您介绍接入 SDK 的加载、监控功能的功能说明、集成准备、集成操作和相关配置介绍。

React 图片加载 SDK 旨在优化 Web 站点的图片资源，其核心能力及说明如下所示：

• 图片格式自适应：通过配置自适应图像格式列表，探测浏览器对图像格式的支持性，自动选择最优格式进行渲染。

• 分辨率自适应：支持根据屏幕像素比和图片所在容器大小自动适配图片分辨率，分辨率按原图比例缩放。

• 图片懒加载：图片延迟加载，只有当图片出现在视口范围内时，再获取图片资源进行渲染。

• 图片占位：在图片加载完成前显示占位图，避免页面抖动，保持渲染流畅性。

• 错误兜底：支持自定义图片加载错误时的占位图及错误描述。

• 稳定性布局：内置 5 种布局，您可根据实际业务灵活配置。

功能优势

React 图片加载 SDK 基于 veImageX 图片服务，旨在优化 Web 站点的图片资源，其核心功能优势如下所示：

• 节省图片流量：您可通过使用格式自适应和分辨率自适应功能来达到提升站点性能并节省流量的目的；
• 提升视觉稳定性：内置 5 种图片布局方式，可涵盖绝大多数的图片渲染场景，能避免累积布局偏移 CLS；
• 提高页面加载速度：您可通过使用过渡图占位和图片懒加载功能达成更快的页面加载；
• 灵活处理图片资源：已支持图片缩放、压缩、格式转换等图片模板能力，您可在配置模板后对加载图片进行灵活处理。

集成准备

环境要求

本文档适用于 React 16 及以上版本。

兼容要求

格式自适应及懒加载能力存在浏览器版本要求，具体如下表所示：

模板配置

SDK 内图片格式自适应、分辨率自适应、图片压缩等能力均依赖云端图片处理能力，请您参考以下操作创建具备图片压缩和缩放功能的图片处理模板。

1. 登录 veImageX 控制台，单击图片处理配置，在下拉列表中选择相应的图片服务。

   

2. 点击新建模板， 在编辑页面配置缩放和图片压缩，您可按下图所示进行模板配置。

   • 配置图片缩放：在编辑操作中选择基础图像处理 > 缩放 。
     

   • 配置图片压缩：在输出设置中配置压缩质量参数为 URL输入。您可选择开启 PNG 瘦身，该功能可以显著减小 PNG 图片的体积，默认关闭状态。
     

     说明

     您可以根据实际需求增加其他图片处理能力模板配置，如图文水印、旋转等。

3. 点击保存，完成模板配置并记录模板名称。

快速开始

前提条件

• 已开通 veImageX 相关服务，未注册用户可注册账号免费试用；

• 已配置图片处理模板。

安装 SDK

请在您的前端项目根目录下执行以下命令：

npm install @volcengine/imagex-react -S

集成 SDK

安装成功后，请执行以下命令集成 SDK ：

import { Viewer } from '@volcengine/imagex-react';
//具体参数说明请见功能接入
<Viewer
  layout='fixed'
  placeholder='skeleton'
  width={680}
  height={376}
  src='xxx'
  loader={({ src, width, quality, format }) => `//www.example.com/${src}~tplv-serviceid-resize:${width}:q${quality}.${format}`}
/>

功能接入

参数说明

import { ImageLoader } from '@volcengine/imagex-react';
// 域名/src~模板:模板参数:q质量参数.图片格式
const myLoader: ImageLoader = ({ src, width, quality, format }) => `//www.example.com/${src}~tplv-serviceid-resize:${width}:q${quality}.${format}`

SDK 支持 <img> 元素的全部属性，如 alt、onError 等，指定参数后再传递到内部包裹的 <img> 元素。代码示例如下所示：

type ProtocolType = 'http:' | 'https:';

type ImageLoaderProps = {
  src: string; // 图片访问 path 部分，不包含域名，如：imagex-common/5b96c061******21ab111b
  width: number; // 图片的宽度
  quality: number; // 图片质量
  format: string; // 图片格式
  extra: {
    domain?: string; // 从图片访问 url 解析出的域名
    protocol?: 'http:' | 'https:'; // 从图片访问 url 解析出的协议
    template?: string; // 从图片访问 url 解析出的 imagex 模板
    suffix?: string; // 从图片访问 url 解析出的格式后缀
    search?: string; // 从图片访问 url 解析出的query部分
    origin: string; // 图片访问 url
  };
};

布局方式说明

SDK 内置了 5 种布局方式，能够覆盖绝大多数的场景。SDK 支持全局配置和各布局样式配置，具体代码示例和实现效果图如下所示：

全局配置

其中 5 种布局方式共用的全局配置，代码示例如下所示：

import { GlobalConfig } from '@volcengine/imagex-react';

GlobalConfig({
  formats: ['avif', 'webp'],
  placeholder: 'skeleton',
  loader: ({ src, width, quality, format }) => `//www.example.com/${src}~tplv-serviceid-resize:${width}:q${quality}.${format}`
});

各布局样式配置

<div style={{ padding: '10px 20px', border: '10px solid #eae2fd', backgroundColor: '#d7f5d5', width: '60vw' }}>
    <Viewer
      layout='intrinsic' // 布局方式
      width={680}  // 必填
      height={376} // 必填
      src='xxx'  // 图片路径，可访问的图片 URL
      alt='图片加载错误'  // 错误兜底图文字说明
    />
</div>
  	

<div style={{ padding: '10px 20px', border: '10px solid #eae2fd', backgroundColor: '#d7f5d5', width: '60vw' }}>
   <Viewer
     layout='responsive' // 布局方式
     src='xxx'  // 图片路径，可访问的图片 URL
     alt='img' // 错误兜底图文字说明
     width={380}  // 图片宽度，必填
     height={188}  // 图片高度，必填，
   />
</div>
  	

<div id='wrapper1' style={{ padding: '10px 20px', border: '10px solid #eae2fd', backgroundColor: '#d7f5d5', width: '60vw' }}>
    <Viewer
      layout='fixed'  // 布局方式
      width={680}  // 图片宽度
      height={376}  // 图片高度
      src='xxx'  // 图片路径，可访问的图片 URL
      alt='img' // 错误兜底图文字说明
    />
</div>
  	

<div style={{ position: 'relative', width: '60vw', height: '60vh', padding: '10px 20px', border: '10px solid #eae2fd', backgroundColor: '#d7f5d5' }}>
    <Viewer
      layout='fill'  // 布局方式
      objectFit='contain'  // 具体浏览器填充模式
      src='xxx'  // 图片路径，可访问的图片 URL
      alt='img'  // 错误兜底图文字说明
    />
</div>
  	

<div style={{ padding: '10px 20px', border: '10px solid #eae2fd', backgroundColor: '#d7f5d5', width: '60vw' }}>
    <Viewer
      layout='raw'  // 布局方式
      width={340}   // 图片宽度
      height={168}  // 图片高度  
      src='xxx'  // 图片路径，可访问的图片 URL
      style={{ width: '100%', height: 'auto' }} // 自定义图片样式
      alt='图片加载错误'  // 错误兜底图文字说明
    />
</div>
  	

全局配置

全局配置代码示例如下所示：

import { GlobalConfig } from '@volcengine/imagex-react'
GlobalConfig({
  formats: ['avif', 'webp'], // 指定 avif，webp 自适应
  placeholder: 'skeleton',  //骨架屏占位
});

图片监控 SDK 旨在监控各种场景下图片元素的加载情况，通过上报图片加载数据，助力分析图片加载耗时、成功率、分辨率等数据。

集成准备

兼容要求

SDK 监控功能基于浏览器的PerformanceObserver API和MutationObserver API，则适用浏览器及版本如下所示：

• Chrome 52 及以上版本

• Edge 79 及以上版本

• Safari 11 及以上版本

• Firefox 57 及以上版本

获取 AppID

AppID 是隔离 SDK 的最小单位，一般用于 License 下发和数据隔离处理，也作为数据查询的最小单位。

1. 点击应用管理 ，进入应用管理页面。

2. 单击创建应用，在应用创建页面根据指引以及实际业务情况创建您的应用。

3. 创建完成后，单击详情查看并记录您的 APPID 等信息。

   

响应头配置

1. 登录 veImageX 控制台，选择服务管理 > 基础配置。

2. 选择域名状态为正常的域名单击配置，选择并进入高级配置页面。

   

3. 单击 HTTP Header 配置的编辑按钮，在弹出的配置框中单击添加。 在参数下拉框中选择[Access-Control-Allow-Origin]: * 、 [Timing-Allow-Origin]: * ，并进行配置后，单击确定保存。

   

快速开始

前提条件

• 已开通 veImageX 相关服务，未注册用户可注册账号免费试用；

• 已完成获取 AppID；

• 已完成图片域名响应头配置。

安装 SDK

支持 Script 和 NPM 两种引入方式，您可根据实际需要任选其一。

<head>
  <script src="https://unpkg.byted-static.com/volcengine/imagex-monitor/X.X.X/umd/index.js" />
  <script>
    const monitor = new window.ImageMonitor.Monitor({
      el: document,
      appId: xxxxx, // 请替换为您在集成准备获取的 appId
      region: 'cn' //中国
    });
    monitor.start()
  </script>
</head>
	

npm install @volcengine/imagex-monitor -S
	

import { Monitor } from '@volcengine/imagex-monitor';

const monitor = new Monitor({
  // config
  el: document,
  appId: xxxxx, // 请替换为您在集成准备获取的 appId
  region: 'cn'  //中国
})
monitor.start()
	

数据上报验证

接入 Web 监控 SDK 后，您可登录 veImageX 控制台 > 服务质量监控查看上报的图片质量数据，具体支持指标如下所示：

• 下行网络监控：网络耗时、DNS 耗时、TCP 建联耗时、SSL 握手时间、发送时间、等待时间、接收时间、网络成功率、错误码分布、网络链接复用率、http/https 占比
• 客户状态监控：加载耗时、SDK 版本变化、文件大小分布、图片样本量

功能接入

参数说明

代码示例如下所示：

const config = {
  el: document.body, // 表示监听的元素。如果需要单点监控，则传入一个单独的img/picture标签。除支持传入HTML元素外，也支持传入string，会使用document.querySelector(el)查找对应元素
  selector: 'img.specfic-classname',  // 非必填，过滤selector，传值后则只会上报满足该selector的图片元素
  appId: xxxxxx,   // 请替换为您在集成准备获取的 appId
  region: "cn",  // 区域，cn：中国；sg：新加坡
  enableCloudConfig: true,   // 是否启用云端配置下发，仅支持读取正常日志上报采样率、错误日志上报采样率。需要与veImageX服务端能力联动，在控制台-SDK配置下发进行配置，具体请参考下文云端下发配置
  userUniqueId: "somebody",  // 用户ID，自定义，用于将数据对应到特定用户
  exclude: [/exclude-pattern/],  //满足后，不发起上报的校验规则
  include: [/include-pattern/],  //满足后，发起上报的校验规则
  defaultConfig: {
    reportRateConfig: {
      reportRate: 1,  // 正常日志上报采样率
      reportRateError: 1  // 错误日志上报采样率
    }
  }
}

云端下发配置

SDK 支持读取控制台配置日志上报采样率以及错误日志上报采样率。具体配置步骤如下所示：

1. 登录 veImageX 控制台，并单击 SDK 配置下发后进入该页面。并在应用下拉框选中您创建的应用；如未创建，请单击新建应用按钮创建应用。

   

2. 在 SDK 配置下发页面选中您的应用后，在基础配置中打开 allow_log_type 配置节点配置客户端错误日志上报采样率和客户端日志上报采样率。

   

   配置名称	节点类型	说明
   imagex_load_monitor	客户端日志上报采样率	默认为 50%，请根据您的实际情况进行修改，如果 SDK 覆盖率比较高，可以调低此值。
   imagex_load_monitor_error	客户端错误日志上报采样率	默认为 100%，一般不需要修改。

3. 点击对应配置详情，进入配置页面，新建配置规则。

   

4. veImageX 支持您填写不同的规则，为满足不同条件的环境下发不同的采样率配置，配置完成后单击保存。