🥮 mooncakes.io
    Sign in

    q2316367743/open-list/fs does not have a README file

    FileHash

    source
    pub struct FileHash {
      md5 : String?
      sha1 : String?
      sha256 : String?
    }

    上传时可选提供的文件哈希，服务端拿它做一致性校验（也用于判断能否跳过 重复上传）。

    三个字段都是十六进制小写字符串；只有服务端信任这个值，算不准就别填。

    FileHash::new

    source
    fn FileHash::new(md5? : String, sha1? : String, sha256? : String) -> FileHash

    按需构造文件哈希，只填知道的算法。

    FileSystem

    source
    pub struct FileSystem {
      // private fields
    }

    文件系统域：/api/fs/* 下的浏览、搜索、文件管理、上传与归档。

    服务端对这批端点的认证要求并不一致：

    • /fs/list、/fs/get、/fs/archive/meta、/fs/archive/list 必须登录 （这几个挂了强制认证中间件，游客会拿到 401）；
    • /fs/dirs、/fs/search、/fs/other 与所有写操作是「可选认证」， 没登录时按游客权限处理。

    本客户端的门面会在需要时自动登录，所以两类端点都不用特殊处理；要按游客 使用时传 Credentials::Token("")（空 token 不会带认证头）。

    FileSystem::add_offline_download

    source
    async fn FileSystem::add_offline_download(self : FileSystem, path : String, urls : Array[String], tool? : String) -> Array[
    TaskInfo    ] raise 
    OpenListError

    让服务端离线下载一批 URL 到一个目录（POST /api/fs/add_offline_download）。

    tool 指定用哪个离线下载工具（先用 PublicApi::offline_download_tools 查可用列表）；留空时服务端挑默认工具。空白 URL 会被服务端忽略。 返回的是刚创建的任务列表（服务端字段名是 tasks）。

    FileSystem::archive_decompress

    source
    async fn FileSystem::archive_decompress(self : FileSystem, src_dir : String, dst_dir : String, names : Array[String], archive_pass? : String, inner_path? : String, cache_full? : Bool, put_into_new_dir? : Bool, overwrite? : Bool) -> Array[
    TaskInfo    ] raise 
    OpenListError

    把压缩包里的内容解压到 dst_dir（POST /api/fs/archive/decompress）。

    names 是包内要解压的条目（相对包内路径）；服务端把它当异步任务跑， 返回的是刚创建的任务列表（服务端字段名是 task，但值是数组）。

    FileSystem::archive_list

    source
    async fn FileSystem::archive_list(self : FileSystem, path : String, inner_path? : String, password? : String, refresh? : Bool, archive_pass? : String, page? : Int, per_page? : Int) -> 
    PageResult    [
    ArchiveContent    ] raise 
    OpenListError

    分页列出压缩包内某个目录的内容（POST /api/fs/archive/list）。

    inner_path 是包内路径（archive_meta 没给出时留空表示根）。

    FileSystem::archive_meta

    source
    async fn FileSystem::archive_meta(self : FileSystem, path : String, password? : String, refresh? : Bool, archive_pass? : String) -> 
    ArchiveMetaResponse     raise 
    OpenListError

    读取压缩包的结构与元信息（POST /api/fs/archive/meta）。

    加密的包要在 archive_pass 里给密码；refresh 会绕过服务端的归档缓存。

    FileSystem::batch_rename

    source
    async fn FileSystem::batch_rename(self : FileSystem, src_dir : String, rename_objects : Array[RenameObject]) -> Unit raise 
    OpenListError

    批量重命名（POST /api/fs/batch_rename）。

    所有改动都发生在同一个目录 src_dir 下。

    FileSystem::copy

    source
    async fn FileSystem::copy(self : FileSystem, src_dir : String, dst_dir : String, names : Array[String], overwrite? : Bool, skip_existing? : Bool, merge? : Bool) -> Unit raise 
    OpenListError

    复制一批对象（POST /api/fs/copy），参数与 move 相同。

    给对象取直链（POST /api/fs/link，仅管理员）。

    驱动不支持直链时 Link::url 是空字符串；支持多线程加速的驱动还会给出 concurrency 与 part_size，以及需要一起发送的请求头。

    FileSystem::dirs

    source
    async fn FileSystem::dirs(self : FileSystem, path? : String, password? : String, force_root? : Bool) -> Array[
    DirResp    ] raise 
    OpenListError

    列出目录树（POST /api/fs/dirs，只给目录名与修改时间）。

    与 list 的区别：它只递归列举目录（适合做目录选择器），不返回文件。 force_root 为真时从根目录开始，忽略 path。

    FileSystem::get

    source

    取单个对象的详情（POST /api/fs/get）。

    响应里除了对象本身，还有带签名的直链 raw_url，以及该对象的说明与自定义 请求头（挂在元数据上的），见 @core.FsGetResponse。

    FileSystem::list

    source
    async fn FileSystem::list(self : FileSystem, path : String, password? : String, refresh? : Bool, page? : Int, per_page? : Int) -> 
    FsListResponse     raise 
    OpenListError

    列出目录内容（POST /api/fs/list）。

    分页由服务端完成：page 小于 1 时按 1 处理，per_page 小于 1 时返回全部。 refresh 会绕过服务端的目录缓存，代价是慢。

    FileSystem::mkdir

    source
    async fn FileSystem::mkdir(self : FileSystem, path : String) -> Unit raise 
    OpenListError

    新建文件夹（POST /api/fs/mkdir）。

    FileSystem::move_to

    source
    async fn FileSystem::move_to(self : FileSystem, src_dir : String, dst_dir : String, names : Array[String], overwrite? : Bool, skip_existing? : Bool, merge? : Bool) -> Unit raise 
    OpenListError

    把一批对象移动到另一个目录（POST /api/fs/move）。

    skip_existing 与 merge 只在目标已存在时起作用：skip_existing 跳过冲突项， merge 合并目录，两者都为假时按 overwrite 决定是否覆盖。

    FileSystem::multipart_abort

    source
    async fn FileSystem::multipart_abort(self : FileSystem, upload_id : String) -> Unit raise 
    OpenListError

    放弃一个分片上传会话（POST /api/fs/multipart/abort）。

    FileSystem::multipart_chunk

    source
    async fn FileSystem::multipart_chunk(self : FileSystem, upload_id : String, index : Int, data : Bytes) -> 
    SessionSnapshot     raise 
    OpenListError

    上传一个分片（PUT /api/fs/multipart/chunk）。

    index 从 0 开始。分片被拒时（分片乱序、重复、会话不见了）服务端会把当前 会话快照放在错误响应的 data 里，所以抛出的 OpenListError::Api 的 ApiError::data 里仍然能拿到进度，可以据此重试或继续。

    FileSystem::multipart_complete

    source

    声明分片传完，等服务端合并（POST /api/fs/multipart/complete）。

    返回最终快照；驱动真正写盘失败时会抛 OpenListError::Api，state 与 error 在错误的 data 里。

    FileSystem::multipart_init

    source
    async fn FileSystem::multipart_init(self : FileSystem, path : String, size : Int64, chunk_size? : Int, overwrite? : Bool, content_type? : String, last_modified? : Int64, hash? : FileHash) -> 
    MultipartInitResponse     raise 
    OpenListError

    初始化（或续用）一个分片上传会话（POST /api/fs/multipart/init）。

    size 是文件总字节数，必须大于 0。chunk_size 只是建议值，服务端会把它 夹到 [1MB, 配置上限] 之间；实际值看返回的 snapshot.chunk_size。

    FileSystem::multipart_status

    source

    按会话 ID 查分片上传进度（GET /api/fs/multipart/status?upload_id=）。

    FileSystem::multipart_status_by_path

    source

    按「目标路径 + 总大小」查分片上传进度 （GET /api/fs/multipart/status?path=&size=）。

    用于客户端重启后找回未完成的会话，不需要记住 upload_id。

    FileSystem::multipart_upload

    source
    async fn FileSystem::multipart_upload(self : FileSystem, path : String, data : Bytes, chunk_size? : Int, overwrite? : Bool, content_type? : String, hash? : FileHash) -> 
    SessionSnapshot     raise 
    OpenListError

    一步做完「初始化 → 逐片上传 → 合并」。

    分片大小以服务端返回的 snapshot.chunk_size 为准；已经在服务端手里的分片 （续传场景）会被跳过，所以这个函数可以安全地用同一个文件重跑。

    只适合「整块字节已在内存里」的场景（手机端小文件、测试）；大文件请按需自己 调 multipart_init / multipart_chunk / multipart_complete 传流。

    FileSystem::new

    source

    由根包创建（使用者应通过 OpenListClient::fs 获取）。

    FileSystem::other

    source
    async fn FileSystem::other(self : FileSystem, path : String, request_method : String, data? : Json, password? : String) -> Json raise 
    OpenListError

    调用存储驱动的自定义方法（POST /api/fs/other）。

    request_method 是驱动自己认的方法名（例如 GET、POST），data 是驱动 自定义的入参。返回值完全由驱动决定，所以这里不做解码，原样返回信封里的 data。

    FileSystem::put

    source
    async fn FileSystem::put(self : FileSystem, path : String, reader : &
    Reader    , content_length? : Int, overwrite? : Bool, as_task? : Bool, content_type? : String, last_modified? : Int64, hash? : FileHash) -> 
    TaskInfo    ? raise 
    OpenListError

    流式上传一个文件（PUT /api/fs/put）。

    reader 是文件内容的读取流：大文件不要先读进内存，直接用 @fs.File::open(...) 之类的读到 Reader 传进来。content_length 给了就按 定长发送（同时带上 X-File-Size），不给就按 Transfer-Encoding: chunked 发送——那种情况下服务端只认 X-File-Size，所以流式上传务必给出大小。

    返回值：as_task 为真（且服务端接受了异步任务）时是刚创建的任务，否则是 None——同步上传完毕。要进度回调可以用 OpenListClient::request 自己拼配置，或后续版本再加。

    FileSystem::put_bytes

    source
    async fn FileSystem::put_bytes(self : FileSystem, path : String, data : Bytes, overwrite? : Bool, as_task? : Bool, content_type? : String, last_modified? : Int64, hash? : FileHash) -> 
    TaskInfo    ? raise 
    OpenListError

    上传一块已经在内存里的字节（PUT /api/fs/put 的便捷版）。

    适合小文件；大文件请用 put 传流，避免把整个文件读进内存。

    FileSystem::put_form

    source
    async fn FileSystem::put_form(self : FileSystem, path : String, filename : String, data : Bytes, overwrite? : Bool, as_task? : Bool, content_type? : String, last_modified? : Int64, hash? : FileHash) -> 
    TaskInfo    ? raise 
    OpenListError

    用 multipart/form-data 上传（PUT /api/fs/form）。

    表单字段名固定是 file；filename 只用于让服务端猜 MIME 类型。 除了请求体形态不同，头与语义都和 put 一样。

    FileSystem::recursive_move

    source
    async fn FileSystem::recursive_move(self : FileSystem, src_dir : String, dst_dir : String, conflict_policy? : String) -> Unit raise 
    OpenListError

    递归移动目录（POST /api/fs/recursive_move，连子目录一起搬）。

    conflict_policy 决定遇到同名项怎么办：skip、overwrite、merge （留 None 时服务端按 overwrite 处理）。

    FileSystem::regex_rename

    source
    async fn FileSystem::regex_rename(self : FileSystem, src_dir : String, src_name_regex : String, new_name_regex : String) -> Unit raise 
    OpenListError

    用正则批量重命名（POST /api/fs/regex_rename）。

    服务端对目录下每个名字做 src_name_regex 匹配，再按 new_name_regex 生成新名字（仅匹配到第一个的项会被改名）。

    FileSystem::remove

    source
    async fn FileSystem::remove(self : FileSystem, dir : String, names : Array[String]) -> Unit raise 
    OpenListError

    删除一批对象（POST /api/fs/remove）。

    注意参数是「目录 + 目录下的名字」，而不是完整路径。

    FileSystem::remove_empty_directory

    source
    async fn FileSystem::remove_empty_directory(self : FileSystem, src_dir : String) -> Unit raise 
    OpenListError

    删除目录下所有空目录（POST /api/fs/remove_empty_directory）。

    FileSystem::rename

    source
    async fn FileSystem::rename(self : FileSystem, path : String, name : String, overwrite? : Bool) -> Unit raise 
    OpenListError

    重命名（POST /api/fs/rename）。

    path 是原路径，name 是新名字（不含目录）。overwrite 为真时允许 覆盖同名对象。

    FileSystem::search

    source
    async fn FileSystem::search(self : FileSystem, parent : String, keywords : String, scope? : Int, page? : Int, per_page? : Int, password? : String) -> 
    PageResult    [
    SearchResult    ] raise 
    OpenListError

    在某个目录下按关键字搜索（POST /api/fs/search）。

    scope：0 全部、1 只搜目录、2 只搜文件；留 None 时服务端按 0 处理。搜索结果由服务端分页，total 是命中总数。

    RenameObject

    source
    pub struct RenameObject {
      src_name : String
      new_name : String
    }

    批量重命名里的一项：把 src_name 改成 new_name。

    RenameObject::new

    source
    fn RenameObject::new(src_name : String, new_name : String) -> RenameObject

    构造一条重命名项。

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io