发布抖音视频

更新时间 2024-07-24 02:58:49

我的收藏

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

警告

此文档将逐步废弃，后续不再维护，请参考转发和挂载概述进行接入。

流程说明

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

在页面的逻辑文件（.js）中注册 onUploadDouyinVideo 钩子。

在页面的视图文件（.ttml）中使用 button 组件，并将组件的 open-type 属性设置成 uploadDouyinVideo。

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

uploadOptions 说明

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

属性名	类型	说明	最低支持版本
target	Target	上传抖音视频按钮的相关信息，包含 id、dataset、offsetTop、offsetLeft，详见 Target 类型说明	2.65.0

Target 类型说明

object 类型，属性如下：

属性名	类型	说明	最低支持版本
id	string	上传抖音视频按钮的 id，即标签上的 `id` 属性	2.65.0
dataset	object	按钮标签上的自定义属性集，即标签上的 `data-xx` 属性	2.65.0
offsetTop	number	按钮元素左上角相对于其 offsetParent 元素的顶部内边距的距离	2.65.0
offsetLeft	number	按钮元素左上角相对于其 offsetParent 元素的左边界的距离	2.65.0

uploadParams 说明

uploadParams 是开发者在 onUploadDouyinVideo 钩子中返回的值，该返回值会作为上传参数，拉起抖音发布器。

注意
uploadParams 支持众多抖音视频配置，数据结构较为复杂，可参考下文结构示例与代码辅助理解。如无特殊需求也可以只返回 videoPath，不使用任何特殊能力。​

uploadParams 是 object 类型，属性如下：

属性名	类型	默认值	必填	说明	最低支持版本
videoPath	string		是	要发布的视频路径，只支持 ttfile 格式（可通过如 tt.chooseVideo 等 API 获取），暂不支持网络视频资源	2.65.0
titleConfig	TitleConfig		否	视频的标题配置，详情参考 TitleConfig 类型说明	2.65.0
stickersConfig	StickersConfig		否	视频的贴图配置，详情参考 StickersConfig 类型说明	2.65.0
extra	Extra		否	挂载锚点等额外信息，详情参考 Extra 类型说明	2.65.0
success	function		否	发布成功的回调函数	2.65.0
fail	function		否	发布失败的回调函数	2.65.0
complete	function		否	发布成功或失败时都会执行的回调函数	2.65.0

TitleConfig 类型说明

object 类型，属性如下：

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

MentionMarker 类型说明

object 类型，属性如下：

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

HashtagMarker 类型说明

object 类型，属性如下：

属性名	类型	默认值	必填	说明	最低支持版本
start	number	0	否	在 title 中插入标记的起始位置下标，有效区间为 `[0, 标题长度]`，小于 0 时会被重置成 0、大于标题长度时会被重置成标题长度	2.65.0
hashtag	string	''	否	该 hashtagMarker 的话题，表现为 #xxx	2.65.0

stickersConfig 类型说明

object 类型，属性如下：

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

TextSticker 类型说明

object 类型，属性如下：

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

HashtagSticker 类型说明

object 类型，属性如下：

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

MentionSticker 类型说明

object 类型，属性如下：

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

CustomSticker 类型说明

object 类型，属性如下：

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

Extra 类型说明

object 类型，属性如下：

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

Anchor 类型说明

object 类型，属性如下：

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

完整结构示例

js复制
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 类型，属性如下：

属性名	类型	说明	最低支持版本
videoId	string	如果发布成功且成功挂载锚点，则返回 videoId，此 id 与发布的抖音视频存在一一对应的映射关系，能通过 OpenAPI 换取抖音视频，也能通过 button(open-type=navigateToVideoView) 组件跳转到该视频页面	2.65.0
errMsg	string	"uploadDouyinVideo:ok"	2.65.0

发布失败回调

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

属性名	类型	说明	最低支持版本
errNo	number	错误码	2.65.0
errMsg	string	"uploadDouyinVideo:fail" ＋详细错误信息	2.65.0

发布完成回调

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

当发布成功时，与 “发布成功回调” 里的回调参数一致。

当发布失败时，与 “发布失败回调” 里的回调参数一致。

代码示例

html复制
<!-- index.ttml --> 
<button open-type="uploadDouyinVideo" id="1" data-hello="world">
  uploadDouyinVideo
</button>

js复制
// index.js 
Page({
  data: {},
  // onUploadDouyinVideo 和 onLoad 等其他钩子同级
  async onUploadDouyinVideo(uploadOptions) {
    // 通过 uploadOptions 可以拿到 button target 上的一些信息
    // 如这里的 demo 可以拿到 id: "1"，hello: "world"
    console.log("onUploadDouyinVideoOptions: ", uploadOptions);

    // 可以利用异步能力配合其他 API 获取必要的字段信息
    const videoPath = await this.chooseVideo();
    console.log("videoPath:", videoPath);
    // 返回值（文档中称之为 uploadParams）将被当作发布参数传入视频发布器，发布视频
    return {
      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() {
    return new Promise((resolve) => {
      tt.chooseVideo({
        sourceType: ["album", "camera"],
        compressed: true,
        success: (res) => {
          resolve(res.tempFilePath);
        },
        fail: (err) => {
          let errType = err.errMsg.includes("chooseVideo:fail cancel")
            ? "取消选择"
            : "选择失败";
          tt.showModal({
            title: errType,
            content: err.errMsg,
            showCancel: false,
          });
          resolve("");
        },
      });
    });
  },
});