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: string | Route | null | 按 URL 路径(如 "/about")查找路由 |
getByNameOrId(nameOrId) | nameOrId: string | Route | null | 按路由名称(URL)或路由 id 查找路由 |
getByObjectId(objectId) | objectId: string | Route | 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: string | void | 将原路由路径 oldurl 变更为 newurl |
makeAlias(url, alias) | url: string, alias: string | Route | 为已有路由 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;
}