抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 基础
  • 渲染
  • 媒体
  • 图片
  • tt.chooseImage
  • tt.saveImageToPhotosAlbum
  • tt.previewImage
  • tt.getImageInfo
  • tt.compressImage
  • 音频
  • Canvas 录制
  • 数据缓存
  • TTML
  • 数据分析
  • 页面导航
  • 设备
  • 画布
  • 界面
  • 直播开放能力
  • tt.chooseImage
    收藏
    我的收藏

    基础库 3.41.0 开始支持本方法,这是一个异步方法。
    从系统相册中选择图片,或使用相机拍摄图片,选取成功后将存入本地临时文件,并在 success 回调中返回相应路径列表。该 API 需要用户授权方可调用,详细信息可参考用户授权。
    前提条件
    无
    业务背景
    无
    使用限制
    无
    注意事项
      •Android 上所选图片总大小不能超过 180M;
      •Android 上使用相机拍摄图片,所返回的拍摄图片默认为压缩图,暂不支持原图;
      •手动取消也会触发失败回调,回调参数为 chooseImage:fail cancel,可以通过判断详细错误信息区分取消和其他错误。
    支持沙盒
    否
    ​
    相关教程
    无
    ​

    语法

    tt.chooseImage(options)

    参数说明

    options 为 object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    count
    number
    9
    否
    最多可以选择的图片数量,拍照时此选项无效
    3.41.0
    sourceType
    array
    ["album", "camera"]
    否
    指定图片来源,详情见 sourceType参数说明
    3.41.0
    sizeType
    array
    ["original", "compressed"]
    否
    是否选择原图,详情见 sizeType参数说明
    3.41.0
    success
    function
    ​
    否
    接口调用成功的回调函数
    3.41.0
    fail
    function
    ​
    否
    接口调用失败的回调函数
    3.41.0
    complete
    function
    ​
    否
    接口调用结束的回调函数(调用成功、失败都会执行)
    3.41.0
    ​

    sourceType 参数说明

    值
    说明
    最低支持版本
    ['album']
    从相册选择
    3.41.0
    ['camera']
    使用相机拍摄
    3.41.0
    ['album', 'camera']
    既可以从相册选择图片,也可以使用相机拍摄图片
    3.41.0
    ​

    sizeType 参数说明

    值
    说明
    最低支持版本
    ['original']
    使用原图,显示并默认勾选原图按钮
    3.41.0
    ['compressed']
    使用压缩图,不显示原图按钮
    3.41.0
    ['original', 'compressed']
    提供原图按钮,可自由选择是否使用原图
    3.41.0
    ​

    回调成功

    object 类型,属性如下:
    属性名
    类型
    说明
    最低支持版本
    errMsg
    string
    "chooseImage:ok"
    3.41.0
    tempFiles
    array
    图片对象数组,TempFile 是图片对象
    3.41.0
    tempFilePaths
    array
    图片的本地文件路径列表
    3.41.0

    tempFiles 类型说明

    object 类型,属性如下:
    属性名
    类型
    说明
    最低支持版本
    path
    string
    本地文件路径
    3.41.0
    size
    number
    本地文件大小,以字节为单位
    3.41.0
    ​

    回调失败

    object 类型,属性如下:
    属性名
    类型
    说明
    最低支持版本
    errMsg
    string
    "chooseImage:fail" + 详细错误信息
    3.41.0
    ​

    错误码

    errorCode
    errMsg
    errorType
    说明
    最低支持版本
    111887
    feature is not supported in app
    D
    没有实现协议时
    3.41.0
    111888
    param:data illegal
    U
    图像服务返回数据为空
    3.41.0
    111880
    privacy permission is not authorized
    U
    用户拒绝隐私协议
    3.41.0
    111895
    cancel
    U
    在出现“拍照”、“相册选择”、“取消”这个选择列表时选择“取消”用户取消选择/拍摄图片
    3.41.0
    111891
    Internal error
    F
    小程序框架内部错误,有需要请拉客服咨询
    3.41.0
    111891
    Internal error: %sInternal error: %sInternal error: internal auth error
    F
    小程序框架内部错误,有需要请拉客服咨询
    3.41.0
    111892
    native exception $throwable stack:${StackUtil.getStackInfoFromThrowable(throwable, 0, 1)}
    F
    小程序框架内部错误,有需要请拉客服咨询
    3.41.0
    111883
    invalid scope
    D
    传入的 scope 未注册
    3.41.0
    111879
    api scope is not declared in the privacy agreement
    D
    开启校验且当前 scope 在后台未配置的情况下
    3.41.0
    111889
    system auth deny
    U
    用户在系统的权限申请弹窗上点击拒绝
    3.41.0
    111890
    auth deny
    U
    用户在小程序半屏授权弹窗上点击“拒绝”或在小程序设置中关闭了摄像头、相册权限
    3.41.0
    ​

    扫码体验

    请使用字节宿主APP扫码

    代码示例

    <!-- index.ttml --> <button type="primary" bindtap="chooseImage">选择图片</button> <view tt:if="{{imageList.length > 0}}"> <view tt:for="{{imageList}}"> <view>第 {{index + 1}} 张图片,图片 size:{{item.size}}</view> <image src="{{item.path}}" /> </view> </view>
    // index.js Page({ data: { images: [], }, chooseImage() { tt.chooseImage({ count: 3, success: (res) => { tt.showToast({ title: "选择成功" }); console.log("chooseImage 返回结果:", res); this.setData({ imageList: res.tempFiles, }); }, fail(err) { let errType = err.errMsg.includes("chooseImage:fail cancel") ? "取消选择" : "选择失败"; tt.showModal({ title: errType, content: err.errMsg, showCancel: false, }); }, complete() { console.log("完成选择"); }, }); }, });

    Bug & Tip

      •Tip:Android 上所选图片总大小不能超过 180M;
      •Tip:Android 上使用相机拍摄图片,所返回的拍摄图片默认为压缩图,暂不支持原图;
      •Tip:手动取消也会触发失败回调,回调参数为 chooseImage:fail cancel,可以通过判断详细错误信息区分取消和其他错误。