Skip to content

k.site 上下文与内置工具 ​

当前站点信息、只读配置快照、多语言链接、全文检索、资源版本号、磁盘统计与页面辅助链接

适用上下文前置条件典型用途
KScript API / KView / 服务端脚本当前站点上下文(search.findAll 需站点开启全文检索)读取站点配置与域名、生成多语言/资源版本链接、执行全文检索与统计磁盘占用

快速上手 ​

一次读取当前站点名称、语言、基础地址、默认语言配置与磁盘空间占用:

js
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: stringstring基于当前站点 baseUrl 拼接完整绝对地址
updateSetting(key, value)key: string, value: stringvoid写入并保存站点 CustomSettings 键值对
removeSetting(key)key: stringvoid移除站点 CustomSettings 中的指定键
setDomain(fulldomain)fulldomain: stringvoid为当前站点绑定域名(仅管理脚本按需调用)
enableSsl(fulldomain)fulldomain: stringvoid为指定已绑定域名启用 SSL(仅管理脚本按需调用)

返回值:对应属性或方法返回站点上下文数据(配置/域名变更方法返回 void)

js
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: stringany | null按名称读取站点内置配置对象
[key]key: stringany | null通过索引访问读取站点内置配置对象

返回值:配置对象或 null

js
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: stringSiteMultilingualInfo[]计算指定相对路径在全部站点语言下的地址列表
getLangUrl(relativeUrl, culture)relativeUrl: string, culture: stringstring生成指定目标语言的跳转地址
getUrl(relativeUrl)relativeUrl: stringstring按当前请求语言格式化相对路径

返回值:对应语言代码、URL 字符串或 SiteMultilingualInfo[]

js
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")
    }
})

提供全站索引查询 findAll(keyword, options?) 与自定义目录 Lucene 索引 on(folderName):

  • 全站搜索:在站点启用全文检索后返回匹配结果列表(关键词为空时返回空列表;结果集需用 for...of 遍历)。
  • 自定义全文索引:返回独立目录索引器 KFullTextSearch,适合为自定义业务数据建索引并按关键词召回文档。
方法参数返回值说明
findAll(keyword, options?)keyword: string, options?: SearchOptionsSearchResult[]全站全文检索(返回可迭代集合)
on(folderName)folderName: stringKFullTextSearch打开隔离目录自定义全文索引器

返回值:SearchResult[](可迭代集合)或 KFullTextSearch

js
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)):

js
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: stringstring仅当开启图片浏览器缓存且 imageCacheDays <= 0 时附加版本参数
jsVersionSrc(src)src: stringstring开启 JS/CSS 浏览器缓存时为站内脚本附加版本参数
cssVersionSrc(src)src: stringstring开启 JS/CSS 浏览器缓存时为站内样式附加版本参数

返回值:string

js
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)

返回值:磁盘空间统计对象

js
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: stringstring | null生成指定页面预览地址
pageInlineEditUrl(pageId)pageId: stringstring | null生成指定页面在线编辑跳转地址

返回值:string 或 null

js
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 定义
ts
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;
}

相关文档 ​