Skip to content

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 文本。

参数类型必填说明
pathstring是目标站点路径(如 "/images/banner.png")
datanumber[]是图片二进制字节数组(例如来自上传请求的 file.bytes)
altstring否图片替代文本(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: stringImage | null按图片 id 查询完整对象(传入纯文件名将返回 null)
getByUrl(url)url: stringImage | null按图片访问路由 URL(如 "/uploads/logo.png")查询完整对象
getByFolder(folder)folder: stringImage[]列出指定文件夹路径下的图片(仅加载索引列元数据,不含 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: Imagevoid更新图片属性(如 alt 等);必须传入经 get(id) 或 getByUrl(url) 获取的完整对象,切勿直接传入 all() / getByFolder() 返回的部分对象
updateBinary(nameOrId, binary)nameOrId: string, binary: number[]void替换已有图片的内容字节并更新大小
delete(nameOrId)nameOrId: stringvoid按 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: stringChangeLog[] | null查询图片的变更日志;无日志时返回 null
getByLog(logId)logId: numberImage | 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;
}

相关文档 ​