上传下载相关API
API
| 接口 | 说明 |
|---|---|
| JBoltApi.uploadToQiniu | 上传到七牛 |
| JBoltApi.uploadToServer | 上传到JBolt服务器端 |
| JBoltApi.download | 下载文件 |
上传到七牛 JboltApi.uploadToQiniu
接口定义：
ts
async function uploadToQiniu(
files: File[] | File,
qiniuPath: string,
qiniuSn?: string,
next?: (args: { size: number; loaded: number; percent: number }) => void,
complete?: (args: { url: string; key: string; hash: string }) => void,
error?: (args: { file: File; path: string; error: Error }) => void,
putExtra?: Record<string, any>,
config?: Record<string, any>
): Promise<string[] | string>async function uploadToQiniu(
files: File[] | File,
qiniuPath: string,
qiniuSn?: string,
next?: (args: { size: number; loaded: number; percent: number }) => void,
complete?: (args: { url: string; key: string; hash: string }) => void,
error?: (args: { file: File; path: string; error: Error }) => void,
putExtra?: Record<string, any>,
config?: Record<string, any>
): Promise<string[] | string>参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| files | File[] | File | 要上传的文件，可以使单个，也可以是file数组 |
| qiniuPath | string | 七牛保存路径，支持动态参数，参考下方说明 |
| qiniuSn | string | 使用哪个七牛bucket配置，不传则使用默认配置，参考下方通用配置说明 |
| next | (args: { size: number; loaded: number; percent: number }) => void | 上传进度回调，每次上传进度变化都会触发，percent当前上传进度，size文件大小，loaded已上传大小 |
| complete | (args: { url: string; key: string; hash: string }) => void | 上传完成回调，url文件完整访问地址，key文件保存路径，hash文件hash值 |
| error | (args: { file: File; path: string; error: Error }) => void | 上传失败回调，file上传的文件，path文件保存路径，error错误信息 |
| putExtra | object | 参考七牛文档 |
| config | object | 参考七牛文档 |
返回值
如果传入file，则返回一个字符串，代表上传后的文件完整访问地址，如果传入file数组，则返回一个字符串数组，代表每个文件上传后的完整访问地址。
示例代码
js
const path = await JBoltApi.uploadToQiniu(
file,
'/img/{date(yyMMdd)}/{random(6)}/{ori}'
)const path = await JBoltApi.uploadToQiniu(
file,
'/img/{date(yyMMdd)}/{random(6)}/{ori}'
)上传到JBolt服务器端 JboltApi.uploadToServer
接口定义：
ts
async function uploadToServer(
files: File[] | File,
savePath: string,
next?: (args: { size: number; loaded: number; percent: number }) => void,
complete?: (args: { url: string; id: string }) => void,
error?: (args: { file: File; path: string; error: Error }) => void
): Promise<string[] | string>async function uploadToServer(
files: File[] | File,
savePath: string,
next?: (args: { size: number; loaded: number; percent: number }) => void,
complete?: (args: { url: string; id: string }) => void,
error?: (args: { file: File; path: string; error: Error }) => void
): Promise<string[] | string>参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| files | File[] | File | 要上传的文件，可以使单个，也可以是file数组 |
| savePath | string | 服务器端保存路径，支持动态参数，参考下方说明 |
| next | (args: { size: number; loaded: number; percent: number }) => void | 上传进度回调，每次上传进度变化都会触发，percent当前上传进度，size文件大小，loaded已上传大小 |
| complete | (args: { url: string; id: string}) => void | 上传完成回调，url文件完整访问地址，id 数据库文件记录id |
| error | (args: { file: File; path: string; error: Error }) => void | 上传失败回调，file上传的文件，path文件保存路径，error错误信息 |
返回值
如果传入file，则返回一个字符串，代表上传后的文件完整访问地址，如果传入file数组，则返回一个字符串数组，代表每个文件上传后的完整访问地址。
示例代码
js
const path = await JBoltApi.uploadToServer(
file,
'/img/{date(yyMMdd)}/{random(6)}/{ori}',
({ percent }) => {
console.debug(`上传进度：${percent}%`)
}
)const path = await JBoltApi.uploadToServer(
file,
'/img/{date(yyMMdd)}/{random(6)}/{ori}',
({ percent }) => {
console.debug(`上传进度：${percent}%`)
}
)下载 JboltApi.download
接口定义：
ts
async function download(url: string, filename: string, config?: Api.RequestConfig): Promise<void>async function download(url: string, filename: string, config?: Api.RequestConfig): Promise<void>参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| url | string | 要下载的地址 |
| filename | string | 保存文件的命名 |
| config | Api.RequestConfig | JBoltApi相关的请求配置 |
示例代码
js
JBoltApi.download('/api/admin/user/export', '用户列表.xlsx')JBoltApi.download('/api/admin/user/export', '用户列表.xlsx')上传通用配置
框架中自带的一些上传相关的组件和API，使用时基本都要指定上传相关的一些属性值，比如上传到哪里，默认使用哪个七牛bucket配置等等。
对于单个项目来说，这些属性值几乎不会怎么变，所以为了减少重复代码的书写，将一些上传相关的通用属性值抽到了.env-config.ts配置文件中，相当于提供了默认的上传配置。当然组件本身还是可以单独指定的。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| defaultUploadTo | UploadTo | qiniu | 将文件上传到哪里 |
| defaultQiniuSn | string | '' | 如果上传到七牛，指定使用哪个七牛配置，这里需要传入七牛的bucket sn值，该值在后台系统管理 - 七牛配置 -七牛Bucket中可以查询到。空字符串代表使用后台管理界面中设置的默认七牛BucketSn，注意： 需要在后台管理界面中同时指定默认的七牛账号和它下面的默认七牛Bucket才可正常工作 |
| serverUploadApi | string | /api/admin/jboltFile/upload | 如果是上传到服务器，指定服务器接口地址。注意： 建议不要修改该接口地址，该接口已在后端框架中内置，并且和前端组件API配合良好。 |
类型 UploadTo
ts
type UploadTo = 'qiniu' | 'server'type UploadTo = 'qiniu' | 'server'指定上传到哪里。目前只支持以下值：
| 值 | 说明 |
|---|---|
| qiniu | 上传到七牛 |
| server | 上传到服务器端 |
生成动态的保存路径
上传通常需要指定一个文件服务器上的保存路径，框架提供了在路径中插入{规则}来生成动态路径。以下是规则的语法说明，假设用户选择了一个叫abc.doc的文件为例：
| 语法 | 说明 | 规则举例 | 生成的结果 |
|---|---|---|---|
| {ori} | 完整的原文件名 | /doc/{ori} | /doc/abc.doc |
| {oriSuffix} | 原文件后缀名 | /doc/a.{oriSuffix} | /doc/a.doc |
| {oriName} | 原文件名,不带后缀 | /doc/{oriName}_1.doc | /doc/abc_1.doc |
| {random(位数)} | 随机字符 | /doc/{random(4)}/{ori} | /doc/e5j8/abc.doc |
| {date(格式)} | 日期 | /doc/{date(yyMMddHH)}/{ori} | /doc/23102410/abc.doc |
| {date} | 日期按照yyyyMMddHHmmss格式化后的值 | /doc/{date}/{ori} | /doc/20231024100521/abc.doc |