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

应用布局与状态 ​

打开「布局实验室」或顶部设置抽屉里的「布局」页签,切换导航和工作区。桌面支持侧边 side、顶部 top、混合 mixed、右侧 right 和通栏分组 split 导航;混合模式把一级导航放在顶部,侧栏只显示当前分组的子菜单。宽度不超过 768px 时改用抽屉,保留原桌面偏好。

在线布局实验 ​

在预览中切换导航方向、固定顶栏或内容宽度。预览使用 Ray Admin 的布局与设置组件,菜单和状态只在当前示例里生效。

查看示例源码
vue
<template>
  <DemoFrame :dark="dark" :locale="locale">
    <div
      class="shell-demo"
      :class="{ 'r-template--dark': dark }"
      :lang="locale"
    >
      <AdminShell :layout="layout" :groupedSidebar="true" showTabs showFooter>
        <template #header>
          <div class="shell-bar">
            <strong>Ray Admin</strong>
            <NButton size="small" @click="dark = !dark">{{
              dark ? copy.light : copy.dark
            }}</NButton>
          </div>
          <ShellTopNavigation
            v-if="['top', 'mixed', 'split'].includes(layout.mode)"
            :items="menu"
            :active="active"
            :grouped="layout.mode !== 'top'"
            :label="copy.navigation"
            :select="(item) => navigate(item.fullPath)"
          />
        </template>
        <template #sidebar>
          <NLayoutSider :width="132" bordered>
            <NMenu :options="menu" :value="active" @update:value="navigate" />
          </NLayoutSider>
        </template>
        <template #tabs>
          <div class="shell-bar">
            <ShellTab
              v-for="item in pages"
              :key="item.path"
              :label="item.label"
              :active="active === item.path"
              :select="() => navigate(item.path)"
            />
          </div>
        </template>
        <h2>{{ title }}</h2>
        <LayoutSettings
          :layout="layout"
          :defaults="defaults"
          :translate="translate"
          :update="updateLayout"
        />
        <template #footer>
          <div class="shell-bar">{{ copy.footer }}</div>
        </template>
      </AdminShell>
    </div>
  </DemoFrame>
</template>

<script setup lang="ts">
import {
  AdminShell,
  LayoutSettings,
  ShellTab,
  ShellTopNavigation,
} from '@ray-template/admin-shell'
import type { LayoutConfig } from '@ray-template/admin-shell'
import { NButton, NLayoutSider, NMenu } from 'naive-ui'
import { computed, onMounted, ref } from 'vue'
import { createMemoryHistory, createRouter } from 'vue-router'
import DemoFrame from './DemoFrame.vue'

const props = withDefaults(defineProps<{ locale?: 'zh-CN' | 'en' }>(), {
  locale: 'zh-CN',
})
const copy = computed(() =>
  props.locale === 'en'
    ? {
        dashboard: 'Dashboard',
        reports: 'Reports',
        navigation: 'Navigation',
        light: 'Light theme',
        dark: 'Dark theme',
        footer: 'Layout preview',
        settings: 'Layout',
        side: 'Left',
        top: 'Top',
        mixed: 'Mixed',
        right: 'Right',
        split: 'Split',
        contentWidth: 'Content width',
        fluid: 'Fluid',
        fixed: 'Fixed',
        maxWidth: 'Maximum width',
        padding: 'Padding',
        fixedHeader: 'Fixed header',
        fixedFooter: 'Fixed footer',
        reset: 'Reset layout',
      }
    : {
        dashboard: '工作台',
        reports: '报表',
        navigation: '导航',
        light: '浅色主题',
        dark: '深色主题',
        footer: '布局预览',
        settings: '布局',
        side: '侧边导航',
        top: '顶部导航',
        mixed: '混合导航',
        right: '右侧导航',
        split: '通栏分组',
        contentWidth: '内容宽度',
        fluid: '流式铺满',
        fixed: '定宽居中',
        maxWidth: '最大宽度',
        padding: '内容间距',
        fixedHeader: '固定顶栏',
        fixedFooter: '固定页脚',
        reset: '恢复默认布局',
      },
)
const translate = (key: string) =>
  copy.value[(key === 'tab' ? 'settings' : key) as keyof typeof copy.value] ??
  key
const defaults: LayoutConfig = {
  mode: 'side',
  contentWidth: 'fluid',
  contentMaxWidth: 1200,
  contentPadding: 16,
  fixedHeader: true,
  fixedFooter: true,
}
const layout = ref({ ...defaults })
const updateLayout = (patch: Partial<LayoutConfig>) => {
  layout.value = { ...layout.value, ...patch }
}
const dark = ref(false)
const pages = computed(() => [
  { path: '/', label: copy.value.dashboard },
  { path: '/reports', label: copy.value.reports },
])
const router = createRouter({
  history: createMemoryHistory(),
  routes: pages.value.map(({ path }) => ({
    path,
    component: { render: () => null },
  })),
})
const active = computed(() => router.currentRoute.value.path)
const title = computed(
  () => pages.value.find(({ path }) => path === active.value)?.label,
)
const menu = computed(() =>
  pages.value.map(({ path, label }) => ({
    key: path,
    label,
    path,
    fullPath: path,
    name: path,
    meta: {},
  })),
)
const navigate = (path: string) => {
  void router.push(path)
}

onMounted(() => navigate('/'))
</script>

<style scoped>
.shell-demo {
  --html-height: 100dvh;
  --html-width: 100vw;
  --r-theme-primary-color: #3b63d9;
  color: var(--r-text);
}

.shell-bar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
  padding: 10px 12px;
  background: var(--r-surface);
  border-block-end: 1px solid var(--r-line);
}
</style>

配置工作区 ​

ts
import { useSettingActions } from '@/store'

const { updateSettingState } = useSettingActions()

updateSettingState('layoutConfig', {
  mode: 'mixed',
  contentWidth: 'fixed',
  contentMaxWidth: 1200,
  contentPadding: 24,
})

最大宽度范围是 640–2560px,间距为 0–48px。顶栏和页脚可固定或随内容滚动。设置抽屉默认使用舒适间距(24px),并提供紧凑和居中阅读预设,只调整内容宽度与间距,保留导航方式和固定栏配置。当前预设和实际间距会显示在预设区域;手动配置不匹配预设时显示「自定义间距」,不会覆盖已有设置。已有浏览器偏好继续沿用,恢复默认布局时应用新的默认间距。旧设置补齐默认值,布局恢复默认只重置 layoutConfig。

内容区最大化复用 useMaximize,关闭设置后可查看效果。窄屏的退出按钮固定悬浮在右上角,不占内容空间。点击按钮或按 Esc 即可恢复;最大化状态不随刷新保留。

外观页可批量显示或隐藏面包屑、页面标签和页脚,页面切换动画在「窗口与动效」中选择。各效果进入用时 240ms,退出用时 190ms,完整退出后再进入,并保留小幅位移和缩放。系统偏好减少动态效果时直接切换。恢复外观默认只重置外观选项,保留当前明暗模式。水印页提供疏朗、紧凑和水平预设、独立局部预览,以及应用标题和账户昵称快捷填入;无需开启全屏水印即可调试样式,预设保留已有文本和显隐状态。各模块的恢复按钮只作用于对应模块。

菜单图标 ​

展开侧栏、移动端抽屉和顶部导航默认使用 20 px 的图标;折叠侧栏默认 22 px,方便只凭图形辨认菜单。线性图标跟随菜单状态和明暗主题变色。可在「偏好设置 → 菜单」调整「图标尺寸」与「折叠图标尺寸」,修改即时生效。紧凑和舒适预设只调整宽度、缩进和图标尺寸;折叠方式、侧栏折叠/展开、回到菜单顶部和刷新菜单也可直接操作。当前布局没有桌面侧栏时,侧栏快捷操作禁用,已配置的尺寸仍会保留。

替换布局区域 ​

RLayout 提供 header、sidebar、tabs、footer 和 default 插槽。模式和显隐开关仍生效,例如顶部导航模式不会渲染侧栏。替换 default 内容时,需要自行接入所需的路由缓存和请求取消。

状态放在哪里 ​

状态入口刷新后的行为
加载、移动抽屉、内容最大化、重载useRuntimeGetters / useRuntimeActions运行态,不持久化
布局、主题、语言等偏好useSettingGetters / useSettingActions沿用设置缓存;旧值补默认配置
锁屏锁屏 Store保留历史布尔值格式和跨标签同步

通用页通过 updateLocale 同步界面、组件库和日期语言,提供刷新当前页面、回到内容顶部和缓存管理。可调整缓存上限,界面保留缓存管理规则的提示。清理缓存会释放非活动页面实例,当前页面继续保留,后续访问按缓存配置重新创建。刷新当前页面会重新挂载内容,未保存的页面输入可能丢失。通用模块恢复默认仅重置动态标题与缓存配置,保留语言、最近访问和收藏。

新增共享状态按职责放到 apps/admin/src/store/modules,对外用 Store hooks。持久化使用 pick / omit 选择字段;检查历史 key 和序列化格式再变更。

布局说明与插槽 · 状态实现与持久化

更细的状态字段与更新动作见 Setting Store、Runtime Store 和 布局 Hooks。

最近访问和收藏 ​

桌面搜索支持 Ctrl/Command + K。输入页面名称查找,点击星标收藏;空关键词时显示收藏与最近访问,方向键、回车和 Tab 可操作。记录按会话用户 id 隔离,刷新后恢复;清空记录保留收藏,也可在「偏好设置 → 通用」确认后清理当前账户的最近访问。缓存只存菜单路径,展示时重新依据当前菜单和权限筛选,语言切换沿用当前翻译。手机也可通过顶栏搜索按钮查询、收藏和打开页面;导航抽屉提供关闭按钮,切换屏幕宽度保留桌面侧栏的折叠偏好。

内容页需要撑满工作区时,先复用布局的 --layout-content-height、RTablePro autoHeight 和 --r-table-height,以及 Naive UI 的 NCard contentScrollable / NScrollbar。父容器提供确定高度,Flex/Grid 子项设置 min-block-size: 0 后再承载内部滚动;单纯填充与滚动无需新增通用组件。用户管理页在桌面左右独立滚动;窄屏改为纵向页面滚动,组织树限制高度,表格保留局部横向滚动。