Skip to content

k.site.pages ​

站点页面的增删改查、路由 URL 与版本日志

概述 ​

k.site.pages 管理 Kooboo Page 资源(页面 HTML/布局占位、路由、版本)。与全局 k.page 不同:后者只改当前请求正在渲染页的 Meta,不负责站点页面仓库。

与 k.page 的区别

API用途
k.site.pages站点内所有页面的 CRUD、按 URL 查找
k.page当前页 setTitle / setMeta 等

TypeScript 定义(节选) ​

ts
interface PageRepository {
  add(page: PageInput): void;
  all(): Page[];
  get(nameOrId: string): Page | null;
  getByUrl(url: string): Page | null;
  update(page: Page): void;
  updateBody(nameOrId: string, body: string): void;
  delete(nameOrId: string): void;
  getUrl(id: string): string | null;
  getAbsUrl(id: string): string | null;
  getLogs(nameOrId: string): ChangeLog[] | null;
  getByLog(logId: number): Page | null;
  getUrls(nameOrId: string): Record<string, string>;
  updateRoute(id: string, url: string, culture?: string): void;
}

interface PageInput {
  name: string;
  body: string;
  url: string;
  layoutName?: string;
}

add() ​

创建页面并注册路由。未传 url 时默认 /{name}。

参数类型必填说明
page.namestring是页面名称(唯一)
page.bodystring是页面内容,可为 <layout> 占位结构
page.urlstring否访问路径,如 /about;未传时默认 /{name}
page.layoutNamestring否关联布局名称

返回: void。

ts
k.api.post(() => {
    const stamp = Date.now().toString()
    const name = "doc-check-" + stamp
    const url = "/doc-check-" + stamp

    k.site.pages.add({
        name,
        url,
        body: `<layout id="main"><placeholder id="Main"><h1>${name}</h1></placeholder></layout>`
    })

    const page = k.site.pages.getByUrl(url)
    return {
        created: !!page,
        id: page?.id,
        name: page?.name,
        url: page ? k.site.pages.getUrl(page.id) : null
    }
})

all() ​

返回站点全部页面对象数组。

参数: 无。

返回: Page[]。

ts
k.api.get(() => {
    const pages = k.site.pages.all()
    return { count: pages.length, names: pages.slice(0, 5).map((p) => p.name) }
})

get() ​

按 名称 或 Id(GUID 字符串)获取页面。

参数类型必填说明
nameOrIdstring是页面名称或 Id

返回: Page | null。

ts
k.api.get(() => {
    const page = k.site.pages.get("home")
    return page ? { id: page.id, name: page.name } : null
})

getByUrl() ​

按 路由 URL 获取页面(会解析路由别名)。

参数类型必填说明
urlstring是页面路由 URL

返回: Page | null。

ts
k.api.get(() => {
    const page = k.site.pages.getByUrl("/")
    return page ? { id: page.id, name: page.name } : null
})

update() ​

用完整页面对象更新(通常先 get / getByUrl 再改字段)。

参数类型必填说明
pagePage是修改后的完整页面对象

返回: void。

ts
k.api.post(() => {
    const stamp = Date.now().toString()
    const url = "/doc-upd-" + stamp
    k.site.pages.add({
        name: "doc-upd-" + stamp,
        url,
        body: "<layout id=\"main\"><placeholder id=\"Main\"><h1>v1</h1></placeholder></layout>"
    })

    const page = k.site.pages.getByUrl(url)
    page.body = "<layout id=\"main\"><placeholder id=\"Main\"><h1>v2</h1></placeholder></layout>"
    k.site.pages.update(page)

    const after = k.site.pages.getByUrl(url)
    return {
        verified: after?.body?.indexOf("v2") >= 0,
        snippet: after?.body?.substring(0, 80)
    }
})

updateBody() ​

仅更新 body 字段。

参数类型必填说明
nameOrIdstring是页面名称或 Id
bodystring是新页面主体 HTML

返回: void。

ts
k.api.post(() => {
    const stamp = Date.now().toString()
    const url = "/doc-body-" + stamp
    k.site.pages.add({
        name: "doc-body-" + stamp,
        url,
        body: "<h1>before</h1>"
    })

    const page = k.site.pages.getByUrl(url)
    k.site.pages.updateBody(page.id, "<h1>after</h1>")

    const after = k.site.pages.getByUrl(url)
    return {
        verified: after?.body?.indexOf("after") >= 0
    }
})

delete() ​

按名称或 Id 删除页面。

参数类型必填说明
nameOrIdstring是页面名称或 Id

返回: void。

WARNING

删除后请用 get(nameOrId) 确认;对已删页面调用 getByUrl 在部分站点上可能因路由残留触发运行时错误。

ts
k.api.post(() => {
    const stamp = Date.now().toString()
    const url = "/doc-del-" + stamp
    const name = "doc-del-" + stamp

    k.site.pages.add({ name, url, body: "<h1>del</h1>" })
    const before = k.site.pages.getByUrl(url)

    k.site.pages.delete(name)
    const after = k.site.pages.get(name)

    return {
        hadPage: !!before,
        deleted: !!before && !after
    }
})

getUrl() / getAbsUrl() ​

根据页面 Id 获取相对路径或绝对 URL。

方法参数返回说明
getUrl(id)id: string`stringnull`
getAbsUrl(id)id: string`stringnull`
ts
k.api.get(() => {
    const page = k.site.pages.all()[0]
    if (!page) return { error: "no pages" }
    return {
        id: page.id,
        relative: k.site.pages.getUrl(page.id),
        absolute: k.site.pages.getAbsUrl(page.id)
    }
})

getLogs() / getByLog() ​

getLogs 返回指定页面的变更日志;getByLog 按日志 Id 还原该版本对象。

方法参数返回说明
getLogs(nameOrId)nameOrId: string`ChangeLog[]null`
getByLog(logId)logId: number`Pagenull`
ts
k.api.get(() => {
    const page = k.site.pages.all()[0]
    if (!page) return { error: "no pages" }
    const logs = k.site.pages.getLogs(page.id)
    return { logCount: logs ? logs.length : 0 }
})

getUrls() ​

返回页面在各文化下的路由路径字典。

参数类型必填说明
nameOrIdstring是页面名称或 Id

返回: Record<string, string>。

ts
k.api.get(() => {
    const page = k.site.pages.all()[0]
    if (!page) return { error: "no pages" }
    return k.site.pages.getUrls(page.id)
})

updateRoute() ​

更新页面在指定文化下的路由路径。

参数类型必填说明
idstring是页面 Id
urlstring是新路径
culturestring否文化代码,默认站点主文化

返回: void。

ts
// 多语言站点中调整某语言下的 URL
k.api.post(() => {
    const page = k.site.pages.get("about")
    if (!page) return { error: "page not found" }
    k.site.pages.updateRoute(page.id, "/about-us", "en")
    return k.site.pages.getUrls(page.id)
})

Page 对象(常用字段) ​

字段类型说明
idstring页面 Id
namestring名称
bodystring页面主体
layoutNamestring布局名
url—通过 getUrl(id) 获取路由
onlineboolean是否上线
versionnumber版本号

相关文档 ​