开发
API
自2022年9月6日起,本文档站不再更新内容,相关文档已迁移至全新“抖音开放平台”前往

发布抖音视频

基础库 2.65.0 开始支持该能力。IDE 和非抖音宿主暂不支持此功能,请在抖音上调试。

流程说明

发布抖音视频主要有两步:

  1. 在页面的逻辑文件(.js)中注册 onUploadDouyinVideo 钩子
  2. 在页面的视图文件(.ttml)中使用 button 组件,并将组件的 open-type 属性设置成 uploadDouyinVideo

当用户点击 button 组件时,将会触发事先在逻辑文件中注册好的 onUploadDouyinVideo 钩子(位置与 onLoad 同级),钩子的返回值将被当作发布视频的参数,简要流程如下图所示:

uploadOptions 说明

uploadOptions 是触发 onUploadDouyinVideo 钩子时,开发者能拿到的回调参数。uploadOptions 是 object 类型,属性如下:

属性名类型说明最低支持版本
targetTarget上传抖音视频按钮 <button open-type="uploadDouyinVideo"> 的相关信息,包含 id、dataset、offsetTop、offsetLeft,详见 Target 类型说明2.65.0

Target 类型说明

object 类型,属性如下:

属性名类型说明最低支持版本
idstring上传抖音视频按钮的 id,即标签上的 id 属性2.65.0
datasetobject按钮标签上的自定义属性集,即标签上的 data-xx 属性2.65.0
offsetTopnumber按钮元素左上角相对于其 offsetParent 元素的顶部内边距的距离,详情参考 offsetTop2.65.0
offsetLeftnumber按钮元素左上角相对于其 offsetParent 元素的左边界的距离,详情参考 offsetLeft2.65.0

uploadParams 说明

uploadParams 是开发者在 onUploadDouyinVideo 钩子中返回的值,该返回值会作为上传参数,拉起抖音发布器。(注:uploadParams 支持众多抖音视频配置,数据结构较为复杂,可参考下文结构示例与代码辅助理解。如无特殊需求也可以只返回 videoPath,不使用任何特殊能力)uploadParams 是 object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
videoPathstring要发布的视频路径,只支持 ttfile 格式(可通过如 tt.chooseVideo 等 API 获取),暂不支持网络视频资源2.65.0
titleConfigTitleConfig视频的标题配置,详情参考 TitleConfig 类型说明2.65.0
stickersConfigStickersConfig视频的贴图配置,详情参考 StickersConfig 类型说明2.65.0
extraExtra挂载锚点等额外信息,详情参考 Extra 类型说明2.65.0
successfunction发布成功的回调函数2.65.0
failfunction发布失败的回调函数2.65.0
completefunction发布成功或失败时都会执行的回调函数2.65.0

TitleConfig 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
titlestring''发布视频的标题,字数限制为 60 个字符2.65.0
mentionMarkersMentionMarker[][]数据结构为 MentionMarker 组成的数组,往标题中某个位置插入提醒标记,表现为 @xxx,详情参考 MentionMarker 类型说明2.65.0
hashtagMarkersHashtagMarker[][]数据结构为 HashtagMarker 组成的数组,往标题中某个位置插入话题标记,表现为 #xxx,详情参考 HashtagMarker 类型说明2.65.0

MentionMarker 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
startnumber0在 title 中插入标记的起始位置下标,有效区间为 [0, 标题长度],小于 0 时会被重置成 0、大于标题长度时会被重置成标题长度2.65.0
openIdstring''该 mentionMarker 提醒的人,表现为 @xxx2.65.0

HashtagMarker 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
startnumber0在 title 中插入标记的起始位置下标,有效区间为 [0, 标题长度],小于 0 时会被重置成 0、大于标题长度时会被重置成标题长度2.65.0
hashtagstring''该 hashtagMarker 提醒的人,表现为 #xxx2.65.0

stickersConfig 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
textTextSticker[][]视频上的文字贴图,数据结构为 TextSticker 组成的数组,详情参考 TextSticker 类型说明2.65.0
hashtagHashtagSticker[][]视频上的话题贴图,数据结构为 HashtagSticker 组成的数组,详情参考 HashtagSticker 类型说明2.65.0
mentionMentionSticker[][]视频上的提醒贴图,数据结构为 MentionSticker 组成的数组,详情参考 MentionSticker 类型说明2.65.0
customCustomSticker[][]视频上的自定义贴图, 数据结构为 CustomSticker 组成的数组,详情参考 CustomSticker 类型说明2.65.0

TextSticker 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
textstring文字贴图的文本2.65.0
colorstring'#ffffff'16 进制 hex 格式的颜色,如 #ffffff2.65.0
fontSizenumber28贴图字体大小,单位为像素2.65.0
scalenumber1贴图放大倍率,最小值是 0,精度为 2 位小数2.65.0
xnumber0.5贴图中心点的横坐标位置,0 表示在屏幕最左边,1 表示在屏幕最右边,默认为 0.5 表示水平居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.52.65.0
ynumber0.5贴图中心点的纵坐标位置,0 表示在屏幕最上边,1 表示在屏幕最下边,默认为 0.5 表示垂直居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.52.65.0

HashtagSticker 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
namestring话题名称,话题不能带空格2.65.0
xnumber0.5贴图中心点的横坐标位置,0 表示在屏幕最左边,1 表示在屏幕最右边,默认为 0.5 表示水平居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.52.65.0
ynumber0.5贴图中心点的纵坐标位置,0 表示在屏幕最上边,1 表示在屏幕最下边,默认为 0.5 表示垂直居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.52.65.0

MentionSticker 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
openIdstring提醒的人2.65.0

CustomSticker 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
pathstring自定义贴图路径,只支持 ttfile 格式(可通过如 tt.chooseImage 等 API 获取),暂不支持网络图片资源2.65.0
scalenumber1贴图放大倍率,最小值是 0,精度为 2 位小数2.65.0
rotatenumber0贴图旋转角度,正数代表顺时针旋转,负数代表逆时针旋转(如 90 表示顺时针旋转 90 度)2.65.0
xnumber0.5贴图中心点的横坐标位置,0 表示在屏幕最左边,1 表示在屏幕最右边,默认为 0.5 表示水平居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.52.65.0
ynumber0.5贴图中心点的纵坐标位置,0 表示在屏幕最上边,1 表示在屏幕最下边,默认为 0.5 表示垂直居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.52.65.0

Extra 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
anchorAnchor锚点配置,详情参考 Anchor 类型说明2.65.0

Anchor 类型说明(todo)

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
anchorType"none" | "app""none"挂载锚点的类型,"none" 表示不挂载,"app" 表示将小程序锚点挂载到发布的抖音视频上,暂不开放挂载其他场景的能力。挂载小程序需要申请挂载权限2.65.0
titlestring小程序名称挂载锚点的文案,为空时展示小程序名称2.65.0
pathstring小程序首页点击锚点时打开小程序的页面。是相对路径,相对于小程序根目录,如 page/about/about,默认是小程序首页2.65.0

完整结构示例

const uploadParamsDemo = {
  videoPath: "ttfile://xxx",
  titleConfig: {
    title: "视频标题",
    mentionMarkers: [
      {
        start: 0,
        openId: "标题里要 @ 的人",
      },
    ],
    hashtagMarkers: [
      {
        start: 0,
        hashtag: "标题里要 # 的话题",
      },
    ],
  },
  stickersConfig: {
    text: [
      {
        text: "这是文字贴图",
        color: "#ffffff",
        fontSize: 28,
        scale: 1,
        x: 0.5,
        y: 0.5,
      },
    ],
    hashtag: [
      {
        name: "这是话题贴图",
        x: 0.5,
        y: 0.5,
      },
    ],
    mention: [
      {
        openId: "这是 @ 贴图",
      },
    ],
    custom: [
      {
        path: "ttfile://xxx",
        scale: 1,
        rotate: 0,
        x: 0.5,
        y: 0.5,
      },
    ],
  },
  extra: {
    anchor: {
      anchorType: "app",
      title: "挂载锚点的标题",
      path: "page/about/about",
    },
  },
  success: function (res) {
    console.log("success: ", res);
  },
  fail: function (res) {
    console.log("fail: ", res);
  },
  complete: function (res) {
    console.log("complete: ", res);
  },
};

发布成功回调

如果返回的 uploadParams 中有 success 回调函数,那么在发布视频成功后会触发该成功回调。回调函数携带参数,为 object 类型,属性如下:

属性名类型说明最低支持版本
videoIdstring如果发布成功且成功挂载锚点,则返回 videoId,此 id 与发布的抖音视频存在一一对应的映射关系,能通过 openAPI 换取抖音视频,也能通过 tt.navigateToVideoView API 跳转到该视频页面2.65.0
errMsgstring"uploadDouyinVideo:ok"2.65.0

发布失败回调

如果返回的 uploadParams 中有 fail 回调函数,那么在发布视频失败后会触发该失败回调。回调函数携带参数,为 object 类型,属性如下:

属性名类型说明最低支持版本
errNonumber错误码2.65.0
errMsgstring"uploadDouyinVideo:fail" + 详细错误信息2.65.0

发布完成回调

如果返回的 uploadParams 中有 complete 回调函数,那么无论发布视频成功与否,都会触发该回调。回调函数携带的参数根据发布情况略有不同:

  1. 当发布成功时,与 “发布成功回调” 里的回调参数一致
  2. 当发布失败时,与 “发布失败回调” 里的回调参数一致

代码示例

<!-- index.ttml -->
<button bindtap="chooseVideo">chooseVideo</button>
<button open-type="uploadDouyinVideo" id="1" data-hello="world">
  uploadDouyinVideo
</button>
Page({
  data: {
    videoPath: "",
  },
  // onUploadDouyinVideo 和 onLoad 等其他钩子同级
  onUploadDouyinVideo(uploadOptions) {
    // 通过 uploadOptions 可以拿到 button target 上的一些信息
    // 如这里的 demo 可以拿到 id: 1,hello: world
    console.log("onUploadDouyinVideoOptions: ", uploadOptions);

    // 返回值(文档中称之为 uploadParams)将被当作发布参数传入视频发布器,发布视频
    return {
      videoPath: this.data.videoPath,
      stickersConfig: {
        text: [
          {
            text: "这是文字贴图",
            color: "#ffffff",
            fontSize: 28,
            scale: 1,
            x: 0.5,
            y: 0.5,
          },
        ],
      },
      success: function (callback) {
        // 只有当发布成功且挂载成功时,success callback 才会有 videoId
        console.log("success: ", callback);
      },
      fail: function (callback) {
        console.log("fail: ", callback);
      },
      complete: function (callback) {
        console.log("complete: ", callback);
      },
    };
  },
  chooseVideo() {
    tt.chooseVideo({
      sourceType: ["album", "camera"],
      compressed: true,
      success: (res) => {
        this.setData({
          videoPath: res.tempFilePath,
        });
      },
      fail: (err) => {
        let errType = err.errMsg.includes("chooseVideo:fail cancel")
          ? "取消选择"
          : "选择失败";
        tt.showModal({
          title: errType,
          content: err.errMsg,
          showCancel: false,
        });
      },
    });
  },
});

Bug & Tip

  • Tip:titleConfig.mentionMarkers + stickersConfig.mention 总数不能超过 5 个,超过 5 个将会截取前 5 个 mention;
  • Tip:titleConfig.hashtagMarkers + stickersConfig.hashtag 总数不能超过 5 个,超过 5 个将会截取前 5 个 hashtag。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助