抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • JS API 列表
  • 基础
  • TTML
  • 网络
  • 媒体
  • 地图
  • 文件
  • 数据缓存
  • 地理位置
  • 设备
  • 画布
  • 界面
  • 页面导航
  • 开放接口
  • 登录
  • 用户信息
  • 广告
  • 营销能力
  • 支付
  • 分享
  • 小程序跳转
  • 抖音视频能力
  • 发布抖音视频
  • 收货地址
  • 设置
  • 授权
  • 评价能力
  • 数据分析
  • 视频拍摄器
  • 引导关注
  • 订阅消息
  • 电商插件能力(即将废弃)
  • 流量来源识别
  • 隐私信息授权
  • web化
  • 转发和挂载
  • 侧边栏能力
  • 直播能力
  • AI/AR能力
  • 安全能力
  • 行业开放
  • 第三方平台
  • 其它
  • 生活服务(即将废弃)
  • 发布抖音视频

    收藏
    我的收藏
    基础库 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。
    ​