跳转到正文
开发指南版本 6.0.0

路由、菜单与权限 ​

在 apps/admin/src/router/modules 写默认导出的路由模块。模板递归收集文件,按 meta.order 排序;路由树用于菜单与面包屑,页面记录展开后注册到 Vue Router。默认使用 hash 路由,例如 /ray-template/#/orders。

路由配置交互校验 ​

修改路径、名称或页面 ID,查看共享校验器的结果。示例注册了 overview 页面。

有效路由 / Valid routes: 1
查看示例源码
vue
<template>
  <div class="ray-demo ray-demo-fields">
    <div>
      <label :for="id">路由配置 / Route configuration</label>
      <textarea
        :id="id"
        v-model="source"
        rows="8"
        spellcheck="false"
        :aria-invalid="result.invalid"
      />
      <output class="ray-demo-result">{{ result.message }}</output>
    </div>
  </div>
</template>

<script setup lang="ts">
import { createRouteContract } from '@ray-template/routing'
import { computed, ref, useId } from 'vue'

const load = async () => ({})
const { parseRouteConfig } = createRouteContract({
  layout: load,
  homePath: '/overview',
  managementPath: '/route-management',
  findRouteView: (view) =>
    view === 'overview' ? { name: 'Overview', load } : void 0,
  findRouteViewId: (candidate) => (candidate === load ? 'overview' : void 0),
})
const id = useId()
const source = ref(
  JSON.stringify(
    {
      version: 1,
      routes: [
        {
          path: '/overview',
          component: 'overview',
          name: 'Overview',
          meta: {},
        },
      ],
    },
    null,
    2,
  ),
)
const result = computed(() => {
  try {
    const { routes } = parseRouteConfig(source.value)

    return {
      invalid: false,
      message: `有效路由 / Valid routes: ${routes.length}`,
    }
  } catch (error) {
    return {
      invalid: true,
      message: error instanceof Error ? error.message : String(error),
    }
  }
})
</script>

<style scoped>
textarea {
  width: 100%;
  padding: 10px;
  border: 1px solid var(--vp-c-divider);
  border-radius: 6px;
  background: var(--vp-c-bg);
  font-family: var(--vp-font-family-mono);
  resize: vertical;
}
</style>

常用元数据 ​

字段作用
i18nKey / noLocalTitle使用翻译键,或提供不经翻译的菜单标题
icon使用完整分包图标名,也接受 VNode
role同时影响菜单与守卫;角色值类型要和会话一致
hidden、env控制菜单显隐;不充当接口或路由权限
sameLevel详情页可保留当前菜单与标签,只在面包屑补充层级
keepAlive允许页面加入内容区的缓存
windowOpen菜单点击时打开指定地址。
ignoreAutoResetScroll允许页面保留内容区滚动位置,详见滚动工具实现。
extra菜单标记的文本、图标、类型和显隐,见 useBadge。

嵌套子路由使用相对路径时会继承父路径。内置示例按用途分组,并以绝对路径保留原有页面地址。查看 布局与路由示例 里的分组及多级菜单。

登录和角色 ​

默认登录页为 /。守卫启用时,无会话会返回登录页;有会话时按白名单、角色和应用首页决定导航。菜单隐藏的页面仍可能允许直达。接入真实业务时,在后端校验会话、权限和资源归属。

KeepAlive 排查 ​

  1. 路由设置 meta.keepAlive: true,并为它配置唯一 name。
  2. TSX 的 defineComponent({ name }) 或 SFC 的组件名应与路由名一致。检查懒加载模块是否导出了预期组件。
  3. 从菜单进入,改变页内状态,切到另一个标签再返回;随后检查关闭标签、直达和刷新是否符合预期。KeepAlive 不跨浏览器刷新保留组件实例。
  4. 替换布局的默认内容插槽后,应用接入方需要自行保留需要的路由渲染和缓存逻辑。

路由契约 · 守卫实现