集成 Taro 小程序加载 SDK

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

能力说明

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

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

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

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

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

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

功能优势

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（属性）

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

loader 配置示例

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

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

事件

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

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

日志上报

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

添加 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;
}

具体参数说明如下所示：

查看上报数据

开通日志上报能力后，您可登录 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 支持您填写不同的规则，为满足不同条件的环境下发不同的采样率配置，配置完成后单击保存。