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 ​

完整结构示例

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.当发布失败时,与 “发布失败回调” 里的回调参数一致 ​

代码示例

<!-- index.ttml --> <button open-type="uploadDouyinVideo" id="1" data-hello="world"> uploadDouyinVideo </button>
// 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。​