Miku 抖音小程序 SDK 文档

安装

npm install @qiniu/miku-delivery-mp-tt --save

因为抖音小程序开发工具对 npm 包的支持还不完善，我们需要手动将依赖包中的文件拷贝到项目中；这里以拷贝到项目中的 lib/miku-delivery/ 目录为例：

mkdir lib
cp -r node_modules/@qiniu/miku-delivery-mp-tt/dist ./lib/miku-delivery

注意事项

在使用前，需要在小程序管理后台配置域名白名单（详见 配置域名白名单），将以下域名添加到白名单中：

• https://api.qiniudns.com

使用

使用 Miku Delivery SDK 分为 2 步：

1. 在小程序启动时初始化 SDK
2. 替换界面上的媒体组件

1. 在小程序启动时初始化 SDK

在小程序的 App 定义处（一般是 app.js）引入 SDK 并在 App onLaunch 回调中初始化：

import { init as initMD } from './lib/miku-delivery/index'

App({
  onLaunch() {
    initMD({
      /** Miku 应用信息 */
      app: { appID: '<APP_ID>', appSalt: '<APP_SALT>' },
      /** 需要被代理的域名列表 */
      domains: ['proxy-example.com']
    })
  }
})

2. 替换界面上的媒体组件

对于基础媒体组件 image & video，Miku Delivery SDK 提供了与之对应的组件；这里以视频（video）为例：

在使用视频（video）的页面对应的 json 文件中添加

{
  "usingComponents": {
    "md-video": "../lib/miku-delivery/components/video"
  }
}

在页面对应的 ttml 文件中，将

<video src="..."><video>

替换为

<md-video src="..."><md-video>

即可（<md-video> 与 <video> 的属性、事件均一致）；如果该视频 src 对应的域名出现在上面初始化 SDK 时指定的 domains 中，则该视频资源会被 SDK 代理；若视频 src 对应的域名不在初始化 SDK 时指定的 domains 中，则 SDK 不会对该资源进行代理，即，此时 <md-video> 的行为等价于 <video>。

通过 VideoContext 操作对应的 video 组件

上面提到，<md-video> 与 <video> 的属性、事件均一致；不过如果要通过 VideoContext 操作对应的视频播放器，这里需调整获取 VideoContext 实例的姿势：

首先给 <md-video> 添加 tt:ref（如 mdVideoHandler）：

<md-video tt:ref="mdVideoHandler" src="..."><md-video>

然后在对应的 JavaScript 文件中可以通过名为 mdVideoHandler 的 method 获取到 md-video 组件的实例：

Page({
  mdVideoHandler(mdVideo) {
    // mdVideo 即 `md-video` 组件的实例
  }
})

通过组件实例上的 getVideoContext 方法即可得到对应的 VideoContext 实例，如：

let videoContext = mdVideo.getVideoContext()
videoContext.play()

即可控制视频开始播放。

自定义组件的样式

因为抖音小程序平台的设定，自定义组件节点默认会被一层 inline 元素包裹，这使得其默认的布局行为与原生的媒体组件不同。

以 image 为例，其默认为 display: inline-block，因此我们需要在项目代码中给 md-image 对应的节点添加 display: inline-block 样式，它才会表现地跟普通 image 一致，示例代码如下：

<md-image class="my-image" src="..."></md-image>

.my-image {
  display: inline-block;
}

API Reference

/** 初始化 SDK */
async function init(
  /** 初始化配置 */
  config: InitConfig
): Promise<void>

/** SDK 初始化配置信息 */
export type InitConfig = {
  /** 应用信息 */
  app: AppInfo
  /** 需要被代理的域名列表 */
  domains: string[]
  /** 开启 debug 模式 */
  debug?: boolean
}

/** App 信息 */
type AppInfo = {
  appID: string
  appSalt: string
}

/** 组件 components/video */
// 同 video，见 https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/component/media-component/video/

/** 组件 components/image */
// 同 image，见 https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/component/media-component/image/