应用布局与状态
打开「布局实验室」或顶部设置抽屉里的「布局」页签,切换导航和工作区。桌面支持侧边 side、顶部 top、混合 mixed、右侧 right 和通栏分组 split 导航;混合模式把一级导航放在顶部,侧栏只显示当前分组的子菜单。宽度不超过 768px 时改用抽屉,保留原桌面偏好。
在线布局实验
在预览中切换导航方向、固定顶栏或内容宽度。预览使用 Ray Admin 的布局与设置组件,菜单和状态只在当前示例里生效。
查看示例源码
<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>配置工作区
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 后再承载内部滚动;单纯填充与滚动无需新增通用组件。用户管理页在桌面左右独立滚动;窄屏改为纵向页面滚动,组织树限制高度,表格保留局部横向滚动。