You need to enable JavaScript to run this app.
导航
集成 Taro 小程序加载 SDK
最近更新时间:2024.02.04 17:34:10首次发布时间:2023.12.22 17:08:53

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

注意

当前仅支持在微信小程序抖音小程序中使用本组件。

能力说明

Taro 小程序图片加载 SDK 旨在优化小程序中的图片资源,其核心能力及说明如下所示:

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

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

  • 图片懒加载:图片延迟加载,只有当图片出现在上下左右三屏的范围时,再获取图片资源进行渲染。

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

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

功能点功能描述云端依赖

格式自适应

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

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

依赖 veImageX 云端配置模板

分辨率自适应

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

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

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

图片压缩支持配置图片质量参数,基于云端实现图片压缩。依赖 veImageX 云端配置中携带质量参数的模板
懒加载内置图片懒加载,图片出现在小程序上下左右三屏内时再加载图片。无依赖
错误兜底支持自定义兜底图,图片加载失败时渲染兜底图。无依赖
占位图片支持自定义占位图,图片加载完成之前优先渲染占位图。无依赖
日志上报支持图片加载耗时、加载成功率、错误码分布、网络链接复用率、http/https 占比等指标。依赖 veImageX 云端配置日志采样率、错误日志采样率

功能优势

Taro 小程序图片加载 SDK 基于 veImageX 图片服务,旨在优化小程序中的图片资源,其核心功能优势如下所示:

  • 节省图片流量:您可通过使用格式自适应和分辨率自适应功能来达到提升站点性能并节省流量的目的;

  • 提高页面加载速度:您可通过使用过渡图占位和图片懒加载功能达成更快的页面加载;

  • 灵活处理图片资源:已支持图片缩放、压缩、格式转换等图片模板能力,您可在配置模板后对加载图片进行灵活处理。

前提条件

开通 veImageX 相关服务,未注册用户可注册账号免费试用。

集成准备

环境要求

本文档适用于 Taro 3.6 及以上版本。

模板配置

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

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

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

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

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

      说明

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

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

快速开始

安装 SDK

在项目目录下,执行以下命令安装 SDK。

npm install @volcengine/imagex-mp-taro
# or
yarn add @volcengine/imagex-mp-taro

集成 SDK

安装成功后,执行以下命令集成 SDK。

import Viewer from '@volcengine/imagex-mp-taro'

const loader = ({ src, width, quality, format }) =>
          `https://test.example.com/${src}~tplv-serviceid-resize:${width}:q${quality}.${format}`
const formats = ['heif', 'avif', 'webp'] // formats 需要注意顺序,默认选择第一个支持的格式

export function Page() {
    // ...省略参数

    return (
        <Viewer
          onLoad={evtHandler}
          onLoadingComplete={evtHandler}
          onError={evtHandler}
          mode={mode}
          formats={formats}
          placeholder={placeholder}
          loader={loader}
          width={width}
          height={height}
          src={src}
          errorDataUrl={errorDataUrl}
          quality={quality}
          alt={alt}
          imageSizes={imageSizes}
          unoptimized={unoptimized}
        />
    )
}

参数与事件说明

Prop(属性)

该组件支持配置及相关参数与事件说明如下表所示。

属性名类型是否必填说明

width

Number

图片宽度,将应用在图片容器的样式中的 width。支持指定以下内容:

  • px:"200px"

  • rpx:支持"200rpx"200"200"三种传入方式

  • 百分比:"50%"

height

Number

图片高度,将应用在图片容器的样式中的 height。支持指定以下内容:

  • px:"200px"

  • rpx: 支持"200rpx"200"200"三种传入方式

  • 百分比:"50%"

modestring默认为 scaleToFill,更多可选值参考 Image 组件说明
srcString加载图片路径,可访问的图片 URL。
loaderFunctionloader 函数,当unoptimized取值为false时,必填。 格式自适应和分辨率自适应能力均依赖该属性实现。具体使用方法请参见 loader 配置部分。

loading

lazy| eager

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

  • lazy: (默认)懒加载

  • eager :立即加载

placeholder

empty| skeleton| String

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

  • empty:(默认)无占位

  • skeleton:骨架屏占位

  • 支持自定义占位图,例如:data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAMAAAC67D+PAAAABlBMVEW/0v/K2/+wPdJoAAAAI0lEQVQImWNghAMGEGZggDAZIIARxgCxGQgAFG1QnVBzoQAACT8AKbEcZzAAAAAASUVORK5CYII=

errorDataURL

String

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

qualityNumber质量参数。默认值为 75,取值范围为[0, 100]。取值越低,图片越模糊。

formats

string[]

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

  • heic

  • webp(默认)

  • avif

  • jpeg

  • png

说明

  • 指定 [webp]时,表示仅支持 webp 格式自适应;

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

imageSizes

number[]

图片尺寸列表,默认为[480, 750, 1080, 1366, 1920]。
当传入的 width 为非百分比形式时,SDK 从该列表中选取首个满足条件的图片大小。当传入的width为百分比形式时,默认选择第一个。

说明

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

unoptimized

Boolean

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

  • true:关闭,关闭图片优化后将不再支持格式自适应、分辨率自适应能力。

  • false:(默认)开启。

altString图片加载错误时,用于占位的说明文字。

loader 配置示例

参考以下标准 loader 配置示例,构建一个包含域名、路径、模板、模板参数、质量参数和图片格式的 URL。

//域名/src~模板:模板参数:q质量参数.图片格式
const myLoader = ({ src, width, quality, format }) => 
    `https://example.com/${src}~tplv-serviceId-resize:${width}:q${quality}.${format}`

事件

属性回调参数类型是否必填说明

onLoad

{
    width: number;//图片宽
    height: number;//图片高
    src: string;//图片加载路径
}

透传的 Image 标签原生 onLoad 事件

onError

{
    errMsg: string;//加载失败的错误原因
}

透传的 Image 标签原生 onError 事件

日志上报

该加载组件内置了日志上报能力,您可以通过日志上报在控制台查看图片加载过程中的相关指标变化。

添加 request 域名

在微信公众平台的 开发 > 开发设置 > 服务器域名中添加以下域名配置:

  • 图片域名:您的图片服务所绑定的 CDN 域名。

  • 日志上报域名https://mcs.zijieapi.com

初始化

具体代码示例如下所示。

import { initLoggerInstance } from '@volcengine/imagex-mp-taro'

const logger = {
  region: 'cn',//国内。会影响上报的域名。当启用 SDK 配置下发 时,会影响获取 SDK 配置的请求域名。
  appId: 123456, //请替换为您获取的 AppID
  userUniqueId: 'miniprogram-test',// 用户ID,自定义,用于将数据对应到特定用户
  enableCloudConfig: false,// 是否启用云端配置下发,仅支持读取正常日志上报采样率、错误日志上报采样率。需要与veImageX服务端能力联动,在控制台-SDK配置下发进行配置,具体请参考下文云端下发配置
  reportRateConfig: {
    reportRate: 1,// 正常日志上报采样率
    reportRateError: 1 // 错误日志上报采样率
  },
  callback: (evtName, ...evtParams) => {
    console.log(evtName, evtParams)
  }
};

initLoggerInstance(logger)

其中 LoggerOptions 的类型定义为

interface ReportRate {
  reportRate: number;
  reportRateError: number;
}

interface LoggerOptions {
  region: "cn" | "sg";
  appId: number;
  userUniqueId: string;
  enableCloudConfig?: boolean;
  reportRateConfig?: ReportRate;
}

具体参数说明如下所示:

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

region

cn | sg

-

区域,会影响上报的域名。当启用 SDK 配置下发 时,会影响获取 SDK 配置的请求域名。 取值如下所示:

  • cn:国内
  • sg:新加坡

appId

Number

-

应用 ID。用于定位某一条业务线的日志。

  • 您可以登录 veImageX 控制台的应用管理,查看账号下已创建应用的应用 ID。

  • 您可以通过调用 GetImageXQueryApps 接口获取账号下已创建的全部应用 ID。

userUniqueIdString-用户 ID,支持自定义,用于将数据对应到特定用户。

enableCloudConfig

Boolean

false

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

  • true:开启

  • false:关闭

reportRateConfig.reportRateNumber1默认的日志采样率配置,取值范围为[0, 1],1代表全部上报。当enableCloudConfig取值为true时,会被请求得到的云端配置覆盖,即开启云端配置后以云端配置为准。
reportRateConfig.reportRateErrorNumber1默认的错误日志采样率配置,取值范围为[0, 1],1代表全部上报。当enableCloudConfig取值为true时,会被请求得到的云端配置覆盖,即开启云端配置后以云端配置为准。
callback(evtName: string, params: Record<string, unknown>)-日志上报回调,会将上报的日志内容传入该函数,供开发者自行消费。

查看上报数据

开通日志上报能力后,您可登录 veImageX 控制台 > 服务质量监控查看上报的图片质量数据,具体支持指标如下所示:

  • 下行网络监控:网络耗时、DNS 耗时、TCP 建联耗时、SSL 握手时间、发送时间、等待时间、接收时间、网络成功率、错误码分布、网络链接复用率、http/https 占比

  • 客户状态监控:加载耗时、SDK 版本变化、文件大小分布、图片样本量

修改云端下发配置 (可选)

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

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

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

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

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