集成抖音小程序加载 SDK

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

具体参数说明如下所示：