UploadParam__抖音开放平台

UploadParam 是开发者在 Page.onUploadDouyinVideo 钩子中返回的值，该返回值会作为上传参数，最终传递给发布器（注：uploadParam 支持众多抖音视频配置，数据结构较为复杂，可参考下文结构示例与代码辅助理解。如无特殊需求也可以只返回 videoPath，不使用任何特殊能力）。开发者可以根据约定传入部分自定义数据，属性如下：

属性	类型	默认值	是否必填	说明	最低支持版本
videoPath	string		否	•基础库 3.2.0 开始，未填时，代表拉起拍摄器拍摄； •设置了此属性，代表要发布的视频路径，只支持 ttfile 格式（可通过如 tt.chooseVideo 等 API 获取），暂不支持网络视频资源。	2.65.0
titleConfig	TitleConfig		否	TitleConfig 类型说明	2.65.0
stickersConfig	StickersConfig		否	stickersConfig 类型说明	2.65.0
taskIds	string[]		否	拍抖音任务 id 列表，用户完成拍抖音后，会在success回调内返回当前用户的对应任务完成信息	3.2.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 类型说明	2.65.0
hashtagMarkers	HashtagMarker[]	[]	否	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 类型说明	2.65.0
hashtag	HashtagSticker[]	[]	否	HashtagSticker 类型说明	2.65.0
mention	MentionSticker[]	[]	否	MentionSticker 类型说明	2.65.0
custom	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
createChallenge	boolean	false	否	是否分享为挑战视频 ( 仅头条支持 )	3.2.0
videoTag	string		否	分享视频的标签，可以结合获取抖音视频排行榜使用	3.2.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

完整结构示例

JavaScript复制
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);
  },
};

发布成功回调

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

属性名	类型	说明	最低支持版本
videoId	string	如果发布成功且成功挂载锚点，则返回 videoId，此 id 与发布的抖音视频存在一一对应的映射关系，能通过 OpenAPI 换取抖音视频，也能通过 button(open-type=navigateToVideoView) 组件跳转到该视频页面	2.65.0
taskResult	TaskResult[]	当前用户的拍抖音任务结果，当 UploadParam 有传入 taskIds 才会返回	3.2.0
type	string	目前支持video 和 image ，代表当前展示的是视频还是图文，仅在拍抖音场景下返回	3.2.0
errMsg	string	"uploadDouyinVideo:ok"	2.65.0

TaskResult

属性名	类型	说明	最低支持版本
taskId	string	任务id	3.2.0
completed	boolean	当前用户在该任务的状态，true代表已全部完成，false代表未完成	3.2.0
successCount	number	当前用户在该任务的进度	3.2.0
increaseCount	number	本次拍抖音带来的任务完成人数的进度更新	3.2.0
isValid	boolean	任务是否还在有效期	3.2.0
errNo	number	错误码	3.2.0
errMsg	string	错误信息	3.2.0

发布失败回调

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

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

发布完成回调

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

1.

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

2.

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

代码示例

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

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

    // 可以利用异步能力配合其他 API 获取必要的字段信息
    const videoPath = await this.chooseVideo();
    console.log("videoPath:", videoPath);
    // 返回值（文档中称之为 UploadParam）将被当作发布参数传入视频发布器，发布视频
    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("");
        },
      });
    });
  },
});

Bug & Tip

•

Tip：titleConfig.mentionMarkers + stickersConfig.mention 总数不能超过 5 个，超过 5 个将会截取前 5 个 mention；

•

Tip：titleConfig.hashtagMarkers + stickersConfig.hashtag 总数不能超过 5 个，超过 5 个将会截取前 5 个 hashtag。

开发者平台

UploadParam
收藏
我的收藏

TitleConfig 类型说明

MentionMarker 类型说明

HashtagMarker 类型说明

stickersConfig 类型说明

TextSticker 类型说明

HashtagSticker 类型说明

MentionSticker 类型说明

CustomSticker 类型说明

Extra 类型说明

Anchor 类型说明

完整结构示例

发布成功回调

TaskResult

发布失败回调

发布完成回调

代码示例

Bug & Tip

UploadParam收藏我的收藏

​TitleConfig 类型说明 ​

​MentionMarker 类型说明 ​

​HashtagMarker 类型说明 ​

​stickersConfig 类型说明 ​

​TextSticker 类型说明 ​

​HashtagSticker 类型说明 ​

​MentionSticker 类型说明 ​

​CustomSticker 类型说明 ​

​Extra 类型说明 ​

​Anchor 类型说明 ​

​完整结构示例 ​

​发布成功回调 ​

​TaskResult ​

​发布失败回调 ​

​发布完成回调 ​

​代码示例 ​

​Bug & Tip ​

​​

UploadParam
收藏
我的收藏

TitleConfig 类型说明

MentionMarker 类型说明

HashtagMarker 类型说明

stickersConfig 类型说明

TextSticker 类型说明

HashtagSticker 类型说明

MentionSticker 类型说明

CustomSticker 类型说明

Extra 类型说明

Anchor 类型说明

完整结构示例

发布成功回调

TaskResult

发布失败回调

发布完成回调

代码示例

Bug & Tip