文件约定

文件路由的核心思想是：文件路径即路由路径。通过约定的文件命名规则，插件会自动将页面目录下的文件映射为路由配置。

基本规则

页面目录下的文件会根据路径和文件名自动生成对应的路由：

文件路径生成路由
index.tsx/
about.tsx/about
user/profile.tsx/user/profile
contact.tsx/contact

INFO

index 文件名会映射为目录的根路径，即 / 或父路径本身。

动态路由

使用方括号 [] 定义动态路由参数：

文件路径生成路由说明
user/[id].tsx/user/{id}必填参数
user/[id?].tsx/user/{id?}可选参数
  • [param] — 必填动态参数，匹配 /user/123、/user/abc 等
  • [param?] — 可选动态参数，同时匹配 /user 和 /user/123
tsx
// src/pages/user/[id].tsx
import { useRoute } from 'vitarx-router'

export default function UserDetail() {
  const route = useRoute()
  const userId = route.params.id
  return <div>用户 ID：{userId}</div>
}

命名视图

使用 @ 分隔符为同一路由定义多个命名视图：

文件路径视图名称说明
page.tsxdefault默认视图
page@sidebar.tsxsidebar侧边栏命名视图
page@header.tsxheader头部命名视图

同一路由路径下，page.tsx 和 page@sidebar.tsx 会合并为一个路由，分别对应 default 和 sidebar 视图：

tsx
// 生成的路由配置
{
  path: '/page',
  component: {
    default: PageDefault,
    sidebar: PageSidebar
  }
}

引用：命名视图需要配合 <RouterView name="sidebar" /> 使用，详见 布局路由。

路径策略

pathStrategy 配置项控制文件名到路由路径的转换方式：

策略文件名生成路径说明
kebab（默认）MyPage.tsx/my-page转换为 kebab-case
lowercaseMyPage.tsx/mypage转换为小写
rawMyPage.tsx/MyPage保持原样
ts
// vite.config.ts
VitarxRouter({
  pathStrategy: 'kebab' // 默认值
})

分组路由

目录名支持使用数字前缀来控制排序和分组：

目录名生成路径额外配置
1.admin//adminmeta: { order: 1 }
2.settings//settingsmeta: { order: 2 }

默认的分组解析器会提取数字前缀作为 meta.order，目录名作为路径。你也可以通过 groupParser 选项自定义解析逻辑：

ts
VitarxRouter({
  groupParser(dirName) {
    // dirName = '1.admin'
    const [order, name] = dirName.split('.')
    return {
      path: name, // 'admin'
      options: {
        meta: { order: Number(order) } // 1
      }
    }
  }
})

目录配置文件

每个目录下可以放置一个配置文件（默认为 _config.ts 或 _config.js），用于通过 definePage 宏为该目录对应的路由配置元信息。配置文件不会生成独立的路由节点，而是将选项注入到所属目录的父路由中。

ts
// src/pages/admin/_config.ts
definePage({
  meta: { requiresAuth: true }
})

上面的配置会将 meta.requiresAuth 注入到 /admin 路由节点上，效果等同于在路由表中手动配置：

ts
{ path: '/admin', meta: { requiresAuth: true }, children: [...] }

配置文件中支持 definePage 的所有选项：

ts
// src/pages/user/_config.ts
definePage({
  name: 'userGroup',
  meta: { requiresAuth: true, order: 1 },
  redirect: '/user/profile',
  alias: ['/u']
})

INFO

配置文件名可通过 configFileName 选项自定义，默认为 '_config'。配置文件必须是 .ts 或 .js 后缀。

完整示例

以下是一个完整的页面目录结构及其生成的路由：

text
src/pages/
├── index.tsx                  → /
├── about.tsx                  → /about
├── contact.tsx                → /contact
├── custom-route.tsx           → /custom-route
├── multi-view.tsx             → /multi-view (default 视图)
├── multi-view@sidebar.tsx     → /multi-view (sidebar 视图)
├── user/
│   ├── _config.ts             → 目录配置（meta: { requiresAuth: true }）
│   └── [id].tsx               → /user/{id}
├── post/
│   └── [slug].tsx             → /post/{slug}
├── users/
│   ├── index.tsx               → /users
│   ├── profile.tsx             → /users/profile
│   └── settings/
│       └── index.tsx           → /users/settings
└── admin/
    ├── _config.ts              → 目录配置（meta: { requiresAuth: true }）
    ├── _layout.tsx             → 布局组件
    ├── index.tsx               → /admin
    ├── users.tsx               → /admin/users
    └── posts.tsx               → /admin/posts

生成的路由配置大致如下：

ts
;[
  { path: '/', component: Index },
  { path: '/about', component: About },
  { path: '/contact', component: Contact },
  { path: '/custom-route', component: CustomRoute },
  {
    path: '/multi-view',
    component: { default: MultiView, sidebar: MultiViewSidebar }
  },
  { path: '/user/{id}', meta: { requiresAuth: true }, component: UserDetail },
  { path: '/post/{slug}', component: PostDetail },
  { path: '/users', component: UsersIndex },
  { path: '/users/profile', component: UserProfile },
  { path: '/users/settings', component: UserSettings },
  {
    path: '/admin',
    meta: { requiresAuth: true },
    component: AdminLayout,
    children: [
      { path: '/admin', component: AdminIndex },
      { path: '/admin/users', component: AdminUsers },
      { path: '/admin/posts', component: AdminPosts }
    ]
  }
]