前端 SDK

最近更新时间:2020-05-29 10:20:37

云剪辑 SDK 主要用于协助用户完成云剪辑 Web 端开发等。

准备工作

已做好相关准备,应用服务已就绪,更多详情请参见 快速入门

快速开始

使用我们的 CDN 引入 SDK,<script src="https://imgcache.qq.com/qcloud/cme/sdk_v1.js"></script>,在页面初始化完成以后填入如下代码。

/* @create  创建实例方法,没调用该方法之前,调用 send 方法通信无效。
 *    @param el {{HTMLELement}}  html元素,作为父容器承载 CME 组件。
 *    @param options {{ object|hash }} 参数。
 *         @param sign {{ string }} ,该项目签名.具体参考签名算法。
 *    @return 返回一个 cme 组件实例。
 **/
let myCmeInstance = CME.create(document.getElementById("Container"), {
  sign: "your_signature",
});

/**
 * 页面初始化异常时,会抛出Error事件。
 **/
myCmeInstance.on("Error", (data) => {
  console.log("Error", data);
});

/**
 * 页面组件完全准备好以后,会抛出:Editor:Ready 事件,
 * 该事件触发以后,所有命令字会正常响应,触发之前,部分命令字无法响应。
 **/
myCmeInstance.on("Editor:Ready", () => {
  console.log("desc", "iframe Ready");
  /**
   *
   * @send 发送命令字方法,
   *    @param cmd {{string}} 字符串,参考 cme 命令字列表。
   *    @param param {{object}} 命令入参。
   *    @param callback {{function}} 完成命令的回调函数。
   *
   **/
  myCmeInstance.send("syncFusionData", {}, (data) => {
    console.log("sync done", data);
  });
});

let clickHandler = () => {
  console.log("Click");
};
/**
 *
 * @on 监听方法,监听来自 CME 的用户事件。
 *    @param eventName {{string}} 字符串,参考 cme 自定义用户事件。
 *    @param callback {{function}} 回调函数。
 *
 */
myCmeInstance.on("Editor:MoreResourceBtn:click", clickHandler);

/**
 * @off 取消监听方法,监听来自 CME 的事件,如果什么都不传则会清理所有监听事件。
 *    @param eventName {{string}} 字符串,参考 cme 自定义用户事件。
 *    @param callback {{function}} 对应回调函数。
 *
 */
myCmeInstance.off("Editor:MoreResourceBtn:click", clickHandler);

如果执行成功则可以看到开启一个 页面定制

页面定制

假如已经成功初始化,则可以看到下图这样的页面,页面可以做基础定制,目前只能通过 联系我们 来协助操作,后续会开放自助。

基础定制主要提供以下能力:

  • 设置页面元素隐藏和显示。
  • 定制页面元素呈现形态(仅支持替换 Logo 图标,修改部分文案的小幅修改)。
说明:

如果需要自定义处理用户事件,或定制化云剪辑行为,请参见 SDK 概述

可配置元素如下,图标位置对应上图标红数字

图标位置 描述
1 顶部 Logo。
2 顶部返回按钮。
3 上传按钮 。
4 更多资源按钮。
5 导出按钮。

SDK 概述

  • SDK 会使用CME作为命名空间,该命名空间包含如下对象和方法:
    方法名称功能描述
    create 用于创建 CME 组件实例。
  • 组件create后会返回一个CME组件实例,实例包含以下方法:
    方法名称功能描述
    send 控制云剪辑行为。
    on 用户事件监听抛出。
    destroy 销毁组件自身。

create

用于创建CME实例的工厂方法.与之对应则可以调用组件自身的 销毁方法。配置主要内容是身份校验和云剪组件应该出现位置以及相关操作。

/* @create  创建实例方法,没调用该方法之前,调用 send 方法通信无效。
 *    @param el {{HTMLELement}}  html元素,作为父容器承载 CME 组件。
 *    @param options {{ object|hash }} 参数。
 *         @param sign {{ string }} ,该项目签名.具体参考 签名算法。
 *    @return 返回一个 cme 组件实例。
 **/
let myCmeInstance = CME.create(document.getElementById("Container"), {
  sign: "your_signature",
});

destroy

/**
 * @destroy 清理所有监听事件、临时变量并将对象销毁。
 *  注意,此时cme对象引用会变为空。
 */
myCmeInstance.destroy();

send

云剪组件用 iframe 的方式嵌入到应用,采用 postMessage 方式与父容器通信,所以send必须在iframe内云剪辑页面加载成功以后可用(监听到Editor:Ready事件以后),否则无效或报错。

通过send方法发送 命令字 控制云剪辑的页面行为,实例如下:

  /**
   *
   * @send 发送命令字方法,
   *    @param cmd {{string}} 字符串,参考 cme 命令字列表。
   *    @param param {{object}} 命令入参。
   *    @param callback {{function}} 完成命令的回调函数。
   *
   **/
  myCmeInstance.send("syncFusionData", {}, (data) => {
    console.log("sync done", data);
  });

命令字列表

命令字 参数 可用范围 功能
refreshResources mids:素材 ID 列表数组(可选) 编辑页 更新素材,如果不什么都不传,会将素材刷新到为第一页(20 条数据),如果传入素材 ID,会去尝试将刷新传入素材 ID 到顶部。
syncFusionData - 编辑页 提交编辑数据,如果在外部触发导出项目事件,需要调用一次该接口。
showUpload sign: 上传签名 编辑页 开启上传面板,在云剪内部上传会使用云剪的即传即用功能,即浏览器支持度较好的媒体格式,如 .h264 的 MP4 视频和 WebM,可边上传边编辑, 不用等待完全上传和解码的全过程

on

监听来自云剪辑的 用户事件,与之相对应的有 移除事件

/**
 * 页面组件完全准备好以后,会抛出:Editor:Ready 事件,
 * 该事件触发以后,所有命令字会正常响应,触发之前,部分命令字无法响应。
 **/
myCmeInstance.on("Editor:Ready", () => {
  console.log("desc", "iframe Ready");
  /**
   *
   * @send 发送命令字方法,
   *    @param cmd {{string}} 字符串,参考 cme 命令字列表。
   *    @param param {{object}} 命令入参。
   *    @param callback {{function}} 完成命令的回调函数。
   *
   **/

用户交互事件

用户事件命名规则,可以使用控制台查看元素,元素上标有data-ui就会响应click,该事件抛出名字为:${data-ui}:Clickdata-ui以组件/页面,组件的方式命名,参考Editor:ExportBtn:Click可知道是编辑页导出按钮点击事件,具体导出事件如下:

  • 用户事件:

    事件名说明
    Header:BackBtn:Click 用户点击顶部返回按钮。
    Editor:ExportBtn:Click 用户点击导出按钮 。
    Header:Logo:Click 用户点击 Logo。
    Header:Goto:Click 用户点击顶部跳转按钮。
    Editor:MoreResourceBtn:Click 用户点击更多资源按钮
    Editor:UploadBtn:Click 用户点击上传按钮
  • 生命周期事件:

    事件名说明
    Editor:Ready页面加载完成。
  • 异常事件:

    事件名数据结构
    Error {error:1000,msg:'NotSupportBrowser'},更多错误码请参见 错误码

错误码

错误码 意义
1000 不支持的浏览器,目前只支持 Chrome60版本以上的浏览器

off

移除监听的云剪辑用户事件,与之对应的有 监听事件

/**
 * @off 取消监听方法,监听来自 CME 的事件,如果什么都不传则会清理所有监听事件。
 *    @param eventName {{string}} 字符串,参考 cme 自定义用户事件。
 *    @param callback {{function}} 对应回调函数。
 *
 */
myCmeInstance.off("Editor:MoreResourceBtn:click", clickHandler);
目录