Skip to content

k.site.htmlBlocks ​

站点多语言 HTML 片段(HtmlBlock)的读取、模板占位渲染与更新

适用上下文前置条件典型用途
KScript API / KView / 服务端脚本当前站点上下文;多语言值按请求语言或指定 culture 解析读取并渲染可复用的多语言 HTML 内容块、替换 {key} 占位符

快速上手 ​

写入当前语言和英文版本内容块,并用 getValue(name, params) 渲染 {who} 占位符:

js
k.api.post(() => {
    const name = "site-notice"
    k.site.htmlBlocks.add(name, "<p>欢迎,{who}</p>")
    k.site.htmlBlocks.add(name, "<p>Welcome, {who}</p>", "en")

    const fallback = k.site.htmlBlocks.getOrAdd("footer-note", "<p>默认页脚</p>")
    return {
        notice: k.site.htmlBlocks.getValue(name, { who: "Kooboo" }),
        footer: fallback.getValue()
    }
})

方法速查 ​

方法 / 属性说明返回值
add(name, value, culture?)按当前或指定 culture 创建/覆盖内容块值void
getOrAdd(nameOrId, defaultValue)已存在时直接返回原对象;不存在时以默认值创建并返回HtmlBlock
all()返回站点中全部多语言内容块对象HtmlBlock[]
get(nameOrId)获取内容块包装对象(可读写各语言值)HtmlBlock | null
getValue(nameOrId, params?)返回当前语言 HTML 字符串,可选替换 {key} 占位符string | null
update(name, value, culture?)按名称更新当前或指定语言的内容void
update(block)提交修改后的 HtmlBlock 包装对象void
delete(nameOrId)删除入口(当前运行时不会实际移除记录)void

与 k.label、CMS 内容块的关系

API / 入口用途
k.site.htmlBlocks管理支持多语言与 {key} 变量替换的可复用 HTML 片段
k.label管理轻量级多语言文本标签(纯文本或短语)
HTML 内容块(CMS)在 Kooboo 控制台中可视化编辑与删除 HTML 内容块

注意事项

  • 在当前运行时版本中,调用 k.site.htmlBlocks.delete(nameOrId) 不会实际删除内容块记录。如需清理不再使用的内容块,请在控制台 HTML 内容块 页面手动移除,避免在脚本中反复生成临时名称的测试内容块。

详细方法 ​

add() 与 getOrAdd() ​

向当前请求语言或指定语言写入内容块,或使用 getOrAdd() 在缺失时初始化默认值。

方法参数返回值说明
add(name, value)name: string, value: stringvoid在当前请求语言下新增或更新内容块内容
add(name, value, culture)name: string, value: string, culture: stringvoid向指定语言 culture(如 "en"、"zh")写入内容;若内容块已存在,则仅追加或覆盖该语言的值
getOrAdd(nameOrId, defaultValue)nameOrId: string, defaultValue: stringHtmlBlock已存在时直接返回原内容块(不覆盖原有值);不存在时以 defaultValue 创建并返回

返回值:void 或 HtmlBlock

js
k.api.post(() => {
    const block = k.site.htmlBlocks.getOrAdd("announcement", "<p>系统正常运行中</p>")
    return {
        keys: block.keys,
        value: block.getValue()
    }
})

get() / getValue() / all() ​

获取多语言内容块对象或直接渲染当前语言 HTML 字符串。

方法参数返回值说明
all()无HtmlBlock[]返回站点中全部多语言内容块对象
get(nameOrId)nameOrId: stringHtmlBlock | null获取内容块包装对象,支持 keys、length、getValue() 与 getCultureValue(culture)
getValue(nameOrId)nameOrId: stringstring | null返回当前语言或回退匹配到的 HTML 字符串;内容块不存在时返回 null
getValue(nameOrId, params)nameOrId: string, params: Record<string, any>string | null返回当前语言或回退匹配到的 HTML 字符串,并将 {key} 占位符替换为 params[key]

语言缺失时的回退行为

当内容块存在但缺少目标语言时,block.getValue()、block.getCultureValue(culture) 与 k.site.htmlBlocks.getValue(nameOrId) 并不会严格返回 null,而是按以下顺序回退:空键 "" → 以目标语言为前缀的键 → 块中第一个非空语言值(仅当没有任何非空值时 block.getValue() / getCultureValue() 返回 null)。若需严格判断某语言键是否存在,请先检查 block.keys。

返回值:HtmlBlock[]、HtmlBlock | null 或 string | null

js
k.api.get(() => {
    const block = k.site.htmlBlocks.get("site-notice")
    return {
        totalBlocks: k.site.htmlBlocks.all().length,
        keys: block ? block.keys : [],
        zhValue: block ? block.getValue() : null,
        enValue: block ? block.getCultureValue("en") : null,
        rendered: k.site.htmlBlocks.getValue("site-notice", { who: "开发者" })
    }
})

update() ​

支持通过名称与字符串直接更新当前语言或指定语言,也支持先修改 get() 返回的对象后再调用 update(block) 保存。

方法参数返回值说明
update(name, value, culture?)name: string, value: string, culture?: stringvoid直接更新当前或指定语言的 HTML 内容
update(block)block: HtmlBlockvoid保存对已获取 HtmlBlock 包装对象的修改(会写入 block 获取时的完整多语言 Values 快照)

update(block) 会整体覆盖多语言快照

get() 返回的 HtmlBlock 持有获取瞬间的全量多语言 Values 副本。如果在 get() 之后又调用了按名称的 update(name, ...),再去保存旧的 block 对象会把整个 Values 字典回写为旧快照、覆盖刚才按名称更新的内容。混用两种方式时,请在调用 update(block) 前重新 get() 最新对象。

返回值:void

js
k.api.post(() => {
    // 方式一:按名称更新当前语言或指定语言
    k.site.htmlBlocks.update("site-notice", "<p>公告已更新</p>")
    k.site.htmlBlocks.update("site-notice", "<p>Notice updated</p>", "en")

    // 方式二:重新获取最新对象后修改并保存(避免旧快照覆盖上面的按名称更新)
    const block = k.site.htmlBlocks.get("site-notice")
    if (!block) return { updated: false }

    block.setCultureValue("en", "<p>Updated via object</p>")
    k.site.htmlBlocks.update(block)

    return {
        zh: k.site.htmlBlocks.getValue("site-notice"),
        en: k.site.htmlBlocks.get("site-notice")?.getCultureValue("en")
    }
})

TypeScript 定义 ​

ts
interface HtmlBlockRepository {
  all(): HtmlBlock[];
  get(nameOrId: string): HtmlBlock | null;
  getValue(nameOrId: string): string | null;
  getValue(nameOrId: string, params: Record<string, any>): string | null;
  getOrAdd(nameOrId: string, defaultValue: string): HtmlBlock;
  add(name: string, value: string): void;
  add(name: string, value: string, culture: string): void;
  add(block: Partial<HtmlBlock> & { name: string; value?: string }): void;
  update(name: string, value: string): void;
  update(name: string, value: string, culture: string): void;
  update(block: HtmlBlock): void;
  delete(nameOrId: string): void;
}

interface HtmlBlock {
  name: string;
  keys: string[];
  length: number;
  getValue(): string | null;
  getCultureValue(culture: string): string | null;
  setValue(value: string): void;
  setCultureValue(culture: string, value: string): void;
}

相关文档 ​