文件

最近更新时间:2025-09-29 11:21:32

我的收藏

简介

本文档提供关于文件相关接口介绍以及示例代码

文件上传

功能说明

该上传方法内部会自动进行快速上传、简单上传、分块上传的逻辑,生成的 task 可以供外部进行暂停、恢复、取消等。

示例代码

上传
try {
let filePath = "本地文件路径";
// 调用 SMHFileApis 的 uploadObject 方法进行文件上传
let task = SMHFileApis.uploadObject({
spaceId: "spaceId",
libraryId: "libraryId",
body: filePath, // 本地路径
uploadPath: `smh/test.jpg`, // 目标路径
});
task.onStateChange = (state: SMHTransferState) => {
// 任务状态回调
}
task.confirmKeyInitCallback = (confimKey: string) => {
// 上传返回 confirmKey 回调。用于断点续传
}
task.onProgress = (progress) => {
// 进度回调
}
task.onFinish = (result?: object, error?: SMHError) => {
// 完成回调
}
// 启动任务
task.start();

//其他方法
//task.pause() 暂停任务
//task.cancel() 取消任务
//task.resume() 重新启动任务,与 pause 配合使用
}catch (e) {
// 异常处理
}
断点续传
try {
let filePath = "本地文件路径";
// 调用 SMHFileApis 的 uploadObject 方法进行文件上传
let task = SMHFileApis.uploadObject({
spaceId: "spaceId",
libraryId: "libraryId",
body: filePath, // 本地路径
uploadPath: `smh/test.jpg`, // 目标路径
confirmKey:"confirmKey"// confirmKeyInitCallback 回调返回的 confirmKey。
});
task.onStateChange = (state: SMHTransferState) => {
// 任务状态回调
}
task.confirmKeyInitCallback = (confimKey: string) => {
// 上传返回 confirmKey 回调。用于断点续传
}
task.onProgress = (progress) => {
// 进度回调
}
task.onFinish = (result?: object, error?: SMHError) => {
// 完成回调
}
// 启动任务
task.start();

//其他方法
//task.pause() 暂停任务
//task.cancel() 取消任务
//task.resume() 重新启动任务,与 pause 配合使用
}catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
body
待上传的文件,格式为本地文件路径或者 ArrayBuffer
String/ArrayBuffer
uploadPath
目标路径,例如 foo/bar/file.docx
String
confirmKey
确认参数,指定为开始上传文件时响应体中的 confirmKey 字段的值,用于续传
String
simpleUploadLimit
简单上传阈值 默认1m。小于1m则使用简单上传,否则使用分块上传
Number
sliceLength
分块大小:默认1m
Number
conflictResolutionStrategy
文件名冲突时的处理方式:
ask:冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename:冲突时自动重命名文件
overwrite:如果冲突目标为目录时返回 HTTP 409 Conflict 及SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件
SMHConflictResolutionStrategy
customHeader
自定义请求头
Map
trafficLimit
单链接下载限速,范围100KB/s-100MB/s,单位 B
Number
withInode
上传完是否返回 inode,即文件目录 ID
Bool

文件下载

功能说明

该下载方法内部会自动进行下载到本地以及续传的逻辑,生成的 task 可以供外部进行暂停、恢复、取消等。
说明:
下载接口默认支持断点续传,确保写入本地路径不变即可。

示例代码

try {
// 调用 SMHFileApis 的 downloadObject 方法进行文件上传
let task = SMHFileApis.downloadObject({
spaceId: "spaceId",
libraryId: "libraryId",
filePath: `smh/test.jpg`,// 远端路径
savePath: "本地路径" // 本地路径
})
task.onStateChange = (state: SMHTransferState) => {
// 任务状态回调
}
task.onProgress = (progress: HttpProgress) => {
// 进度回调
}
task.onFinish = (result?: object, error?: SMHError) => {
// 完成回调
}
// 启动任务
task.start();
//其他方法
//task.pause() 暂停任务
//task.cancel() 取消任务
//task.resume() 重新启动任务,与 pause 配合使用
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
savePath
保存到本地的路径
String
historyId
历史版本 ID,用于获取不同版本的文件内容
String
trafficLimit
单链接下载限速,范围 100KB/s-100MB/s,单位 B
Number

获取照片/视频封面缩略图

功能说明

用于获取照片/视频封面缩略图。

示例代码

try {
let result = await SMHFileApis.preview({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/image.jpg"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/image.jpg
String
size
缩放大小
String
scale
等比例缩放百分比,不传 Size 时生效
String
widthSize
缩放宽度,不传高度时,高度按等比例缩放,不传 Size 和 Scale 时生效
String
heightSize
缩放高度,不传宽度时,宽度按等比例缩放,不传 Size 和 Scale 时生效
String
frameNumber
帧数,针对 gif 的降帧处理
String

获取文件下载链接和信息

功能说明

用于获取文件下载链接和信息。

示例代码

try {
let result =
await SMHFileApis.downloadInfo({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
historyId
历史版本 ID,用于获取不同版本的文件内容
String
trafficLimit
单链接下载限速,范围 100KB/s-100MB/s,单位 B
Number
contentDisposition
用于设置 Content-Disposition 响应头,支持 inline 或者 attachment
SMHContentDisposition
purpose
用途,可以设置为 download 或者 preview,用于决定是否将该文件加入最近使用文件列表中,如果设置为 preview,则会将该文件加入最近使用文件列表中,否则不会加入
SMHPurpose
pre_check
是否只用于校验文件是否可预览和下载,设置该参数后返回结果中不包含 cosUrl
Bool

删除文件

功能说明

用于删除文件。

示例代码

try {
let result = await SMHFileApis.deleteFile({
libraryId: "TestLibraryId",
spaceId: "TestSpaceId",
filePath: "foo/bar/file.docx",
permanent: true
});
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
permanent
当媒体库开启回收站时,则该参数指定将文件移入回收站还是永久删除文件,true: 永久删除,false: 移入回收站,默认为 false
Bool

复制文件

功能说明

用于复制文件。

示例代码

try {
let result = await SMHFileApis.copyFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file_new.docx",
copyFrom: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file_new.docx
String
copyFrom
被复制的源文件云端路径,例如 foo/bar/file.docx
String
conflictResolutionStrategy
文件名冲突时的处理方式,默认为 rename
ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename: 冲突时自动重命名文件
overwrite: 如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件
SMHConflictResolutionStrategy

重命名或移动文件

功能说明

用于重命名或移动文件。

示例代码

try {
let result = await SMHFileApis.moveFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file_new.docx",
from: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file_new.docx
String
from
被移动的源文件云端路径,例如 foo/bar/file.docx
String
conflictResolutionStrategy
文件名冲突时的处理方式,默认为 rename
ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename: 冲突时自动重命名文件
overwrite: 如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件
SMHConflictResolutionStrategy

更新文件的标签(Labels)或分类(Category)

功能说明

用于更新文件的标签(Labels)或分类(Category)。

示例代码

try {
let result = await SMHFileApis.updateTagAndCategory({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.jpg",
labels: ["大象","动物","亚洲象"],
category: "image",
localCreationTime: "2022-07-26T02:58:09Z",
localModificationTime: "2022-07-26T02:58:09Z",
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
labels
文件标签列表
String 数组
category
文件自定义的分类
String
localCreationTime
文件对应的本地创建时间
String
localModificationTime
文件对应的本地修改时间
String

查看最近使用文件列表

功能说明

用于查看最近使用文件列表。

示例代码

try {
let result = await SMHFileApis.recentlyUseFile({
libraryId: "libraryId",
spaceId: "spaceId",
filterActionBy: SMHFilterAction.preview,
withPath: true
});
}catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
marker
用于顺序列出分页的标识,不传默认第一页
String
limit
用于顺序列出分页时本地列出的项目数限制,可选参数,不传则默认20
String
filterActionBy
筛选操作方式,不传返回全部,preview 只返回预览操作,modify 返回编辑操作
SMHFilterAction
type
筛选文件类型,当前支持的类型包括:
all: 搜索所有文件,当不传 type 或传空时默认为 all
document: 搜索所有文档,文档类型为:['pdf', 'powerpoint', 'excel', 'word','text']
pdf: 仅搜索 PDF 文档,对应的文件扩展名为 .pdf
powerpoint: 仅搜索演示文稿,如 .ppt、.pptx、.pot、.potx 等
excel: 仅搜索表格文件,如 .xls、.xlsx、.ett、.xltx、.csv 等
word: 仅搜索文档,如 .doc、.docx、.dot、.wps、.wpt 等
text: 仅搜索纯文本,如 .txt、.asp、.htm 等
doc、xls 或 ppt: 仅搜索 Word、Excel 或 Powerpoint 类型文档,对应的文件扩展名为 .doc(x)、.xls(x) 或 .ppt(x)
字符串数组: 可以是文档后缀数组,如 ['.ppt', '.doc', '.excel']等;也可以是上述筛选类型数组,如 ['pdf', 'powerpoint', 'word'] 等
SMHFileInfoType 数组
withPath
是否返回文件路径,true|false,默认为 false,可选参数
Bool

根据文件 ID 查询文件信息

功能说明

用于根据文件 ID 查询文件信息。

示例代码

try {
let result = await SMHFileApis.getFileInfoByInode({
libraryId: "libraryId",
spaceId: "spaceId",
inode: "inode"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
inode
文件 ID
String

检查文件状态

功能说明

用于检查文件状态。

示例代码

try {
let result = await SMHFileApis.headFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
});
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
historyId
历史版本 ID
String

获取 HTML 格式文档预览

功能说明

用于获取 HTML 格式文档预览。

示例代码

try {
let result = await SMHFileApis.previewHtml({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
historyId
历史版本 ID,用于获取不同版本的文件内容
String
type
文档预览方式,如果设置为"pic"则以 jpg 格式预览文档首页,否则以 html 格式预览文档
SMHPreviewType