Skip to content

k.site.files ​

站点文件仓库(CmsFile)的读写、二进制更新与版本日志

适用上下文前置条件典型用途
KScript API / 服务端脚本当前站点上下文;getByUrl/getByFolder 需文件已绑定路由管理 CMS 静态文件对象(CmsFile)、更新字节内容与查看历史快照

快速上手 ​

新增 CmsFile 元数据记录、从 all() 获取其 GUID id 并写入二进制字节内容:

js
k.api.post(() => {
    const name = "hello-" + Date.now() + ".txt"
    k.site.files.add({
        name,
        extension: ".txt",
        contentType: "text/plain"
    })

    const created = k.site.files.all().find((f) => f.name === name)
    k.site.files.updateBinary(created.id, [72, 101, 108, 108, 111])
    const afterBinary = k.site.files.get(created.id)
    return { id: String(afterBinary.id), size: afterBinary.size }
})

方法速查 ​

方法 / 属性说明返回值
add(file)新增 CmsFile 元数据记录(不自动注册路由)void
updateBinary(nameOrId, binary)写入或替换文件二进制字节并更新 sizevoid
all()返回站点中的所有 CmsFile 对象CmsFile[]
get(nameOrId)按 id 获取文件对象(仅传文件名返回 null)CmsFile | null
getByUrl(url)按已注册路由 URL 查找文件CmsFile | null
getByFolder(folder)列出路由文件夹下的已路由文件(需 for...of 遍历)CmsFile[]
update(file)保存文件属性更改void
delete(nameOrId)按 id 删除文件记录void
getLogs(nameOrId)查询文件的修改日志ChangeLog[] | null
getByLog(logId)按日志编号还原对应的历史版本对象CmsFile | null

与 k.file、CMS 媒体/文件的区别

API / 入口用途
k.site.files管理站点仓库中的 CmsFile 资源及其版本日志
k.file直接读写站点磁盘文件系统中的文件与目录
文件(CMS 控制台)在 Kooboo 控制台上传与管理文件并自动创建访问路由

注意事项

  • CmsFile 使用随机生成的 GUID 作为 id,不会根据文件名生成固定 ID。因此通过 add() 新增文件后,直接调用 k.site.files.get(name) 会返回 null;请从 all() 找到该文件后使用 id 调用 get(id)、updateBinary(id, bytes) 与 delete(id)。
  • k.site.files.add() 仅写入对象仓库,不会自动注册站点路由;因此 getByUrl() 与 getByFolder() 只能查询到已经绑定路由的文件。
  • getByFolder() 在运行时返回可迭代集合而非原生 JS 数组(Array.isArray(...) 为 false),请使用 for...of 遍历。

详细方法 ​

add() 与 updateBinary() ​

新增文件元数据记录后,可通过 all() 获取其生成的 id,再使用 updateBinary() 写入二进制字节数组(系统会自动更新 size)。

参数类型必填说明
filePartial<CmsFile>是(add)待新增的 CmsFile 对象(如 name、extension、contentType)
nameOrIdstring是(updateBinary)文件记录的 id
binarynumber[]是(updateBinary)字节数组

返回值:void

js
k.api.post(() => {
    const file = k.site.files.all().find((f) => f.name === "hello.txt")
    if (!file) return { found: false }
    k.site.files.updateBinary(file.id, [72, 105])
    return { size: k.site.files.get(file.id).size }
})

all() / get() / getByUrl() / getByFolder() ​

列出站点文件,或按 id、路由 URL、路由文件夹查询文件。

方法参数返回值说明
all()无CmsFile[]返回站点中的所有文件对象
get(nameOrId)nameOrId: stringCmsFile | null按 id 查找文件(传入文件名将返回 null)
getByUrl(url)url: stringCmsFile | null按已绑定路由 URL(如 "/robots.txt")查找文件
getByFolder(folder)folder: stringCmsFile[]列出指定路由文件夹下的已路由文件(需用 for...of 遍历)

返回值:CmsFile[] 或 CmsFile | null

js
k.api.get(() => {
    const allFiles = k.site.files.all()
    const folderFiles = k.site.files.getByFolder("/")
    const routedNames = []
    for (const file of folderFiles) {
        routedNames.push(file.name)
    }
    return {
        totalCount: allFiles.length,
        rootRoutedNames: routedNames
    }
})

update() / delete() ​

保存文件元信息更新或按 id 删除文件记录。

方法参数返回值说明
update(file)file: CmsFilevoid保存文件属性更改;仓库校验 name、extension 与内容变化后再持久化,仅修改 contentType 时建议配合其他变更字段保存
delete(nameOrId)nameOrId: stringvoid按 id 删除文件记录

返回值:void

js
k.api.post(() => {
    const file = k.site.files.get(k.request.form.id)
    if (!file) return { found: false }
    file.name = k.request.form.newName
    file.contentType = "text/plain; charset=utf-8"
    k.site.files.update(file)
    return { updated: true, name: k.site.files.get(file.id).name }
})

getLogs() / getByLog() ​

查询文件变更历史并按日志编号还原对应快照。

方法参数返回值说明
getLogs(nameOrId)nameOrId: stringChangeLog[] | null查询文件的修改日志;无日志时返回 null
getByLog(logId)logId: numberCmsFile | null按日志编号还原对应的历史版本对象

返回值:ChangeLog[] | null 或 CmsFile | null

js
k.api.get(() => {
    const logs = k.site.files.getLogs(k.request.queryString.id)
    const firstSnapshot = logs && logs.length ? k.site.files.getByLog(logs[0].logId) : null
    return {
        logCount: logs ? logs.length : 0,
        snapshotName: firstSnapshot ? firstSnapshot.name : null
    }
})

TypeScript 定义 ​

ts
interface FileRepository {
  add(file: Partial<CmsFile>): void;
  all(): CmsFile[];
  get(nameOrId: string): CmsFile | null;
  getByUrl(url: string): CmsFile | null;
  getByFolder(folder: string): CmsFile[];
  update(file: CmsFile): void;
  updateBinary(nameOrId: string, binary: number[]): void;
  delete(nameOrId: string): void;
  getLogs(nameOrId: string): ChangeLog[] | null;
  getByLog(logId: number): CmsFile | null;
}

interface CmsFile {
  id: string;
  name: string;
  extension: string;
  contentType: string;
  size: number;
  online: boolean;
  version: number;
  creationDate: Date;
  lastModified: Date;
}

相关文档 ​