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

能力说明

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

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

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

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

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

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

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

功能优势

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

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

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

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

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

前提条件

• 已开通 veImageX 相关服务，未注册用户可注册账号免费试用；

• 您的抖音小程序项目依托宿主需为抖音、抖音极速版、今日头条、西瓜视频或懂车帝；

• 您的抖音小程序项目已支持 npm 功能且已完成初始化 package.json。

集成准备

环境要求

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

兼容要求

• iOS 端暂不支持使用该组件加载 heif 图。

• Android 端支持使用该组件加载 heif 图，且暂无最低版本要求。

模板配置

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

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

   

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

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

      

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

      

      说明

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

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

快速开始

安装 SDK

请参考以下两种方式安装抖音小程序加载组件：

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

构建 npm 包

在抖音开发者的 npm 面板中，构建 npm 包。npm 产物会输出到项目中的miniprogram_npm目录中。对于本组件，您可以通过/miniprogram_npm/@volcengine/imagex-mp-douyin/index引用。

集成 SDK

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

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

功能接入

Prop（属性）

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

{
   template: string;
   domain: string;
}

{
    loaderStr: string;
}

LoaderProps 配置说明

LoaderProps 有两种配置方式，两种方式分别会实际生成如下图片 URL：

// 传入的 loaderProps 参数：
declare let loaderProps: {domain: "example.com", template: "tplv-example-resize"};

// SDK 内部根据传入的URL、质量参数、自适应格式列表等计算得到的参数如下：
declare let loaderParams: {
  src: string; // 图片访问 path 部分，访问 URL，不包含域名，如：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
  };
};

const {src, width, quality, format} = loaderParams;

// 最后实际传递给 image 标签的资源
const result = `//${loaderProps.domain}/${src}~${loaderProps.template}:${width}:q${quality}.${format}`
  	

// 其中 __${paramName}__ 会被替换为 loaderParams[paramName]
// 文字水印的URL参数部分：ZXhhbXBsZQ==
const loaderStr = '//example.com/__${src}__~tplv-example-resize:ZXhhbXBsZQ==:__${width}__:q__${quality}__.__${format}__'

// 最后实际传递给 image 标签的资源
const result = `//example.com/${loaderParams.src}~tplv-example-resize:ZXhhbXBsZQ==:${loaderParams.width}:q${loaderParams.quality}.${loaderParams.format}`
  	

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}}"
        loaderProps="{{loaderProps}}"
        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}}"
        loaderProps="{{loaderProps}}"
        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}}"
        loaderProps="{{loaderProps}}"
        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}}"
        loaderProps="{{loaderProps}}"
        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}}"
        loaderProps="{{loaderProps}}"
        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 域名

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

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

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

初始化

具体代码示例如下所示：

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

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

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