k.site.htmlBlocks
站点多语言 HTML 片段(HtmlBlock)的读取、模板占位渲染与更新
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
| KScript API / KView / 服务端脚本 | 当前站点上下文;多语言值按请求语言或指定 culture 解析 | 读取并渲染可复用的多语言 HTML 内容块、替换 {key} 占位符 |
快速上手
写入当前语言和英文版本内容块,并用 getValue(name, params) 渲染 {who} 占位符:
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: string | void | 在当前请求语言下新增或更新内容块内容 |
add(name, value, culture) | name: string, value: string, culture: string | void | 向指定语言 culture(如 "en"、"zh")写入内容;若内容块已存在,则仅追加或覆盖该语言的值 |
getOrAdd(nameOrId, defaultValue) | nameOrId: string, defaultValue: string | HtmlBlock | 已存在时直接返回原内容块(不覆盖原有值);不存在时以 defaultValue 创建并返回 |
返回值:void 或 HtmlBlock
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: string | HtmlBlock | null | 获取内容块包装对象,支持 keys、length、getValue() 与 getCultureValue(culture) |
getValue(nameOrId) | nameOrId: string | string | 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
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?: string | void | 直接更新当前或指定语言的 HTML 内容 |
update(block) | block: HtmlBlock | void | 保存对已获取 HtmlBlock 包装对象的修改(会写入 block 获取时的完整多语言 Values 快照) |
update(block) 会整体覆盖多语言快照
get() 返回的 HtmlBlock 持有获取瞬间的全量多语言 Values 副本。如果在 get() 之后又调用了按名称的 update(name, ...),再去保存旧的 block 对象会把整个 Values 字典回写为旧快照、覆盖刚才按名称更新的内容。混用两种方式时,请在调用 update(block) 前重新 get() 最新对象。
返回值:void
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 定义
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;
}