k.site.images
站点图片媒体库(Image)的上传、URL 查询、元信息更新与删除
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
| KScript API / 服务端脚本 | 当前站点上下文;上传场景需提供二进制字节数组 | 通过 addImage 上传图片并自动创建访问路由,查询或修改图片元信息 |
快速上手
接收请求上传的图片文件并写入站点媒体库(自动计算宽高并注册访问路由):
js
k.api.post(() => {
const file = k.request.files[0]
const uploaded = k.site.images.addImage(
"/uploads/" + file.fileName,
file.bytes,
"Uploaded image"
)
return {
id: String(uploaded.id),
url: uploaded.url,
width: uploaded.width,
height: uploaded.height,
previewUrl: uploaded.previewUrl
}
})方法速查
| 方法 / 属性 | 说明 | 返回值 |
|---|---|---|
addImage(path, data, alt?) | 上传图片字节到指定路径、计算宽高并注册路由 | MediaStorageFileModel |
all() | 返回站点中的所有 Image 对象(仅索引列元数据,不含 alt 与 contentBytes) | Image[] |
get(nameOrId) | 按 GUID id 获取图片(仅传文件名返回 null) | Image | null |
getByUrl(url) | 按已注册路由 URL 查找图片 | Image | null |
getByFolder(folder) | 列出指定文件夹路径下的图片(仅索引列元数据;需 for...of 遍历) | Image[] |
add(image) | 新增图片记录(未传字节会抛错,上传请优先用 addImage) | void |
update(image) | 更新图片元信息(须传入 get(id) 或 getByUrl(url) 获取的完整对象) | void |
updateBinary(nameOrId, binary) | 替换已有图片的内容字节并更新大小 | void |
delete(nameOrId) | 按 id 删除图片及其关联路由 | void |
getLogs(nameOrId) | 查询图片的变更日志 | ChangeLog[] | null |
getByLog(logId) | 按日志编号恢复对应历史版本 | Image | null |
与 k.site.files、CMS 媒体库的关系
| API / 入口 | 用途 |
|---|---|
k.site.images | 站点图片媒体库的上传(addImage)、查询、二进制更新与删除 |
| k.site.files | 站点通用静态文件(CmsFile)的仓库操作 |
| 媒体库(CMS 控制台) | 在控制台中浏览与管理站点图片资源 |
注意事项
- 上传图片请用
addImage():调用add({ name: "..." })且未提供二进制字节时,会抛出"Value cannot be null. (Parameter 'buffer')"错误。 all()与getByFolder()仅返回列数据:这两个方法仅加载索引列元数据(id、name、width、height、size、lastModified),不会加载alt与contentBytes。读取alt或调用update(image)前,必须先通过get(id)或getByUrl(url)获取完整Image对象;直接把all()/getByFolder()返回的部分对象传给update(image)会把数据库中的图片二进制内容清空为null。- 随机 GUID 主键:
Image使用随机 GUID 作为id(不会按文件名哈希),因此get(name)会返回null;请使用addImage()返回的id、getByUrl(url)或从all()获取。 - ID 比较建议转字符串:跨接口返回的图片对象
id为 GUID 对象,比较是否一致时请使用String(a.id) === String(b.id)。 getByFolder()返回可迭代集合:运行时Array.isArray(...)为false,请使用for...of遍历。
详细方法
addImage()
上传字节数组到指定站点路径并注册访问路由,自动识别尺寸并可选设置 alt 文本。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
path | string | 是 | 目标站点路径(如 "/images/banner.png") |
data | number[] | 是 | 图片二进制字节数组(例如来自上传请求的 file.bytes) |
alt | string | 否 | 图片替代文本(alt) |
返回值:MediaStorageFileModel。包含生成的 id、url、width、height、size、previewUrl 与 downloadUrl。
js
k.api.post(() => {
const file = k.request.files[0]
const uploaded = k.site.images.addImage(
"/uploads/" + file.fileName,
file.bytes,
"Banner"
)
return { id: String(uploaded.id), url: uploaded.url }
})all() / get() / getByUrl() / getByFolder()
列出站点图片,或按 GUID id、访问路由 URL、目录路径查询图片。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
all() | 无 | Image[] | 返回站点中的所有图片对象(仅加载索引列元数据,不含 alt 与 contentBytes) |
get(nameOrId) | nameOrId: string | Image | null | 按图片 id 查询完整对象(传入纯文件名将返回 null) |
getByUrl(url) | url: string | Image | null | 按图片访问路由 URL(如 "/uploads/logo.png")查询完整对象 |
getByFolder(folder) | folder: string | Image[] | 列出指定文件夹路径下的图片(仅加载索引列元数据,不含 alt 与 contentBytes;需用 for...of 遍历) |
返回值:Image[] 或 Image | null
js
k.api.get(() => {
const byUrl = k.site.images.getByUrl("/uploads/logo.png")
const inRoot = k.site.images.getByFolder("/")
const rootIds = []
for (const img of inRoot) {
rootIds.push(String(img.id))
}
return {
foundByUrl: !!byUrl,
totalImages: k.site.images.all().length,
rootIds
}
})update() / updateBinary() / delete()
更新图片元信息、替换内容字节或按 id 删除图片与路由。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
update(image) | image: Image | void | 更新图片属性(如 alt 等);必须传入经 get(id) 或 getByUrl(url) 获取的完整对象,切勿直接传入 all() / getByFolder() 返回的部分对象 |
updateBinary(nameOrId, binary) | nameOrId: string, binary: number[] | void | 替换已有图片的内容字节并更新大小 |
delete(nameOrId) | nameOrId: string | void | 按 id 删除图片及其关联路由 |
返回值:void
js
k.api.post(() => {
const img = k.site.images.get(k.request.form.id)
if (!img) return { found: false }
img.alt = "Updated alt text"
k.site.images.update(img)
const logs = k.site.images.getLogs(img.id)
const snapshot = logs && logs.length ? k.site.images.getByLog(logs[0].logId) : null
return {
alt: k.site.images.get(img.id)?.alt,
logCount: logs ? logs.length : 0,
snapshotMatched: !!snapshot && String(snapshot.id) === String(img.id)
}
})getLogs() / getByLog()
查询图片修改历史并按日志编号恢复历史快照。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
getLogs(nameOrId) | nameOrId: string | ChangeLog[] | null | 查询图片的变更日志;无日志时返回 null |
getByLog(logId) | logId: number | Image | null | 按日志编号恢复对应历史版本 |
返回值:ChangeLog[] | null 或 Image | null
TypeScript 定义
展开完整 TypeScript 定义
ts
interface ImageRepository {
addImage(path: string, data: number[], alt?: string): MediaStorageFileModel;
all(): Image[];
get(nameOrId: string): Image | null;
getByUrl(url: string): Image | null;
getByFolder(folder: string): Image[];
add(image: Partial<Image>): void;
update(image: Image): void;
updateBinary(nameOrId: string, binary: number[]): void;
delete(nameOrId: string): void;
getLogs(nameOrId: string): ChangeLog[] | null;
getByLog(logId: number): Image | null;
}
interface MediaStorageFileModel {
id: string;
key: string;
url: string;
name: string;
size: number;
folder: string;
previewUrl: string;
downloadUrl: string;
mimeType: string;
width: number;
height: number;
isImage: boolean;
type: string;
alt: string;
lastModified: Date;
}
interface Image {
id: string;
name: string;
extension: string;
alt: string;
width: number;
height: number;
size: number;
isSvg: boolean;
creationDate: Date;
lastModified: Date;
}