Skip to content

k.site.routes ​

站点路由(Route)的查询、修改路径与创建路由别名

适用上下文前置条件典型用途
KScript API / 服务端脚本当前站点上下文;makeAlias 要求源路由已存在按 URL 或对象 ID 反查路由、迁移路由路径与创建 URL 别名

快速上手 ​

查询全站路由数、首页路由,以及首个页面对应的路由信息:

js
k.api.get(() => {
    const allRoutes = k.site.routes.all()
    const homeRoute = k.site.routes.getByUrl("/")
    const page = k.site.pages.all()[0]
    const pageRoute = page ? k.site.routes.getByObjectId(page.id) : null

    return {
        routeCount: allRoutes.length,
        homeRouteId: homeRoute ? String(homeRoute.id) : null,
        firstPageRoute: pageRoute ? {
            name: pageRoute.name,
            destinationConstType: pageRoute.destinationConstType
        } : null
    }
})

方法速查 ​

方法 / 属性说明返回值
all()返回站点中所有已注册的路由记录Route[]
getByUrl(url)按 URL 路径(如 "/about")精确查找路由Route | null
getByNameOrId(nameOrId)按路由名称(URL)或 GUID id 查找路由Route | null
getByObjectId(objectId)按目标资源对象(页面、文件、样式等)的 id 查找路由Route | null
changeRoute(oldurl, newurl)将原路由路径改写为新路径void
makeAlias(url, alias)为已存在路由创建别名路由(destinationConstType === 15)Route

相关文档与控制台入口

API / 入口用途
k.site.routes查询站点路由、changeRoute 改写路径、makeAlias 创建路由别名
k.site.pages站点页面管理(updateRoute 等)
URL 与路由管理(CMS)在控制台管理站点 URL 路由与别名映射

注意事项

  • 调用 makeAlias(url, alias) 时,如果源路由 url 不存在,会直接抛出错误("Object reference not set to an instance of an object.")。建议先用 getByUrl(url) 确认源路由存在。
  • 别名路由会保存指向目标路由的引用关系(destinationConstType 为 15、objectId 为目标路由的 id)。当目标页面存在关联别名时,直接删除页面不会自动移除被引用的路由和别名,请在 URL 与路由管理 中清理不再使用的别名。
  • 比较 route.id 或 route.objectId 时请使用 String(...) 转换后再做等值比较。

详细方法 ​

all() / getByUrl() / getByNameOrId() / getByObjectId() ​

列出全站路由或按 URL、路由 ID、目标对象 ID 检索路由记录。

方法参数返回值说明
all()无Route[]返回站点中的所有路由记录
getByUrl(url)url: stringRoute | null按 URL 路径(如 "/about")查找路由
getByNameOrId(nameOrId)nameOrId: stringRoute | null按路由名称(URL)或路由 id 查找路由
getByObjectId(objectId)objectId: stringRoute | null按目标资源对象(如页面、文件、样式等)的 id 查找路由

返回值:Route[] 或 Route | null

js
k.api.get(() => {
    const route = k.site.routes.getByUrl("/about")
    return route
        ? { id: String(route.id), objectId: String(route.objectId), culture: route.culture }
        : { found: false }
})

changeRoute() 与 makeAlias() ​

变更已有路由 URL,或为已存在的目标路由创建别名路径。

方法参数返回值说明
changeRoute(oldurl, newurl)oldurl: string, newurl: stringvoid将原路由路径 oldurl 变更为 newurl
makeAlias(url, alias)url: string, alias: stringRoute为已有路由 url 创建别名路由 alias,返回的路由 destinationConstType 为 15、objectId 指向源路由 id

返回值:changeRoute() 返回 void;makeAlias() 返回新创建的 Route

js
k.api.post(() => {
    const oldUrl = k.request.form.oldUrl
    const newUrl = k.request.form.newUrl
    k.site.routes.changeRoute(oldUrl, newUrl)

    const updated = k.site.routes.getByUrl(newUrl)
    return {
        moved: !!updated && !k.site.routes.getByUrl(oldUrl),
        newName: updated?.name
    }
})

为已有路由创建别名(先确认源路由存在):

js
k.api.post(() => {
    const targetUrl = k.request.form.targetUrl
    const aliasUrl = k.request.form.aliasUrl
    const target = k.site.routes.getByUrl(targetUrl)
    if (!target) {
        return { error: "target route not found" }
    }

    const alias = k.site.routes.makeAlias(targetUrl, aliasUrl)
    return {
        aliasName: alias.name,
        destinationConstType: alias.destinationConstType,
        pointsToTarget: String(alias.objectId) === String(target.id)
    }
})

TypeScript 定义 ​

ts
interface RouteObjectRepository {
  all(): Route[];
  getByNameOrId(nameOrId: string): Route | null;
  getByUrl(url: string): Route | null;
  getByObjectId(objectId: string): Route | null;
  changeRoute(oldurl: string, newurl: string): void;
  makeAlias(url: string, alias: string): Route;
}

interface Route {
  id: string;
  name: string;
  objectId: string;
  destinationConstType: number;
  culture: string;
  parameters: Record<string, string>;
  getParameter(key: string): string | null;
  copy(): Route;
  creationDate: Date;
  lastModified: Date;
}

相关文档 ​