definePage 宏

definePage 是一个编译时宏，允许你在页面组件中声明路由配置，无需在单独的路由文件中手动定义。

基本用法

在页面组件的顶层直接调用 definePage，无需导入：

tsx
// src/pages/about.tsx
definePage({
  name: 'about',
  meta: {
    title: '关于我们',
    requiresAuth: false
  }
})

export default function About() {
  return <div>关于页面</div>
}

INFO

definePage 是编译时宏，构建时会被自动移除，不会出现在运行时代码中。你不需要手动导入它。

支持的配置项

definePage 支持以下配置项：

name

自定义路由名称，用于编程式导航。优先级高于基于路径自动生成的名称。

tsx
definePage({
  name: 'user-detail'
})

meta

路由元数据，必须是 JSON 可序列化的对象。常用于存储页面标题、权限标记等信息。

tsx
definePage({
  meta: {
    title: '用户详情',
    requiresAuth: true,
    order: 1
  }
})

pattern

动态参数的匹配约束，值为正则表达式对象。

tsx
definePage({
  pattern: {
    id: /^d+$/ // id 参数只匹配数字
  }
})

redirect

路由重定向配置，支持字符串或配置对象：

tsx
// 字符串形式 — 重定向到指定路径
definePage({
  redirect: '/new-about'
})

// 配置对象形式 — 重定向并携带参数
definePage({
  redirect: {
    index: 'user-detail',
    params: { id: 'default' }
  }
})

alias

路由别名，支持字符串或字符串数组：

tsx
definePage({
  alias: '/info'
})

// 多个别名
definePage({
  alias: ['/info', '/company']
})

注意事项

WARNING

meta 的值必须是 JSON 可序列化的对象。不支持函数、Date、RegExp 等非序列化类型。pattern 中的正则表达式是例外，它们由 AST 解析器单独处理。

WARNING

definePage 必须在组件的顶层调用，不能放在条件语句、循环或函数内部。以下写法是错误的：

tsx
// ❌ 错误：不能在条件语句中调用
if (someCondition) {
  definePage({ name: 'conditional' })
}

// ❌ 错误：不能在函数中调用
function setup() {
  definePage({ name: 'dynamic' })
}

完整示例

tsx
// src/pages/custom-route.tsx
definePage({
  name: 'custom-route-demo',
  meta: {
    title: '自定义路由配置示例',
    requiresAuth: true,
    order: 1
  },
  pattern: {
    id: /^d+$/
  },
  alias: '/demo'
})

export default function CustomRoute() {
  return (
    <div>
      <h1>自定义路由页面</h1>
      <p>此页面使用了 definePage 宏配置路由</p>
    </div>
  )
}