Files

API 參考

瀏覽並管理檔案和目錄。支援多掛載儲存（內部儲存、SD 卡、USB）。

型別定義

bash

type File {
  name: String!
  path: String!
  permission: String!        # "rw" | "r"
  createdAt: String          # ISO 8601, null on some filesystems
  updatedAt: String!         # ISO 8601
  size: Long!                # 0 for directories
  isDir: Boolean!
  childCount: Int!           # 0 for files; child count for directories
  mediaId: String!           # media store ID, empty when unavailable
}

type StorageMount {
  id: String!
  name: String!
  path: String!
  mountPoint: String!
  fsType: String!
  totalBytes: Long!
  usedBytes: Long!
  freeBytes: Long!
  remote: Boolean!
  alias: String!
}

type FileInfo {
  path: String!
  updatedAt: String!
  size: Long!
  tags: [Tag!]!
  data: MediaFileInfo          # image/video/audio metadata, null for other types
}

type MediaFileInfo {
  # Union-like structure; fields vary by media type (image / video / audio)
  width: Int
  height: Int
  duration: Int               # milliseconds (video / audio)
  artist: String
  album: String
  title: String
}

type FavoriteFolder {
  rootPath: String!
  fullPath: String!
  alias: String               # optional display alias, empty when not set
}

操作

query

mounts

列出所有可用的儲存磁碟區（內部儲存、SD 卡、USB）。

bash

query GetMounts {
  mounts {
    id name path mountPoint fsType totalBytes usedBytes freeBytes remote alias
  }
}

query

recentFiles

列出所有儲存中最近修改的檔案。Files UI 中「最近」檢視的資料來源。

bash

query GetRecentFiles {
  recentFiles {
    name path permission createdAt updatedAt size isDir childCount mediaId
  }
}

query

files

在根路徑下列出並搜尋檔案，支援分頁。傳入空查詢可列出全部。

bash

query GetFiles($root: String!, $offset: Int!, $limit: Int!, $query: String!, $sortBy: FileSortBy!) {
  files(root: $root, offset: $offset, limit: $limit, query: $query, sortBy: $sortBy) {
    name path permission createdAt updatedAt size isDir childCount mediaId
  }
}

query

fileInfo

取得單一檔案的 stat + 媒體中繼資料 + 標籤。傳入 fileName 以便伺服器偵測圖片/影片/音訊並載入寬度、高度、時長等。

bash

query GetFileInfo($id: ID!, $path: String!, $fileName: String!) {
  fileInfo(id: $id, path: $path, fileName: $fileName) {
    path updatedAt size
    tags { id name }
    data { width height duration artist album title }
  }
}

query

fileIds

將檔案系統路徑清單解析為其媒體存放區 ID（未索引時為空字串）。

bash

query GetFileIds($paths: [String!]!) {
  fileIds(paths: $paths)
}

query

uploadedChunks

列出可恢復分片上傳中已接收的分片索引。用於恢復中斷的上傳。

bash

query GetUploadedChunks($fileId: String!) {
  uploadedChunks(fileId: $fileId)
}

mutation

createDir

建立新目錄並將其作為 File 物件傳回。

bash

mutation CreateDir($path: String!) {
  createDir(path: $path) {
    name path permission createdAt updatedAt size isDir childCount mediaId
  }
}

mutation

renameFile

重新命名檔案或目錄。

bash

mutation RenameFile($path: String!, $name: String!) {
  renameFile(path: $path, name: $name)
}

mutation

writeTextFile

將文字內容寫入檔案。設定 overwrite=false 可在檔案已存在時附加 "(1)" 後綴。

bash

mutation WriteTextFile($path: String!, $content: String!, $overwrite: Boolean!) {
  writeTextFile(path: $path, content: $content, overwrite: $overwrite) {
    name path size updatedAt
  }
}

mutation

deleteFiles

依精確路徑刪除一個或多個檔案或目錄。

bash

mutation DeleteFiles($paths: [String!]!) {
  deleteFiles(paths: $paths)
}

mutation

copyFile

將檔案或目錄複製到目標路徑。設定 overwrite 可取代已存在的檔案。

bash

mutation CopyFile($src: String!, $dst: String!, $overwrite: Boolean!) {
  copyFile(src: $src, dst: $dst, overwrite: $overwrite)
}

mutation

moveFile

將檔案或目錄移動到目標路徑。設定 overwrite 可取代已存在的檔案。

bash

mutation MoveFile($src: String!, $dst: String!, $overwrite: Boolean!) {
  moveFile(src: $src, dst: $dst, overwrite: $overwrite)
}

mutation

addFavoriteFolder

收藏資料夾以便快速存取。傳回所有已收藏資料夾的更新清單。

bash

mutation AddFavoriteFolder($rootPath: String!, $fullPath: String!) {
  addFavoriteFolder(rootPath: $rootPath, fullPath: $fullPath) {
    rootPath fullPath alias
  }
}

mutation

removeFavoriteFolder

移除已收藏的資料夾。傳回剩餘資料夾的更新清單。

bash

mutation RemoveFavoriteFolder($fullPath: String!) {
  removeFavoriteFolder(fullPath: $fullPath) {
    rootPath fullPath alias
  }
}

mutation

setFavoriteFolderAlias

設定或更新已收藏資料夾顯示的別名。傳入空字串可清除別名。

bash

mutation SetFavoriteFolderAlias($fullPath: String!, $alias: String!) {
  setFavoriteFolderAlias(fullPath: $fullPath, alias: $alias) {
    rootPath fullPath alias
  }
}

mutation

deleteChunks

刪除分片上傳 fileId 的所有已儲存分片。在取消或失敗的上傳後使用以釋放磁碟空間。

bash

mutation DeleteChunks($fileId: String!) {
  deleteChunks(fileId: $fileId)
}

mutation

mergeChunks

將先前上傳的分片合併為最終檔案。傳入 isAppFile=true 可將結果匯入 PlainApp 的內容定址 AppFile 存放區（由聊天附件使用）。

bash

mutation MergeChunks($fileId: String!, $totalChunks: Int!, $path: String!, $replace: Boolean!, $isAppFile: Boolean!) {
  mergeChunks(fileId: $fileId, totalChunks: $totalChunks, path: $path, replace: $replace, isAppFile: $isAppFile)
}