k.site 上下文与内置工具
当前站点信息、只读配置快照、多语言链接、全文检索、资源版本号、磁盘统计与页面辅助链接
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
| KScript API / KView / 服务端脚本 | 当前站点上下文(search.findAll 需站点开启全文检索) | 读取站点配置与域名、生成多语言/资源版本链接、执行全文检索与统计磁盘占用 |
快速上手
一次读取当前站点名称、语言、基础地址、默认语言配置与磁盘空间占用:
k.api.get(() => {
const info = k.site.info
const site = k.site.webSite
return {
name: info.name,
displayName: site.displayName,
currentCulture: info.culture,
baseUrl: info.baseUrl,
absApiUrl: info.makeAbsUrl("/api/health"),
totalBytes: k.site.diskSpace.getSiteSize().total
}
})方法速查
| 方法 / 属性 | 说明 | 返回值 |
|---|---|---|
k.site.info | 当前请求与站点基础信息、自定义配置及绝对 URL 拼接 | InfoModel |
k.site.webSite | 当前站点配置的只读检查对象(开关状态、默认语言等) | WebSiteInspection |
k.site.settings | 按配置名或下标读取系统内置配置项 | kCoreSettings |
k.site.multilingual | 站点多语言列表与多语言 URL 生成 | Multilingual |
k.site.search | 站点全文搜索(findAll)与自定义目录 Lucene 检索(on) | Search |
k.site.version | 根据站点浏览器缓存开关生成带版本号的图片/JS/CSS 链接 | FileVersion |
k.site.diskSpace | 站点仓库存储占用与修改日志数量统计 | DiskSpace |
k.site.helper | 站点根 URL、页面预览地址与在线编辑跳转地址生成 | SiteHelper |
只读边界与运行时集合类型
- 请将
k.site.webSite视为只读配置检查对象,不要在请求脚本中直接修改其属性,以免污染当前站点配置状态。 info.domains、search.findAll(...)与diskSpace.getSiteSize().repositorySize在运行时返回可迭代集合(Array.isArray(...)为false),遍历时请使用for...of。
详细模块
info 与 webSite(只读)
k.site.info 提供当前站点名称、语言、baseUrl、host、绑定域名、自定义设置与绝对链接拼接能力;k.site.webSite 用于只读查看站点开关状态。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
makeAbsUrl(relativePath) | relativePath: string | string | 基于当前站点 baseUrl 拼接完整绝对地址 |
updateSetting(key, value) | key: string, value: string | void | 写入并保存站点 CustomSettings 键值对 |
removeSetting(key) | key: string | void | 移除站点 CustomSettings 中的指定键 |
setDomain(fulldomain) | fulldomain: string | void | 为当前站点绑定域名(仅管理脚本按需调用) |
enableSsl(fulldomain) | fulldomain: string | void | 为指定已绑定域名启用 SSL(仅管理脚本按需调用) |
返回值:对应属性或方法返回站点上下文数据(配置/域名变更方法返回 void)
k.api.get(() => {
const info = k.site.info
const site = k.site.webSite
const domains = []
if (info.domains) {
for (const d of info.domains) {
domains.push(d)
}
}
return {
name: info.name,
displayName: site.displayName,
defaultCulture: site.defaultCulture,
currentCulture: info.culture,
baseUrl: info.baseUrl,
host: info.host,
version: info.version,
domains,
absApiUrl: info.makeAbsUrl("/api/health")
}
})settings
通过配置键名读取站点系统核心设置(支持 .get(name) 或下标访问);未识别的配置键名返回 null。
| 方法 / 访问 | 参数 | 返回值 | 说明 |
|---|---|---|---|
get(name) | name: string | any | null | 按名称读取站点内置配置对象 |
[key] | key: string | any | null | 通过索引访问读取站点内置配置对象 |
返回值:配置对象或 null
k.api.get(() => {
const missing = k.site.settings.get("nonexistent-setting-key")
const jwtByGet = k.site.settings.get("JwtSetting")
const jwtByIndex = k.site.settings["JwtSetting"]
return {
missingIsNull: missing === null || missing === undefined,
jwtSettingName: jwtByGet ? jwtByGet.name : null,
sameName: jwtByIndex ? jwtByIndex.name === jwtByGet?.name : false
}
})multilingual
读取当前语言与站点已启用的语言映射,并生成多语言 URL;注意 currentURLs() 与 getURLs() 返回项上的地址属性为大写的 URL。
| 成员 | 参数 | 返回值 | 说明 |
|---|---|---|---|
currentCulture | — | string | 当前请求命中的语言代码(如 "zh"、"en") |
cultures | — | Record<string, string> | null | 站点配置的语言字典(如 { en: "English", zh: "中文" }) |
currentURLs() | 无 | SiteMultilingualInfo[] | 返回当前请求 URL 在各语言下的映射信息数组 |
getURLs(relativeUrl) | relativeUrl: string | SiteMultilingualInfo[] | 计算指定相对路径在全部站点语言下的地址列表 |
getLangUrl(relativeUrl, culture) | relativeUrl: string, culture: string | string | 生成指定目标语言的跳转地址 |
getUrl(relativeUrl) | relativeUrl: string | string | 按当前请求语言格式化相对路径 |
返回值:对应语言代码、URL 字符串或 SiteMultilingualInfo[]
k.api.get(() => {
const m = k.site.multilingual
return {
currentCulture: m.currentCulture,
cultures: m.cultures,
currentURLs: m.currentURLs().map((u) => ({
key: u.key,
name: u.name,
URL: u.URL,
isActive: u.isActive
})),
aboutEn: m.getLangUrl("/about", "en"),
aboutCurrent: m.getUrl("/about")
}
})search
提供全站索引查询 findAll(keyword, options?) 与自定义目录 Lucene 索引 on(folderName):
- 全站搜索:在站点启用全文检索后返回匹配结果列表(关键词为空时返回空列表;结果集需用
for...of遍历)。 - 自定义全文索引:返回独立目录索引器
KFullTextSearch,适合为自定义业务数据建索引并按关键词召回文档。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
findAll(keyword, options?) | keyword: string, options?: SearchOptions | SearchResult[] | 全站全文检索(返回可迭代集合) |
on(folderName) | folderName: string | KFullTextSearch | 打开隔离目录自定义全文索引器 |
返回值:SearchResult[](可迭代集合)或 KFullTextSearch
k.api.get(() => {
const hits = k.site.search.findAll("kooboo", {
maxCount: 5,
includeObject: false,
highlightPreTag: "<b>",
highlightPostTag: "</b>",
fragmentMaxSize: 100
})
const results = []
for (const item of hits) {
results.push({ title: item.title, url: item.url, scope: item.scope })
}
return { count: results.length, results }
})自定义目录全文索引(search.on(folderName)):
k.api.post(() => {
const fts = k.site.search.on("products_fts")
fts.addDocument("sku-100", "kooboo modular cms routing")
const found = fts.findAll("routing", 10)
const firstKey = found.scoreDocs.length ? fts.getMetaKey(found.scoreDocs[0].doc) : null
fts.deleteDocument("sku-100")
return {
totalHits: found.totalHits,
firstKey
}
})score 与 scope 字段差异
全站检索 k.site.search.findAll(...) 返回的 SearchResult 使用 scope 表示相关度分数;而自定义 Lucene 索引 k.site.search.on(folderName).findAll(keyword, top) 返回 Lucene TopDocs,其 scoreDocs 元素属性为 doc 与 score(不是 scope)。
version
根据当前站点的浏览器缓存配置为静态资源 URL 附加版本号查询参数;当对应缓存开关未开启(或图片设置了 imageCacheDays > 0)时,原样返回输入路径。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
imageVersionSrc(imgSrc) | imgSrc: string | string | 仅当开启图片浏览器缓存且 imageCacheDays <= 0 时附加版本参数 |
jsVersionSrc(src) | src: string | string | 开启 JS/CSS 浏览器缓存时为站内脚本附加版本参数 |
cssVersionSrc(src) | src: string | string | 开启 JS/CSS 浏览器缓存时为站内样式附加版本参数 |
返回值:string
k.api.get(() => {
const v = k.site.version
return {
img: v.imageVersionSrc("/logo.png"),
js: v.jsVersionSrc("/app.js"),
css: v.cssVersionSrc("/site.css")
}
})diskSpace
统计站点各数据仓库及总体磁盘占用(注意 getSiteSize().repositorySize 返回可迭代集合,请使用 for...of 遍历;getCommonStoreSize() 返回前 8 大 ICoreObject 核心仓库数组 storeItem 及仓库加编辑日志的汇总大小,其中的 visitorLogSize 字段当前未使用,恒为 null)。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
getSiteSize() | 无 | { total, repositoryEditCount, repositorySize } | 统计仓库字节占用与变更次数 |
getCommonStoreSize() | 无 | { storeItem, visitorLogSize, totalSize, total } | 返回前 8 大 ICoreObject 仓库与活跃仓库+编辑日志总占用;visitorLogSize 当前未使用(恒为 null) |
返回值:磁盘空间统计对象
k.api.get(() => {
const size = k.site.diskSpace.getSiteSize()
const common = k.site.diskSpace.getCommonStoreSize()
let repoCount = 0
for (const _ of size.repositorySize) {
repoCount++
}
return {
totalBytes: size.total,
repoCount,
editCount: size.repositoryEditCount,
totalSizeText: common.totalSize,
topStores: common.storeItem.map((s) => ({
name: s.name,
itemCount: s.itemCount,
sizeString: s.sizeString
}))
}
})helper
生成站点根路径以及指定页面的预览链接与内联编辑链接(页面不存在时返回 null)。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
siteUrl() | 无 | string | 返回当前站点根地址 |
pagePreviewUrl(pageId) | pageId: string | string | null | 生成指定页面预览地址 |
pageInlineEditUrl(pageId) | pageId: string | string | null | 生成指定页面在线编辑跳转地址 |
返回值:string 或 null
k.api.get(() => {
const h = k.site.helper
const pages = k.site.pages.all()
const pageId = pages.length ? String(pages[0].id) : ""
return {
siteUrl: h.siteUrl(),
previewUrl: pageId ? h.pagePreviewUrl(pageId) : null,
inlineEditUrl: pageId ? h.pageInlineEditUrl(pageId) : null
}
})TypeScript 定义
展开完整 TypeScript 定义
interface InfoModel {
culture: string;
name: string;
setting: Record<string, string>;
user: UserModel;
baseUrl: string;
version: number;
domains: string[];
host: string;
page: Page | null;
makeAbsUrl(relativePath: string): string;
updateSetting(key: string, value: string): void;
removeSetting(key: string): void;
enableSsl(fulldomain: string): void;
setDomain(fulldomain: string): void;
}
interface WebSiteInspection {
readonly id: string;
readonly name: string;
readonly displayName: string;
readonly defaultCulture: string;
readonly culture: Record<string, string>;
readonly published: boolean;
readonly status: any;
readonly enableMultilingual: boolean;
readonly enableSitePath: boolean;
readonly enableFrontEvents: boolean;
readonly enableFullTextSearch: boolean;
readonly enableImageBrowserCache: boolean;
readonly imageCacheDays: number;
readonly enableJsCssBrowerCache: boolean;
readonly ssoLogin: boolean;
}
interface kCoreSettings {
get(name: string): any;
[key: string]: any;
}
interface SiteMultilingualInfo {
key: string;
name: string;
URL: string;
isActive: boolean;
}
interface Multilingual {
currentCulture: string;
cultures: Record<string, string> | null;
currentURLs(): SiteMultilingualInfo[];
getURLs(relativeUrl: string): SiteMultilingualInfo[];
getLangUrl(relativeUrl: string, culture: string): string;
getUrl(relativeUrl: string): string;
}
interface SearchOptions {
highlightPreTag?: string;
highlightPostTag?: string;
folders?: string[];
skipCount?: number;
maxCount?: number;
fragmentMaxSize?: number;
includeObject?: boolean;
}
interface SearchResult {
id: string;
type: string;
title: string;
object: any;
summary: string;
url: string;
additional: Record<string, any>;
scope: number;
}
interface KFullTextSearch {
addDocument(metaKey: string, body: string): void;
deleteDocument(metaKey: string): void;
deleteDocuments(): void;
findAll(keyword: string, top: number): { totalHits: number; scoreDocs: { doc: number; score: number }[] };
getMetaKey(doc: number): string;
}
interface FileVersion {
imageVersionSrc(imgSrc: string): string;
jsVersionSrc(src: string): string;
cssVersionSrc(src: string): string;
}
interface DiskSpace {
getSiteSize(): {
total: number;
repositoryEditCount: number;
repositorySize: { name: string; length: number; itemCount: number }[];
};
getCommonStoreSize(): {
storeItem: { name: string; itemCount: number; size: number; sizeString: string }[];
/** 当前实现未赋值,恒为 null */
visitorLogSize: string | null;
totalSize: string;
total: number;
};
}
interface SiteHelper {
siteUrl(): string;
pagePreviewUrl(pageId: string): string | null;
pageInlineEditUrl(pageId: string): string | null;
}