路由快速开始

@elfui/router 是 ElfUI Custom Element 的客户端路由。它负责维护 URL、选择匹配的页面组件，并通过 <elf-router-view> 将页面渲染出来。

安装

pnpm add @elfui/router

新建项目时，也可以让脚手架自动添加：

pnpm create elfui@beta my-app --router --install

创建一个小型应用

TIP

创建 src/router/index.ts。路由组件可以是元素标签名、Custom Element 构造函数，或懒加载函数。页面推荐使用懒加载函数，以便拆分页面包。

// src/router/index.ts
import { createRouter, createWebHistory } from "@elfui/router";

export const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: "/", name: "home", component: () => import("../pages/home-page") },
    {
      path: "/users/:id",
      name: "user",
      component: () => import("../pages/user-page"),
      props: true,
    },
    { path: "/:pathMatch(.*)*", name: "not-found", component: () => import("../pages/not-found-page") },
  ],
});

在挂载应用之前导入这个模块。createRouter() 会注册路由元素，并让 useRouter()、useRoute() 可以取得当前路由器。

// src/main.ts
import "./router";
import { createApp } from "@elfui/core";
import App from "./app";

createApp(App).mount("#app");

在应用外壳中放置链接与路由出口：

<!-- src/app.ts -->
<header>
  <elf-link to="/">首页</elf-link>
  <elf-link :to=${{ name: "user", params: { id: "42" } }}>我的资料</elf-link>
</header>

<main>
  <elf-router-view></elf-router-view>
</main>

访问 /users/42 时，路由器会加载 user-page 并在路由视图中渲染。设置 props: true 后，路由参数会作为 id 属性传给页面。

// src/pages/user-page.ts
import { defineComponent } from "@elfui/core";

export default defineComponent({
  props: { id: String },
  template: `<h1>User ${this.id}</h1>`,
});

等待首次导航

路由器创建后会立即开始首次导航。如果启动代码依赖首个匹配页面、守卫与懒加载模块都已经完成，可等待 isReady()：

import { createApp } from "@elfui/core";
import App from "./app";
import { router } from "./router";

await router.isReady();
createApp(App).mount("#app");

选择 history 模式

WARNING

createWebHistory() 使用 /users/42 这样的普通 URL；服务端必须把未知的应用路径回退到 index.html。createWebHashHistory() 使用 /#/users/42，无需静态托管平台配置重写规则。createMemoryHistory() 不会修改浏览器 URL，适合测试、类似 SSR 的宿主与嵌入式应用。

继续阅读路由配置，了解 base、匹配规则、嵌套路由与动态注册。