发布抖音视频

收藏
我的收藏
基础库 2.65.0 开始支持该能力。IDE 和非抖音宿主暂不支持此功能,请在抖音上调试。​
警告
此文档将逐步废弃,后续不再维护,请参考转发和挂载概述进行接入。 ​

流程说明​

发布抖音视频主要有两步:​
    1.在页面的逻辑文件(.js)中注册 onUploadDouyinVideo 钩子。​
    2.在页面的视图文件(.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

完整结构示例​

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 回调函数,那么无论发布视频成功与否,都会触发该回调。回调函数携带的参数根据发布情况略有不同:​
    1.当发布成功时,与 “发布成功回调” 里的回调参数一致。
    2.当发布失败时,与 “发布失败回调” 里的回调参数一致。

代码示例​

<!-- index.ttml --> <button open-type="uploadDouyinVideo" id="1" data-hello="world"> uploadDouyinVideo </button>
// 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(""); }, }); }); }, });

Bug & Tip​

    Tip:titleConfig.mentionMarkers + stickersConfig.mention 总数不能超过 5 个,超过 5 个将会截取前 5 个 mention;​
    Tip:titleConfig.hashtagMarkers + stickersConfig.hashtag 总数不能超过 5 个,超过 5 个将会截取前 5 个 hashtag。​