集成微信小程序加载 SDK

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

能力说明

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

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

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

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

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

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

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

功能优势

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

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

• 提升视觉稳定性：内置 4 种图片布局方式，可涵盖绝大多数的图片渲染场景，能避免累积布局偏移 CLS；

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

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

前提条件

• 已开通 veImageX 相关服务，未注册用户可注册账号免费试用；
• 您微信小程序项目已支持 npm 功能。

注意事项

鉴于本组件目前尚未与微信小程序的 Skyline 渲染引擎兼容，因此在使用该引擎时可能会遇到无法预测的兼容性问题。

集成准备

环境要求

请提前确保您的微信开发者工具当前已支持 npm 功能。

模板配置

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

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

   

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

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

      

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

      

      说明

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

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

快速开始

安装 SDK

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

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

构建 npm 包

在微信开发者工具的选项中，选择构建 npm。npm 产物会输出到项目中的miniprogram_npm目录中。对于本组件，您可以通过@volcengine/imagex-mp-weixin/index引用。

集成 SDK

请参考微信小程序如何使用自定义组件，在对应页面/组件的配置中加入以下配置。

// ./pages/some-page/index.json
{
  "usingComponents": {
    "imagex-viewer": "@volcengine/imagex-mp-weixin/index",
  }
}

功能接入

Prop（属性）

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

loader 配置示例

// 首先声明所需要的 loader 函数，并进行注册
const loaderFunc = (props: ImageLoaderProps) => {
  const {src, width, quality, format} = props
  return `//example.com/${src}~tplv-serviceId-resize:${width}:q${quality}.${format}`
}
// 将 loaderFunc 注册为 key=myLoader
registerLoader("myLoader", loaderFunc)

// 使用时将对应的 key 传递给组件即可，组件内会根据 key 查找对应的 loader 函数
<imagex-viewer
  loader="myLoader"
  // ...other props
>
</imagex-viewer>

layout 配置说明

<view
 style="position: relative; width: 60vw; height: 60vh; padding: 10px 20px; border: 10px solid #eae2fd; background-color: #d7f5d5;"
>
    <imagex-viewer
        layout="fill"
        src="{{src}}"
        mode="{{mode}}"
        loader="{{loader}}"
        formats="{{formats}}"
        quality="{{75}}"
        width="{{200}}"
        height="{{200}}"
    ></imagex-viewer>
</view>
  	

<view
 style="position: relative; width: 60vw; height: 60vh; padding: 10px 20px; border: 10px solid #eae2fd; background-color: #d7f5d5;"
>
    <imagex-viewer
        layout="fixed"
        src="{{src}}"
        mode="{{mode}}"
        loader="{{loader}}"
        formats="{{formats}}"
        quality="{{75}}"
        width="{{300}}"
        height="{{300}}"
    ></imagex-viewer>
</view>
  	

<view
 style="position: relative; width: 80vw; padding: 10px 20px; border: 10px solid #eae2fd; background-color: #d7f5d5;"
>
    <imagex-viewer
        layout="intrinsic"
        src="{{src}}"
        mode="{{mode}}"
        loader="{{loader}}"
        formats="{{formats}}"
        quality="{{75}}"
        width="{{250}}"
        height="{{200}}"
    ></imagex-viewer>
</view>
  	

<view
 style="position: relative; width: 80vw; padding: 10px 20px; border: 10px solid #eae2fd; background-color: #d7f5d5;"
>
    <imagex-viewer
        layout="responsive"
        src="{{src}}"
        mode="{{mode}}"
        loader="{{loader}}"
        formats="{{formats}}"
        quality="{{75}}"
        width="{{250}}"
        height="{{200}}"
    ></imagex-viewer>
</view>
  	

Event（事件）

type Event<T> = {
  currentTarget: Element; // 事件绑定的组件
  detail: T; // 事件数据
  target: Element; // 事件触发的组件
  timestamp: number; // 事件触发时间戳
  type: string; // 事件类型
}

Demo 示例

您可在对应的页面/组件中，使用imagex-viewer组件，代码示例如下所示：

<!-- ./pages/some-page/index.ttml -->
<block>
    <imagex-viewer
        layout="{{layout}}"
        src="{{src}}"
        mode="{{mode}}"
        loader="customLoaderName"
        formats="{{formats}}"
        placeholder="{{placeholder}}"
        quality="{{quality}}"
        unoptimized="{{unoptimized}}"
        width="{{width}}"
        height="{{height}}"
        errorDataUrl="{{errorDataUrl}}"
        alt="{{alt}}"
        bind:load="onImageLoad"
        bind:loadingComplete="onImageLoadingComplete"
        bind:error="onImageLoadError"
    ></imagex-viewer>
</block>

日志上报

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

添加 request 域名

在小程序后台 > 开发 > 开发设置 > 服务器域名中添加以下域名配置：

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

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

初始化

具体代码示例如下所示。

import { initLoggerInstance } from '@volcengine/imagex-mp-weixin/tool/index'

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

App({
  onLaunch: function () {
    console.log('App Launched');
    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 支持您填写不同的规则，为满足不同条件的环境下发不同的采样率配置，配置完成后单击保存。