# 文件

# 文件选择器 v4.1.0

# 使用说明

Android	iOS	PC	是否需要鉴权
支持	支持	支持	不需要

# 参数说明

参数	参数类型	必传	说明
multiple	Boolean	否	pc 端是否多选，默认为 false。移动端不需要
imageOpt	Object	否	选择图片
imageOpt[max]	Number	否	最大数量
videoOpt	Object	否	选择视频
videoOpt[max]	Number	否	最大数量
videoOpt[duration]	Number	否	视频最大时长，单位(秒)
typeOnly	Boolean	否	是否支持混选，默认为 false(可以混选)

# 返回说明

若选择取消，则返回-1

参数	参数类型	说明
files	Array	选择文件列表
files.item	Object	文件对象
files.item[path]	String	文件上传路径
files.item[sourcePath]	String	pc 端文件原路径，移动端无此返回
files.item[showPath]	String	pc 端文件展示路径，移动端无此返回
files.item[width]	Number	文件宽度
files.item[height]	Number	文件高度
files.item[duration]	Number	视频时长

// 全量引入调用方式
yy.biz.util.openMediaFileDialog({
  multiple: true,
  imageOpt: {
    max: 9
  },
  videoOpt: {
    max: 1,
    duration: 30
  },
  typeOnly: true,
  onSuccess: function (result) {
    /*
      [{
        path: "..."
        width: 100
        height: 100
        duration: 20
      }]
    */
  },
  // 未按条件选择，也会返回所选文件并回调onFail
  onFail: function (result) {
    /*
      [{
        path: "..."
        width: 100
        height: 100
        duration: 20
      }]
    */
  },
});

// 按需加载调用方式，参数与全量引入相同
openMediaFileDialog({...});

# 调试

biz.util.openMediaFileDialog

# 文件选择器V2 (支持原图和视频异步返回)v4.4.7

# 使用说明

Android	iOS	PC	是否需要鉴权
支持v1.9.13	支持v1.9.13	不支持	需要

# 参数说明

参数	参数类型	必传	说明
columnNumber	Number	否	每一行展示几个图片和视频，默认4个
imageOpt	Object	否	选择图片
imageOpt[max]	Number	否	最大数量
videoOpt	Object	否	选择视频
videoOpt[max]	Number	否	最大数量
typeOnly	Boolean	否	是否支持混选，默认为false(可以混选)

# 返回说明

结果分两次回调，先回调缩略图的base64占位，再异步返回原图或者视频的本地路径，此方法在导出图片和视频时不会有loading阻塞交互。通过sendMsgCommon全局方法回调结果

返回缩略图示例 { type = "mediaFetchThumbImage"; value = ( { localIdentifier = "80D8318C-6930-41DE-AE99-19E8E3869643/L0/001"; thumbImage = "data:image/jpeg;base64,xxxxxxx"; }, { localIdentifier = "4FD29341-EC91-475B-80EE-0F7374AFD7B5/L0/001"; thumbImage = "data:image/jpeg;base64,xxxxxxx"; } ); }
返回原图和视频示例，每个图片和视频分别多次单独返回 { type = "mediaFetchSource"; value = { path = "/var/mobile/Containers/Data/Application/3D8E5A9B-E54E-4034-97E2-292D4B773A4C/Library/Caches/tmp/171745072025-08-01-15-21-03-425.jpg"; localIdentifier = "80D8318C-6930-41DE-AE99-19E8E3869643/L0/001"; width = 1242; height = 2208; duration = 0; }; } h5在第一步拿到缩略图列表后，新建对象存储图片和localIdentifier，第二步收到图片和视频导出成功的回调之后，把localIdentifier字段与第一步里的做映射，再把本地路径和其他信息绑定。

// 全量引入调用方式
yy.biz.util.openMediaFileDialogV2({
  columnNumber: 4,
  imageOpt: {
    max: 9
  },
  videoOpt: {
    max: 1,
  },
  typeOnly: true,
  onSuccess: function (result) {
    /*
      [{
        path: "..."
        width: 100
        height: 100
        duration: 20
      }]
    */
  },
  // 未按条件选择，也会返回所选文件并回调onFail
  onFail: function (result) {
    /*
      [{
        path: "..."
        width: 100
        height: 100
        duration: 20
      }]
    */
  },
});

// 按需加载调用方式，参数与全量引入相同
openMediaFileDialogV2({...});

# 调试

biz.util.openMediaFileDialogV2

# 上传媒体文件 v4.1.0

# 使用说明

Android	iOS	PC	是否需要鉴权
支持	支持	支持	需要

# 参数说明

参数	参数类型	必传	说明
files	Array	是	上传文件列表
files.item	String	是	文件路径

# 返回说明

上传失败，则返回-1

参数	参数类型	说明
list	Array	上传文件列表
list.item	Object	文件对象
list.item[fileId]	String	文件 id，仅 pc 端返回
list.item[filePath]	String	文件链接地址
list.item[fileName]	String	文件名
list.item[sourcePath]	String	文件本地地址
list.item[relation_id]	String	视频文件转码 id，视频播放时使用；图片预览时使用
list.item[videoPic]	String	视频首帧截图链接地址

// 全量引入调用方式
yy.biz.util.mediaFileUpload({
  files: ['xxx.jpg', 'xxx.mp4'],
  onSuccess: function (result) {
    /*
      [{
        fileId: 1
        filePath: "..."
        fileName: "..."
        sourcePath: "..."
        relation_id: "111111"
        videoPic: "..."
      }]
    */
  },
  onProgress: function (result) {
    /*
      [{
        fileId: 1
        sourcePath: "..."
        processdata: {
          loaded: 10000,
          total: 10000,
          speed: 5000,
          percent: 0
        }
      }]
    */
  }
  onFail: function () {},
});

// 按需加载调用方式，参数与全量引入相同
mediaFileUpload({...});

# 调试

biz.util.openMediaFileDialog, biz.util.mediaFileUpload

# 上传媒体文件V2 v4.4.7

# 使用说明

Android	iOS	PC	是否需要鉴权
支持v1.9.13	支持v1.9.13	不支持	不需要

# 参数说明

参数	参数类型	必传	说明
files	Array	是	上传文件列表
files.item	String	是	文件路径
cancel	Number	否	取消上传时为1

cancel:1 取值1时候把files里面对应的文件取消上传

# 返回说明

调用sendMsgCommon发送文件上传进度回调 type："fileUpload" value: [ { filePath:"文件url,上传成功后这个字段有值，没成功之前可以不回调", fileName:"文件名,上传成功后这个字段有值，没成功之前可以不回调", relation_id:"文件关系id,上传成功后这个字段有值，没成功之前可以不回调", videoPic:"视频封面,上传成功后这个字段有值，没成功之前可以不回调", sourcePath:"文件本地路径，必有值", progress:"0.12" 代表当前上传进度，保留小数点后两位 } ]

// 全量引入调用方式
yy.biz.util.mediaFileUploadV2({
  files: ['xxx.jpg', 'xxx.mp4'],
  onSuccess: function (result) {
    /*
      [{
        fileId: 1
        filePath: "..."
        fileName: "..."
        sourcePath: "..."
        relation_id: "111111"
        videoPic: "..."
      }]
    */
  },
  onProgress: function (result) {
    /*
      [{
        fileId: 1
        sourcePath: "..."
        processdata: {
          loaded: 10000,
          total: 10000,
          speed: 5000,
          percent: 0
        }
      }]
    */
  }
  onFail: function () {},
});

// 按需加载调用方式，参数与全量引入相同
mediaFileUploadV2({...});

# 调试

biz.util.mediaFileUploadV2, biz.util.mediaFileUpload

# 上传文件

# 使用说明

Android	iOS	PC	是否需要鉴权
支持	支持	支持	不需要

# 参数说明

参数	参数类型	必传	说明
multiple	Boolean	否	pc 端是否多选，默认为 false。仅支持 pc 端
image	Object	否	仅支持移动端
image[multiple]	Boolean	否	是否多选，默认为 false，仅支持移动端
image[compress]	Boolean	否	是否压缩，默认为 true，仅支持移动端
image[max]	Number	否	最多选择的图片数目，最多支持 9 张，仅支持移动端
file	Object	否	仅支持移动端
file[max]	Number	否	最多选择的文件数目，最多支持 9 个，仅支持移动端
types	Array<'photo' \| 'camera' \| 'file'>	否	支持上传附件的文件类型, 移动端必传，pc 端 types 与 suffix 至少传入其中一个
suffix	string[]	否	支持传入指定后缀名的文件，types 与 suffix 至少传入其中一个，仅支持 PC 端
costype	number	否	目前仅 pc 支持 1:上传到公有桶，0:上传到私有桶；默认上传到公有桶应使用 0 上传到私有桶，1 为兼容已接入的应用，等接入方修改为上传到私有桶后关闭该参数
maxNum	number	否	上传文件最大数量限制，仅支持 PC 端，知音楼版本 >= 1.7.1.10
endUploadOvernumber	boolean	否	超出最大数量限制后是否结束上传，默认为 false 不结束上传，上传到最大限制的数量，仅支持 PC 端，知音楼版本 >= 1.7.1.10
maxSize	number	否	上传单个文件大小限制，仅支持 PC 端，知音楼版本 >= 1.7.1.10
endUploadHasOversize	boolean	否	文件中存在超出大小限制文件时是否结束上传，默认为 false 不结束上传，上传不超出大小限制的文件，仅支持 PC 端，知音楼版本 >= 1.7.1.10

# 返回说明

若上传取消，则返回-1

参数	参数类型	说明
count	Number	上传文件数量
data	Object	上传返回内容
data[fileUrl]	String	文件地址
data[fileId]	String	文件 id
data[fileName]	String	文件名称
data[fileSize]	String	文件大小
data[fileType]	String	文件类型
data[relationId]	String	文件关联 id
ext	Object	额外信息
ext[width]	Number	图片宽度
ext[height]	Number	图片高度

新增上传失败返回说明，仅适用于知音楼版本 >= 1.7.1.10，低版本返回错误信息格式不做兼容

参数	参数类型	说明
data	Object	上传错误返回内容
data[type]	String	错误类型
data[msg]	String	错误描述
data[file]	String、String[]、undefined	出错文件

// 全量引入调用方式
yy.biz.util.uploadAttachment({
  image: {
    multiple: true,
    compress: false,
    max: 9,
  },
  file: {
    multiple: true,
    compress: false,
    max: 30,
  },
  types: ["photo", "file"],
  costype: 0,
  onSuccess: function (result) {
    /*
      true
    */
  },
  onFail: function () {},
});

// 按需加载调用方式，参数与全量引入相同
uploadAttachment({...});

# 调试

biz.util.uploadAttachment

# 上传剪贴板内文件 v1.1.3

# 使用说明

Android	iOS	PC	是否需要鉴权
不支持	不支持	支持	不需要

# 返回说明

无

// 全量引入调用方式
yy.biz.util.clipboardFileUpload({
  onSuccess: function (result) {
    /*
      true
    */
  },
  onFail: function () {},
});

// 按需加载调用方式，参数与全量引入相同
clipboardFileUpload({...});

# 调试

biz.util.clipboardFileUpload

# 下载文件

# 使用说明

Android	iOS	PC	是否需要鉴权
不支持	不支持	支持	不需要

# 参数说明

参数	参数类型	必传	说明
url	string	是	要下载的文件的 url
name	string	否	定义下载文件名字

# 返回说明

无

// 全量引入调用方式
yy.biz.util.downloadFile({
  url:
    "https://yach-xstatic.zhiyinlou.com/test/jsapi/1603681258482/zf6zqwow1l/b544faad-b48b-4bc6-bfce-35c326c4e225.doc", //要下载的文件的url
  name: "test.doc", //定义下载文件名字
  onProgress: function (msg) {
    // 文件下载进度回调
  },
  onSuccess: function (result) {
    /*
          true
        */
  },
  onFail: function () {},
});

// 按需加载调用方式，参数与全量引入相同
downloadFile({...});

# 调试

biz.util.downloadFile

# 文件预览

支持 PDF、office 文件预览，不支持的文件类型提示下载，目前仅支持https://yach-static.zhiyinlou.com、https://yach-xstatic.zhiyinlou.com下的资源预览
视频预览使用 biz.util.openVideoPlaye，图片预览使用 biz.util.previewImage

# 使用说明

Android	iOS	PC	是否需要鉴权
支持	支持	支持 v3.1.0	不需要

# 参数说明

参数	参数类型	必传	说明
type	string	否	文件类型，`4.0.10` 开始废弃该参数，可兼容使用低版本传入的情况
relationId	string	否	1.relationId 可从上传文件接口`biz.util.uploadAttachment`的返回值中获取，腾讯云返回 2.用于获取文件信息，使用 wps 还是使用 Microsoft 打开 3.私有文件通过该参数获取信息
file	string	是	要下载的文件的 url，公有文件直接使用该参数进行预览
size	string	否	定义下载文件大小
name	string	否	定义下载文件名字

# 返回说明

无

// 全量引入调用方式
yy.biz.util.previewFile({
    file: '文件url',
    size: '文件大小',
  	name：'文件名'
    onSuccess : function(result) {
    },
    onFail : function() {}
})

// 按需加载调用方式，参数与全量引入相同
previewFile({...});

# 调试

biz.util.previewFile

# 外链文件预览 v4.1.3

支持 PDF、office 文件预览，不支持的文件类型提示下载

# 使用说明

Android	iOS	PC	是否需要鉴权
支持	支持	支持	不需要

# 参数说明

参数	参数类型	必传	说明
file	string	是	文件 url 地址

# 返回说明

无

// 全量引入调用方式
yy.biz.util.externalLinkPreviewFile({
    file: '文件url',
    onSuccess : function(result) {
    },
    onFail : function() {}
})

// 按需加载调用方式，参数与全量引入相同
externalLinkPreviewFile({...});

# 调试

biz.util.externalLinkPreviewFile

# 图片预览

# 使用说明

调用此 api，将进行预览图片。

Android	iOS	PC	是否需要鉴权
支持	支持	支持	不需要

// 全量引入调用方式
yy.biz.util.previewImage({
  // 移动端和 pc 端（<=1.4.8.24）参数
  urls: [String], //图片地址列表
  current: String, //当前显示的图片链接

  // pc 端（>1.4.8.24）参数
  "data":[{
      "name":"test1",
      "url":"https://yach-static.zhiyinlou.com/test/jsapi/1601360525953/61htm29cdxr/94f58246-f9a6-4859-bf3f-e29e59e5df9c.png",
      "width": 1210,
      "height": 563,
      "id":"120832398568091664",
      "curr":false
    }, {
      "name":"test2",
      "url":"https://yach-static.zhiyinlou.com/test/jsapi/1601360569936/whazs9rnrak/76548db5-fa84-4def-b05a-afb58f270963.png",
      "width": 317,
      "height": 355,
      "id":"120832398568091666",
      "curr":false
    }, {
      "name":"test2",
      "url":"https://yach-static.zhiyinlou.com/test/jsapi/1601360616899/2u3g06idwpi/f87cf929-0418-4e11-af9f-b8d647c623d2.png",
      "width": 270,
      "height": 443,
      "id":"120832398568091668",
      "curr":false
    }, {
      "name":"test2",
      "url":"https://yach-static.zhiyinlou.com/test/jsapi/1601360727298/wotvlzbdf2/d191cb4f-31d9-43b8-a50c-51842a5af609.png",
      "width": 1919,
      "height": 1037,
      "id":"120832398568091672",
      "curr":true
    }],
  "id":"120832398568091672",
  onSuccess: function (result) {
    /**/
  },
  onFail: function (err) {}
});

// 按需加载调用方式，参数与全量引入相同
previewImage({...});

# 参数说明

移动端和 pc 端（<=1.4.8.24）参数说明

参数	参数类型	必传	说明
urls	Array[String]	是	图片地址列表
current	String	否	当前显示的图片链接
longPressOptions	Array[String]	否	可配置的内容： Send：发送给联系人 Save：保存到手机 Qrcode：识别二维码 Editor：编辑例如：{"longPressOptions":["Send","Qrcode"]}，如果不传默认同时配置上面四个选项。

pc 端（>1.4.8.24）参数说明

参数	参数类型	说明
data	Array[img]	图片数据
img[name]	String	图片名称
img[id]	String	图片 id (`biz.util.mediaFileUpload` 中返回的 relation_id)
img[url]	String	图片地址
img[width]	number	图片宽度
img[height]	number	图片高度
img[curr]	boolean	是否为当前图片
id	string	当前图片的 id

# 返回说明

无

# 调试

biz.util.previewImage

# 音频预览

# 使用说明

调用此 api，将进行预览音频。

Android	iOS	PC	是否需要鉴权
支持v1.9.13	支持v1.9.13	支持v1.9.13	否

// 全量引入调用方式
yy.biz.util.openAudioPlayer({
  url: String, // 视频地址列表
  relationId: String,
  name: String,
  size: Number,
  onSuccess: function (result) {
    /**/
  },
  onFail: function (err) {}
});

// 按需加载调用方式，参数与全量引入相同
openAudioPlayer({...});

# 参数说明

参数	参数类型	必传	说明
url	String	是	1.移动端和桌面端均支持该字段
name	String	是	音频名称
size	Number	是	音频大小
relationId	String	否	腾讯云所返回，可根据 relationId 获取到音频资源

# 返回说明

无

# 调试

biz.util.openAudioPlayer

# 视频预览

# 使用说明

调用此 api，将进行预览视频。

Android	iOS	PC	是否需要鉴权
支持	支持	支持	不需要

// 全量引入调用方式
yy.biz.util.openVideoPlayer({
  url: String, // 视频地址列表
  relationId: String,
  onSuccess: function (result) {
    /**/
  },
  onFail: function (err) {}
});

// 按需加载调用方式，参数与全量引入相同
openVideoPlayer({...});

# 参数说明

参数	参数类型	必传	说明
url	String	是	1.移动端和桌面端均支持该字段
relationId	String	否	1.腾讯云所返回，可根据 relationId 获取到视频资源 2.移动端和桌面端均支持该字段 3.桌面端必传 4.移动端非必传

# 返回说明

无

# 调试

biz.util.openVideoPlayer

# 保存 base64 图片

# 使用说明

调用此 api，保存 base64 图片。

Android	iOS	PC	是否需要鉴权
支持	支持	不支持	需要

// 全量引入调用方式
yy.biz.util.savePic({
  content：base64,
  onSuccess: function (result) {
    /**/
  },
  onFail: function (err) {}
});

// 按需加载调用方式，参数与全量引入相同
savePic({...});

# 参数说明

参数	参数类型	必传	说明
content	String	是	base64 字符串

# 返回说明

无

# 调试

biz.util.savePic

← 电话业务 →