You need to enable JavaScript to run this app.
导航
集成微信小程序加载 SDK
最近更新时间:2024.02.04 17:33:46首次发布时间:2023.11.02 17:44:42

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

能力说明

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

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

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

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

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

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

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

功能点功能描述云端依赖

格式自适应

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

注意

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

依赖 veImageX 云端配置模板

分辨率自适应

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

注意

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

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

图片压缩支持配置图片质量参数,基于云端实现图片压缩。依赖 veImageX 云端配置中携带质量参数的模板
稳定性布局内置 4 种稳定性布局,以减少布局抖动,具体请参考下文布局方式说明无依赖
懒加载内置图片懒加载,图片出现在小程序上下左右三屏内时再加载图片。无依赖
错误兜底支持自定义兜底图,图片加载失败时渲染兜底图。无依赖
占位图片支持自定义占位图,图片加载完成之前优先渲染占位图。无依赖
日志上报支持图片加载各阶段(DNS、TCP、SSL、发送、等待、接受)耗时、加载成功率、错误码分布、网络链接复用率、http/https 占比等指标。依赖 veImageX 云端配置日志采样率、错误日志采样率

功能优势

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

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

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

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

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

前提条件

注意事项

鉴于本组件目前尚未与微信小程序的 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引用。
alt

集成 SDK

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

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

功能接入

Prop(属性)

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

属性名类型是否必填说明

width

Number

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

  • intrinsicfixed 布局下用于设置图片渲染宽度;

  • fillresponsive 布局下表示图片宽高比。

height

Number

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

  • intrinsicfixed 布局下用于设置图片渲染高度;

  • fillresponsive 布局下表示图片宽高比。

layout

intrinsic|responsive|fixed|fill

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

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

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

  • fixed:固定的图片宽高。

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

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

modestring详情参考微信小程序 image 组件文档中 mode 的合法值,默认为 scaleToFIll
srcString加载图片路径,可访问的图片 URL。

loader

String

用于图片 URL 拼接的 loader 函数对应的 key。当 unoptimized 取值为 false 时,必填。 格式自适应和分辨率自适应能力均依赖该属性实现。

说明

在配置 loader 属性之前,请使用 registerLoader 方法注册对应的 loader 函数。具体使用方法请参见 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 方法实现格式自适应。取值如下所示:

  • webp (默认)

  • avif

  • jpeg

  • png

说明

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

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

imageSizes

number[]

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

说明

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

unoptimized

Boolean

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

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

  • false:(默认)开启。

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

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 配置说明

图片缩放以填充容器,width、height 属性表示图片宽高比,不指定则以图片原始比例渲染。

说明

请务必在容器配置中设置position: 'relative'

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

具体效果如下所示。

alt

Event(事件)

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

bind:loadingComplete

(evt: Event<{ naturalHeight: number; naturalWidth: number; }>) => void;

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

bind:load(evt: Event<{ height: number; width: number; "loaded-src": string; src: string; }>) => void;图片加载后的回调函数,参数为图片宽高以及实际加载的图片 src。
bind:error(evt: Event<{ errMsg: string; }>) => void;图片加载失败之后的回调函数,参数为错误原因。

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

alt

初始化

具体代码示例如下所示。

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

具体参数说明如下所示:

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

region

cn | sg

-

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

  • cn:国内
  • sg:新加坡

appId

Number

-

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

  • 您可以登录 ImageX 控制台的应用管理,查看账号下已创建应用的应用 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 支持您填写不同的规则,为满足不同条件的环境下发不同的采样率配置,配置完成后单击保存