@qiniu/miku-delivery-mp-ks/README.md

Kuaishou Mini Program SDK for Miku Delivery

# Miku 快手小程序 SDK 文档

## 安装

```shell
npm install @qiniu/miku-delivery-mp-ks --save
```

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

```shell
mkdir lib
cp -r node_modules/@qiniu/miku-delivery-mp-ks/dist ./lib/miku-delivery
```

## 注意事项

在使用前，需要在小程序管理后台设置服务域名（详见 [服务域名配置](https://mp.kuaishou.com/docs/introduction/develop.html#%E6%9C%8D%E5%8A%A1%E5%9F%9F%E5%90%8D%E9%85%8D%E7%BD%AE)），将以下域名添加到 request 合法域名中：

* https://api.qiniudns.com

## 使用

使用 Miku Delivery SDK 分为 2 步：

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

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

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

```js
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 文件中添加

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

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

```xml
<video src="..."><video>
```

替换为

```xml
<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 操作对应的 `video` 组件，这里需调整获取 VideoContext 实例的姿势：

首先给 `<md-video>` 添加 `id`（如 `md-video-1`）：

```xml
<md-video id="md-video-1" src="..."><md-video>
```

然后通过 `selectComponent` 获取到组件实例：

```js
let mdVideo = this.selectComponent('#md-video-1')
```

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

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

即可控制视频开始播放。

#### 自定义组件的样式

因为小程序平台的设定，自定义组件节点会被一层元素包裹，这使得其默认的布局行为与原生的媒体组件可能有细微的不同。在将原生的媒体组件替换为 SDK 提供的组件后，建议检查组件本身的布局、尺寸等，确认是否符合预期；如不符合预期，补充一些样式进行控制即可。

## API Reference

```ts
/** 初始化 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://mp.kuaishou.com/docs/develop/components/media/video.html

/** 组件 components/image */
// 同 image，见 https://mp.kuaishou.com/docs/develop/components/media/image.html
```