You need to enable JavaScript to run this app.
导航

集成 React 加载 SDK

最近更新时间2024.02.04 17:33:00

首次发布时间2023.02.15 15:53:04

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

图片加载

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

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

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

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

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

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

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

功能点功能描述云端依赖

格式自适应

根据客户端兼容情况自动适配不同的格式,例如:webp 自适应、avif 自适应。
自适应原理:<picture> 标签 + 格式探测

注意

使用防盗链情况下需服务端同时下发多个带签名的 URL。

依赖 veImageX 云端配置模板

分辨率自适应

根据图片所在容器大小选择合适分辨率的图片渲染,在不影响图片观感的情况下减小图片体积。

注意

  • 支持配置图片分辨率列表,SDK 从列表中选择接近容器大小的图片。
  • 使用防盗链情况下需服务端同时下发多个带签名的 URL。

依赖 veImageX 云端配置中携带缩放能力的模板

图片压缩支持配置图片质量参数,基于云端实现图片压缩。依赖 veImageX 云端配置中携带质量参数的模板
稳定性布局内置 5 种稳定性布局,以减少 CLS 布局抖动,具体请参考下文布局方式说明。无依赖
懒加载内置图片懒加载,图片出现在浏览器视口内时再加载图片。无依赖
错误兜底支持自定义兜底图,图片加载失败时渲染兜底图。无依赖
占位图片支持自定义占位图,图片加载完成之前优先渲染占位图。无依赖

图片监控

支持图片加载各阶段(DNS、TCP、SSL、发送、等待、接受)耗时、加载成功率、错误码分布、网络链接复用率、http/https 占比等指标。

功能优势

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

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

说明

业务实践收益参考,实际请以您的具体情况为准:

  • 图片传输流量减少 60% 以上;

  • 图片格式中 WEBP 和 AVIF 占比均达到 40% 以上;

  • 图片体积均值由 600KB 降低至 250KB 左右,减小 58%;

  • 图片加载耗时均值由 800ms 降低至 400 ms 以下,减小 50%;

  • 图片未压缩、格式待优化、未懒加载比例均有下降。

集成准备

环境要求

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

兼容要求

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

能力浏览器版本要求

格式自适应能力

说明

格式自适应能力依赖 <picture> 标签使用。

  • Chrome 38 及以上版本
  • Firefox 38 及以上版本
  • Safari(无版本限制)

说明

IE 浏览器不支持 <picture> ,图片渲染按照原图兜底。

懒加载能力

说明

懒加载能力依赖 IntersectionObserver API 使用。

  • Chrome 58 及以上版本
  • Firefox 55 及以上版本
  • Safari 12 以上版本

说明

IE 浏览器不支持懒加载。

模板配置

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

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

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

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

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

      说明

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

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

快速开始

前提条件

安装 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}`}
/>

功能接入

参数说明

属性名
类型
是否必填说明

width

Number

图片宽度。仅当layout取值为fillraw时选填,其他布局为必填。

  • intrinsicfixed 布局下用于设置图片渲染宽度;
  • fillresponsive 布局下表示图片宽高比。

height

Number

图片高度。仅当layout取值为fillraw时选填,其他布局为必填。

  • intrinsicfixed 布局下用于设置图片渲染高度;
  • fillresponsive 布局下表示图片宽高比。
srcString图片路径,可访问的图片 URL

layout

intrinsic|responsive|fixed|fill|raw

布局方式,取值如下所示:

  • intrinsic:(默认)图片宽度自适应容器,最大宽度为组件中设置的图片宽度,并按原图比例适配图片高度。

  • responsive:图片宽度完全自适应容器,图片高度按照原图比例进行缩放。

  • fixed:固定的图片宽高。

  • fill:填充容器,结合 objectFit、objectPosition 可实现多种填充模式。

  • raw:移除外层布局相关 dom,只保留 <picture> 标签。

说明

具体布局说明请参考下文中给出的配置说明、代码示例和效果图。

loader

(props: ImageLoaderProps) => string

图片 URL 拼接函数。当unoptimized取值为false时,必填。函数入参包含 src, width, quality, format 等参数,返回拼接处理参数后的 url。格式自适应和分辨率自适应能力均依赖该函数实现。

  • 格式自适应:结合浏览器支持性以及 formats 属性中指定的格式列表,选择最优的格式传递至函数的入参 format,函数返回相应格式的图片 url;
  • 分辨率自适应:结合图片所在容器大小、屏幕分辨率以及 imageSizes 属性中指定的图片分辨率列表,选择最合适的分辨率传递至函数的入参 width,函数返回相应分辨率的图片 url。
    loader 配置示例如下所示:
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}`

formats

string[]

自适应格式列表,结合 loader 方法实现格式自适应。取值如下所示:

  • webp (默认)
  • avif
  • jpeg
  • png

说明

  • 指定 ['webp']时,表示仅支持 webp 格式自适应;
  • 若指定为 [avif, webp] 则表示优先 avif 格式自适应,其次是 webp 格式自适应,最后用原图格式兜底。

imageSizes

number[]

图片尺寸列表,默认为[480, 750, 1080, 1366, 1920],SDK 从该列表中选取最合适的图片大小。

说明

传入空数组 [] 情况下组件会计算图片或其所在容器大小,直接拉取相应大小的图片(若设置为空数组在一定程度上会降低 cdn 的命中率)。

loading

lazy| eager

定义图片加载行为,取值如下所示:

  • lazy: (默认)懒加载
  • eager :立即加载

placeholder

empty| skeleton| String

为了保证布局稳定性以及性能指标,可预先渲染占位图。取值如下所示:

  • empty:(默认)无占位
  • skeleton:骨架屏占位
  • 支持自定义占位图,例如:data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAMAAAC67D+PAAAABlBMVEW/0v/K2/+wPdJoAAAAI0lEQVQImWNghAMGEGZggDAZIIARxgCxGQgAFG1QnVBzoQAACT8AKbEcZzAAAAAASUVORK5CYII=

errorDataURL

String

可自定义图片加载错误占位图,建议您传入 base64 编码的占位图。layout取值为raw时,暂不支持设置。
默认效果如下图所示(下方文案取 “alt” 属性的值):

errorReactNode自定义错误样式,若默认的样式不符合要求,支持传入 ReactNode 完全自定义错误兜底。layout取值为raw时,暂不支持设置。
qualityNumber质量参数。默认值为 75,取值范围为[0, 100]。取值越低,图片越模糊。

unoptimized

Boolean

是否关闭图片优化,取值如下所示:

  • true:关闭,关闭图片优化后将不再支持格式自适应、分辨率自适应能力。
  • false:(默认)开启。
lazyRootReact.RefObject<HTMLElement>用于图片懒加载配置,指向图片所在的容器元素。默认值为null,指向当前视口。
lazyBoundaryString用于指定懒加载时触发图片渲染的边界,默认值为 200 px。
objectFitStringlayout取值为fill时,用于指定图片元素如何适应容器,与 css 属性 object-fit 相同。
objectPositionStringlayout取值为fill时,用于指定图片元素在容器内的位置,与 css 属性 object-position相同。

onLoadingComplete

(result: {
naturalWidth: number;
naturalHeight: number;
}) => void

图片加载后的回调函数,参数为图片实际的宽高,单位为 px。

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

各布局样式配置

图片宽度自适应容器,最大宽度为组件中设置的图片宽度,并按原图比例适配图片高度。若 width 小于容器宽度,则根据指定宽高渲染图片;否则,图片实际宽度等于容器宽度,图片高度按照原图比例缩放适配。代码示例如下所示:
<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>
  	

具体实现效果如下所示。

全局配置

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

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

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

注意

图片监控 SDK 在实例化失败时会抛出异常,请您自行捕获并对其进行处理。

集成准备

兼容要求

SDK 监控功能基于浏览器的PerformanceObserver APIMutationObserver API,则适用浏览器及版本如下所示:

  • Chrome 52 及以上版本

  • Edge 79 及以上版本

  • Safari 11 及以上版本

  • Firefox 57 及以上版本

说明

不支持所有版本的 IE 浏览器。

获取 AppID

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

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

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

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

响应头配置

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

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

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

快速开始

前提条件

安装 SDK

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

推荐您使用通过 CDN 引入的方式,将引入的代码加入到 HTML 文件的 head 标签中。则监控 SDK 能尽早实例化并启动监听,监控到尽可能多的图片加载数据。

其中,请参考 React 加载 SDK 发布历史获取 SDK 最新版本号后,将 Demo 中的 x.x.x 替换为最新版本号。

<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>
	

数据上报验证

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

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

功能接入

参数说明

参数
类型
是否必填默认值说明

el

String | HTMLElement

-

监听元素。

  • 全局监控:传入document.body
  • 单点监控:可传入一个单独的 img/picture 标签或传入 string,SDK 内部会通过 document.querySelector(el) 查找对应元素。
selectorStringimg过滤 selector,只会监控并上报符合该 selector 的元素触发的图片加载行为。支持设置类名等,监控该类下的图片加载数据。
regioncn | sg-区域,会影响上报的域名。当启用 SDK 配置下发 时,会影响获取 SDK 配置的请求域名。
appIdNumber-AppId,具体获取方式请参考获取 AppID
userUniqueIdString-用户 ID,支持自定义,用于将数据对应到特定用户。

include

Array<RegExp>

-

对图片 URL 进行正则校验,可以使用多个规则进行校验,满足任一规则就会发起上报。

说明

includeexclude 规则同时匹配的情况下,由于 exclude 优先级高于 include ,因此最终将不会发起上报。

exclude

Array<RegExp>

-

对图片 URL 进行正则校验,可以使用多个规则进行校验,满足任一规则就不会发起上报。

说明

includeexclude 规则同时匹配的情况下,由于 exclude 优先级高于 include ,因此最终将不会发起上报。

enableCloudConfig

Boolean

false

是否启用云端配置下发。该功能需要与 veImageX 服务端能力联动,在启用前,请确保已经在 veImageX控制台-SDK配置下发 进行配置,具体操作请参考云端下发配置内容。目前支持下发采样率相关配置。取值如下所示:

  • true:开启
  • false:关闭

defaultConfig.reportRateConfig.reportRate

Number

1

默认的日志采样率配置,取值范围为[0, 1],1代表全部上报。
enableCloudConfig取值为true时,会被请求得到的云端配置覆盖,即开启云端配置后以云端配置为准。

defaultConfig.reportRateConfig.reportRateError

Number

1

默认的错误日志采样率配置,取值范围为[0, 1],1代表全部上报。
enableCloudConfig取值为true时,会被请求得到的云端配置覆盖,即开启云端配置后以云端配置为准。

代码示例如下所示:

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 支持您填写不同的规则,为满足不同条件的环境下发不同的采样率配置,配置完成后单击保存