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) | 写入或替换文件二进制字节并更新 size | void |
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)。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | Partial<CmsFile> | 是(add) | 待新增的 CmsFile 对象(如 name、extension、contentType) |
nameOrId | string | 是(updateBinary) | 文件记录的 id |
binary | number[] | 是(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: string | CmsFile | null | 按 id 查找文件(传入文件名将返回 null) |
getByUrl(url) | url: string | CmsFile | null | 按已绑定路由 URL(如 "/robots.txt")查找文件 |
getByFolder(folder) | folder: string | CmsFile[] | 列出指定路由文件夹下的已路由文件(需用 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: CmsFile | void | 保存文件属性更改;仓库校验 name、extension 与内容变化后再持久化,仅修改 contentType 时建议配合其他变更字段保存 |
delete(nameOrId) | nameOrId: string | void | 按 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: string | ChangeLog[] | null | 查询文件的修改日志;无日志时返回 null |
getByLog(logId) | logId: number | CmsFile | 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;
}