FileApi

文件上传与下载模块，涵盖群文件管理、文件流传输、闪传、在线文件等。

方法

文件上传与下载

方法	返回类型	说明
uploadGroupFile(groupId: number, file: string, name: string, folder?: string)	Result<void>	上传群文件
uploadPrivateFile(userId: number, file: string, name: string)	Result<void>	上传私聊文件
getGroupFileUrl(groupId: number, fileId: string)	Result<{ url: string }>	获取群文件 URL
getPrivateFileUrl(fileId: string)	Result<PrivateFileUrl>	获取私聊文件 URL
downloadFile(url?: string, base64?: string, name?: string, headers?: Record<string, string> | string[] | string)	Result<{ file: string }>	下载文件到缓存目录
getFile(file?: string, fileId?: string)	Result<{ file: string }>	获取文件信息

群文件管理

方法	返回类型	说明
createGroupFileFolder(groupId: number, name: string)	Result<void>	创建群文件文件夹
deleteGroupFolder(groupId: number, folderId: string)	Result<void>	删除群文件文件夹
deleteGroupFile(groupId: number, fileId: string)	Result<void>	删除群文件
moveGroupFile(groupId: number, fileId: string, currentParentDirectory: string, targetParentDirectory: string)	Result<void>	移动群文件
renameGroupFile(groupId: number, fileId: string, currentParentDirectory: string, newName: string)	Result<void>	重命名群文件
transGroupFile(groupId: number, fileId: string)	Result<void>	转发群文件到其他群
getGroupFileSystemInfo(groupId: number)	Result<FileSystemInfo>	获取群文件系统信息
getGroupRootFiles(groupId: number, fileCount?: number)	Result<FileList>	获取群根目录文件列表
getGroupFilesByFolder(groupId: number, folderId?: string, fileCount?: number)	Result<FileList>	获取群子目录文件列表

文件流传输（4.18.6+）

方法	返回类型	说明
downloadFileImageStream(file?: string, fileId?: string, chunkSize?: number)	Result<void>	下载图片文件流
downloadFileRecordStream(file?: string, fileId?: string, chunkSize?: number, outFormat?: string)	Result<void>	下载语音文件流
downloadFileStream(file?: string, fileId?: string, chunkSize?: number)	Result<void>	下载文件流
uploadFileStream(params: UploadFileStreamParams)	Result<void>	上传文件流
cleanStreamTempFile()	Result<void>	清理流式传输临时文件

文件集与闪传

方法	返回类型	说明
getFilesetId(shareCode: string)	Result<{ fileset_id: string }>	获取文件集 ID
getFilesetInfo(filesetId: string)	Result<unknown>	获取文件集信息
downloadFileset(filesetId: string)	Result<void>	下载文件集
getFlashFileList(filesetId: string)	Result<unknown[]>	获取闪传文件列表
getFlashFileUrl(filesetId: string, fileName?: string, fileIndex?: number)	Result<{ url: string }>	获取闪传文件链接
createFlashTask(files: unknown[], name?: string, thumbPath?: string)	Result<void>	创建闪传任务
getShareLink(filesetId: string)	Result<{ url: string }>	获取文件分享链接

在线文件

方法	返回类型	说明
sendOnlineFile(userId: number, filePath: string, fileName?: string)	Result<void>	发送在线文件
sendOnlineFolder(userId: number, folderPath: string, folderName?: string)	Result<void>	发送在线文件夹
receiveOnlineFile(userId: number, msgId: string, elementId: string)	Result<void>	接收在线文件
refuseOnlineFile(userId: number, msgId: string, elementId: string)	Result<void>	拒绝在线文件
cancelOnlineFile(userId: number, msgId: string)	Result<void>	取消在线文件
getOnlineFileMsg(userId: number)	Result<unknown>	获取在线文件消息

调试

方法	返回类型	说明
testDownloadStream(error?: boolean)	Result<void>	测试下载流（调试用）

返回数据结构

PrivateFileUrl

interface PrivateFileUrl {
  url: string
  [key: string]: unknown
}

FileSystemInfo

interface FileSystemInfo {
  file_count: number
  limit_count: number
  used_space: number
  total_space: number
  [key: string]: unknown
}

FileList

interface FileList {
  files: unknown[]
  folders: unknown[]
  [key: string]: unknown
}

UploadFileStreamParams

interface UploadFileStreamParams {
  stream_id: string
  file_retention: number
  chunk_data?: string
  chunk_index?: number
  total_chunks?: number
  file_size?: number
  expected_sha256?: string
  is_complete?: boolean
  filename?: string
  reset?: boolean
  verify_only?: boolean
}

示例

import { FileApi } from '@aemeath-projects/napcat'

const file = new FileApi(client)

// 上传群文件
const uploadResult = await file.uploadGroupFile(123456789, '/data/report.pdf', '报告.pdf')
if (uploadResult.ok) {
  console.log('上传成功')
} else {
  console.error('上传失败:', uploadResult.error.code, uploadResult.error.message)
}

// 获取群文件系统信息
const fsInfo = await file.getGroupFileSystemInfo(123456789)
if (fsInfo.ok) {
  console.log(`已使用空间: ${fsInfo.data.used_space}, 总空间: ${fsInfo.data.total_space}`)
}

// 下载文件到缓存
const dl = await file.downloadFile({ url: 'https://example.com/file.zip' })
if (dl.ok) {
  console.log('下载完成，缓存路径:', dl.data.file)
}