LayoutRouter（路由器）

LayoutRouter 用于在带有层级目录结构的页面之间进行导航，并管理历史记录、查询参数以及页面过渡动画。它取代了早期的线性 PageRouter，并与 Layout、Page 组件共同构建树状的路由体系。

import { useRouter } from "narraleaf-react";
 
const router = useRouter();

基本导航

// 绝对路径导航
router.navigate("/home");
 
// 携带查询参数
router.navigate("/user/profile", { tab: "info" });
 
// 相对路径导航
router.navigate("./detail");
 
// 历史纪录控制
router.back();
router.forward();
 
// 替换当前路径而不新增历史
router.replace("/settings");
 
// 清除当前页面与历史
router.clear();
 
// 保留当前页面但清空历史
router.cleanHistory();

查询参数

router.setQueryParam("lang", "zh-CN");
router.getQueryParam("lang"); // "zh-CN"
router.removeQueryParam("lang");
 
router.setQueryParams({ tab: "general", theme: "dark" });
router.clearQueryParams();

路径工具

方法	说明
`resolvePath(path)`	解析相对路径（如 `../parent`）为绝对路径
`matchPath(path, pattern)`	支持 `*` 与 `:param` 的前缀匹配
`exactMatch(path, pattern)`	与 `matchPath` 类似，但需要完全相同的段数
`extractParams(path, pattern)`	从匹配的路径中提取动态参数

状态检查

router.getCurrentPath();   // "/user/profile"
router.getCurrentQuery();  // { tab: "info" }
router.getCurrentUrl();    // "/user/profile?tab=info"
 
router.getHistory();       // ["/home", "/user/profile"]
router.canGoBack();
router.canGoForward();

事件

// 页面挂载完成
router.onPageMount(() => {
  console.log("页面已挂载");
});
 
// 所有退出动画结束
router.onExitComplete(() => {
  console.log("退出动画完成");
});

与 Layout & Page 搭配示例

import { RouterProvider, RootLayout, Layout, Page } from "narraleaf-react";
 
function MyPages() {
  return (
    <RouterProvider>
      <RootLayout>
        {/* /home */}
        <Layout name="home">
          {/* 默认页面：/home */}
          <Page name={null}>
            <Home />
          </Page>
 
          {/* /home/detail */}
          <Page name="detail">
            <Detail />
          </Page>
        </Layout>
 
        {/* /about */}
        <Layout name="about">
          <Page name={null}>
            <About />
          </Page>
        </Layout>
      </RootLayout>
    </RouterProvider>
  );
}

公共方法

navigate

导航到新路径。

path: string – 目标路径，可为绝对或相对
queryParams?: Record<string,string> – 可选查询参数
return: this

router.navigate("/about");

back

返回上一条历史记录（如果存在）。

return: this

forward

前进到下一条历史记录（如果存在）。

return: this

replace

替换当前路径，不新增历史记录。

path: string – 新路径
queryParams?: Record<string,string> – 可选查询参数
return: this

clear

清除当前路径与历史。

return: this

cleanHistory

保留当前路径，清空其他历史记录。

return: this

getCurrentPath / getPathname

获取当前路径（不含查询字符串）。

return: string

getCurrentQuery / getQueryParams

获取当前查询参数对象。

return: Record<string,string>

getCurrentUrl

获取当前完整 URL（路径 + 查询）。

return: string

setQueryParam

设置单个查询参数。

key: string
value: string
return: this

setQueryParams

批量合并查询参数。

params: Record<string,string>
return: this

getQueryParam

获取指定查询参数。

key: string
return: string | undefined

removeQueryParam

删除指定查询参数。

key: string
return: this

clearQueryParams

清除所有查询参数。

return: this

hasQueryParam

判断是否存在指定查询参数。

key: string
return: boolean

getQueryParamKeys

获取所有查询参数键。

return: string[]

getQueryParamCount

获取查询参数数量。

return: number

getHistory

获取完整历史记录。

return: string[]

getHistoryIndex

获取当前历史索引。

return: number

canGoBack / canGoForward

检查是否可以后退 / 前进。

return: boolean

parseUrl

解析 URL 字符串为 { path, query }。

url: string
return: { path:string; query:Record<string,string>; }

buildUrl

使用路径和查询对象生成完整 URL。

path: string
query: Record<string,string>
return: string

resolvePath

解析相对路径为绝对路径。

path: string
return: string

normalizePath

规范化路径，去除重复或结尾斜杠。

path: string
return: string

joinPath

拼接多个路径段并规范化。

path: string – 基础路径
...paths: string[] – 其他路径段
return: string

parsePath

将路径拆分为段数组。

path: string
return: string[]

buildPath

从段数组生成路径字符串。

segments: string[]
return: string

getParentPath

获取父级路径。

path: string
return: string

matchPath

按前缀匹配路径，支持 * 与 :param。

path: string
pattern: string
return: boolean

exactMatch

精确匹配路径（段数要求一致）。

path: string
pattern: string
return: boolean

extractParams

根据模式提取路径参数。

path: string
pattern: string
return: Record<string,string>

onExitComplete / onceExitComplete

注册退出动画完成时的回调。

handler: () => void
return: LiveGameEventToken

onPageMount / oncePageMount

注册页面挂载时的回调。

handler: () => void
return: LiveGameEventToken

页面路由布局