Layout and Scrolling Hooks
These APIs operate on the template's default layout. Check layout slots and instances before replacing the content or sidebar.
Interactive example
View example source
import {
useAppNavigation,
useBadge,
useContentScroll,
useI18n,
useMaximize,
useSiderBar,
useSiderScroll,
useSpinning,
useTheme,
useVueRouter,
useWatermark,
} from '@/hooks'
import { useMenuGetters, useRuntimeGetters, useSettingGetters } from '@/store'
import { useMenuKeyboard } from '@ray-template/admin-shell'
import { useMenu } from '@ray-template/composables/useMenu'
import { RIcon } from '@ray-template/ui/icon'
import { useTimeoutFn } from '@vueuse/core'
import { NButton, NFlex, NInput, NMenu, NTag } from 'naive-ui'
import DemoPage from '../components/DemoPage'
import HookExample from '../hooks/HookExample'
export default defineComponent({
name: 'TemplateHooks',
setup() {
const { t } = useI18n('hooks')
const text = (key: string) => t<string>(key)
const { t: showcaseT } = useI18n('showcase')
const label = (key: string) => showcaseT<string>(key)
const { router } = useVueRouter()
const theme = useTheme()
const watermark = useWatermark()
const badge = useBadge()
const spinning = useSpinning()
const maximize = useMaximize()
const tags = useSiderBar()
const menuKeyboard = useMenuKeyboard(false)
const { menuRef, menuProps, showOption } = useMenu({
options: [
{ key: 'overview', label: () => text('menuOverview') },
{
key: 'reports',
label: () => text('menuReports'),
children: [
{ key: 'daily', label: () => text('menuDaily') },
{ key: 'monthly', label: () => text('menuMonthly') },
],
},
],
value: 'monthly',
expandedKeys: [],
})
const { navigationTo } = useAppNavigation()
const contentScrollTo = useContentScroll()
const siderScrollTo = useSiderScroll()
const settings = useSettingGetters()
const { getMenuTagOptions } = useMenuGetters()
const runtime = useRuntimeGetters()
const badgeLabel = ref('new')
const watermarkText = ref(settings.getWatermarkConfig.value.content)
const { start: stopSpinLater } = useTimeoutFn(spinning.closeSpin, 800, {
immediate: false,
})
onBeforeUnmount(spinning.closeSpin)
// 过渡期间组件仍可能渲染,操作目标保持为本示例页面。
const currentPath = router.currentRoute.value.path
const current = () => currentPath
const hasCurrentTag = computed(() =>
getMenuTagOptions.value.some((tag) => tag.fullPath === currentPath),
)
const example = (
name: string,
code: string,
children: () => JSX.Element,
) => (
<HookExample
name={name}
description={text(`descriptions.${name}`)}
code={code}
>
{children()}
</HookExample>
)
return () => (
<DemoPage
title={label('templateTitle')}
description={text('templateIntro')}
eyebrow={label('templateEyebrow')}
meta="10 Hooks"
>
<h2 class="r-demo-section-heading">{label('appearanceAndPage')}</h2>
<div class="r-hook-grid">
{example(
'useTheme',
`const { darkTheme, lightTheme, toggleTheme, syncSystemTheme, getAppTheme } = useTheme()\ntoggleTheme()\ngetAppTheme().themeLabel`,
() => (
<NFlex align="center">
<NTag>{theme.getAppTheme().themeI18nLabel}</NTag>
<NButton onClick={theme.darkTheme}>{text('dark')}</NButton>
<NButton onClick={theme.lightTheme}>{text('light')}</NButton>
<NButton onClick={theme.syncSystemTheme}>
{text('system')}
</NButton>
<NButton onClick={theme.toggleTheme}>{text('toggle')}</NButton>
</NFlex>
),
)}
{example(
'useSpinning',
`const { openSpin, closeSpin, reload } = useSpinning()\nopenSpin()\n// Call closeSpin() when work finishes.\nreload(800)`,
() => (
<NFlex>
<NButton
onClick={() => {
spinning.openSpin()
stopSpinLater()
}}
>
{text('spin')}
</NButton>
<NButton onClick={() => spinning.reload()}>
{text('reload')}
</NButton>
<NTag>{String(runtime.layoutContentSpinning.value)}</NTag>
</NFlex>
),
)}
{example(
'useMaximize',
`const { maximize, isLayoutContentMaximized, toggleFullscreen } = useMaximize()\nmaximize(true, { scrollToOptions: { top: 0 } })\nmaximize(false)`,
() => (
<NFlex align="center">
<NTag>{String(maximize.isLayoutContentMaximized.value)}</NTag>
<NButton onClick={maximize.toggleFullscreen}>
{text('maximize')}
</NButton>
</NFlex>
),
)}
</div>
<h2 class="r-demo-section-heading">{label('globalMarkers')}</h2>
<div class="r-hook-grid">
{example(
'useBadge',
`const { show, update, hidden } = useBadge()\nshow('/template-hooks', { label: 'new' })\nupdate('/template-hooks', { label: '3', type: 'warning' })\nhidden('/template-hooks')`,
() => (
<NFlex vertical>
<NInput
value={badgeLabel.value}
onUpdateValue={(value) => {
badgeLabel.value = value
}}
aria-label={text('badgeLabel')}
/>
<NFlex>
<NButton
onClick={() =>
badge.show(current(), { label: badgeLabel.value })
}
>
{text('show')}
</NButton>
<NButton
onClick={() =>
badge.update(current(), {
label: badgeLabel.value,
icon: <RIcon name="status/error" />,
type: 'warning',
})
}
>
{text('update')}
</NButton>
<NButton
onClick={() => badge.update(current(), { icon: void 0 })}
>
{text('clearIcon')}
</NButton>
<NButton onClick={() => badge.hidden(current())}>
{text('hide')}
</NButton>
</NFlex>
</NFlex>
),
)}
{example(
'useWatermark',
`const { setWatermarkContent, showWatermark, hiddenWatermark, toggleWatermark } = useWatermark()\nsetWatermarkContent('Ray Template')\nshowWatermark()`,
() => (
<NFlex vertical>
<NInput
value={watermarkText.value}
onUpdateValue={(value) => {
watermarkText.value = value
watermark.setWatermarkContent(value)
}}
aria-label={text('watermarkText')}
/>
<NFlex>
<NButton onClick={watermark.showWatermark}>
{text('show')}
</NButton>
<NButton onClick={watermark.hiddenWatermark}>
{text('hide')}
</NButton>
<NButton onClick={watermark.toggleWatermark}>
{text('toggle')}
</NButton>
</NFlex>
</NFlex>
),
)}
</div>
<h2 class="r-demo-section-heading">{label('navigationAndTabs')}</h2>
<div class="r-hook-grid">
{example(
'useAppNavigation',
`const { navigationTo } = useAppNavigation()\nawait navigationTo('/web-hooks', { query: { from: 'hooks' } })\n// A zero-based index navigates to the first child of that section.\nawait navigationTo(0)`,
() => (
<NFlex>
<NButton
onClick={() =>
navigationTo('/web-hooks', { query: { from: 'hooks' } })
}
>
{text('openWeb')}
</NButton>
<NButton onClick={() => navigationTo('/multi/multi-menu-one')}>
{text('openNested')}
</NButton>
<NButton onClick={() => navigationTo(0)}>
{text('firstMenu')}
</NButton>
</NFlex>
),
)}
{example(
'useSiderBar',
`const { close, closeAll, closeLeft, closeRight, closeOther, getCurrentTagIndex } = useSiderBar()\ncloseOther('/template-hooks')`,
() => (
<NFlex vertical>
<code>
{getMenuTagOptions.value
.map((tag) => tag.fullPath)
.join(' · ')}
</code>
<NFlex>
<NButton onClick={() => tags.closeOther(current())}>
{text('closeOther')}
</NButton>
<NButton
disabled={
!hasCurrentTag.value || !tags.checkCloseLeft(current())
}
onClick={() => tags.closeLeft(current())}
>
{text('closeLeft')}
</NButton>
<NButton
disabled={
!hasCurrentTag.value || !tags.checkCloseRight(current())
}
onClick={() => tags.closeRight(current())}
>
{text('closeRight')}
</NButton>
<NButton onClick={() => tags.close(current())}>
{text('closeCurrent')}
</NButton>
<NButton onClick={tags.closeAll}>{text('closeAll')}</NButton>
</NFlex>
</NFlex>
),
)}
{example(
'useMenu',
`const { menuRef, menuProps, showOption } = useMenu({
options: [
{ key: 'overview', label: 'Overview' },
{
key: 'reports',
label: 'Reports',
children: [
{ key: 'daily', label: 'Daily report' },
{ key: 'monthly', label: 'Monthly report' },
],
},
],
value: 'monthly',
expandedKeys: [],
})
// TSX
<NMenu ref={menuRef} {...menuProps} />
<NButton onClick={() => showOption('monthly')}>Reveal monthly report</NButton>`,
() => (
<NFlex vertical>
<nav
aria-label={text('menuExample')}
onKeydown={menuKeyboard.onKeydown}
>
<NMenu
ref={menuRef}
{...menuProps}
nodeProps={menuKeyboard.nodeProps}
/>
</nav>
<NFlex>
<NButton onClick={() => showOption('monthly')}>
{text('menuReveal')}
</NButton>
<NButton
disabled={menuProps.value === null}
onClick={() => (menuProps.value = null)}
>
{text('menuClear')}
</NButton>
</NFlex>
<code>
{t('menuState', {
selected: menuProps.value ?? '—',
expanded: menuProps.expandedKeys?.join(', ') || '—',
})}
</code>
</NFlex>
),
)}
</div>
<h2 class="r-demo-section-heading">{label('scrollControls')}</h2>
<div class="r-hook-grid">
{example(
'useContentScroll',
`const contentScrollTo = useContentScroll()\ncontentScrollTo({ top: 0, behavior: 'smooth' })\ncontentScrollTo(0, 300)`,
() => (
<NFlex>
<NButton
onClick={() =>
contentScrollTo({ top: 0, behavior: 'smooth' })
}
>
{text('contentTop')}
</NButton>
<NButton onClick={() => contentScrollTo(0, 300)}>
{text('content300')}
</NButton>
</NFlex>
),
)}
{example(
'useSiderScroll',
`const siderScrollTo = useSiderScroll()\nsiderScrollTo({ top: 0, behavior: 'smooth' })\nsiderScrollTo(0, 300)`,
() => (
<NFlex>
<NButton
disabled={settings.getLayoutConfig.value.mode === 'top'}
onClick={() => siderScrollTo({ top: 0, behavior: 'smooth' })}
>
{text('siderTop')}
</NButton>
<NButton
disabled={settings.getLayoutConfig.value.mode === 'top'}
onClick={() => siderScrollTo(0, 300)}
>
{text('sider300')}
</NButton>
</NFlex>
),
)}
</div>
</DemoPage>
)
},
})useMaximize
useMaximize(defaults?) returns isLayoutContentMaximized, its alias isFullscreen, maximize(full, options?), and toggleFullscreen(). The page, tab menu, and exit button use the same Pinia state. For a single DOM element, use useElementFullscreen.
Per-call options override defaults. Options include zIndex (default 999), backgroundColor, transition, scrollToOptions: { left?, top?, behavior? }, beforeEnter, enter, beforeExit, and exit. The before callbacks run first. Completion callbacks run on the next Vue update and are independent of CSS animation completion. Entering can adjust scroll position. For rapid toggles, only the latest state's completion callback runs. Selecting the current state returns immediately.
import { useMaximize } from '@/hooks'
export function useReportLayout() {
const { isLayoutContentMaximized, maximize } = useMaximize()
const expand = () => maximize(true, { scrollToOptions: { top: 0 } })
return { expand, collapse: () => maximize(false), isLayoutContentMaximized }
}useSpinning
| Method | Purpose |
|---|---|
openSpin() / closeSpin() | Toggle content-area loading independently of the app's global spinner. |
reload(wait?) | Remount the current address and keep other tabs' caches. Defaults to 800 ms. |
reloadWorkspace(wait?) | Remount the complete content area and release page instances for all tabs. |
Content loading uses a thin progress bar and text. openSpin only shows it after 120 ms to avoid flashes. reload displays it immediately. When indicating a pending request, call openSpin and pair it with closeSpin in finally. Reload loses unpersisted state on the current page. For repeated reloads, Runtime Store retains only the most recent restore timer.
import { useSpinning } from '@/hooks'
export function useLoadWithSpinner() {
const { openSpin, closeSpin } = useSpinning()
return async <T>(load: () => Promise<T>) => {
openSpin()
try {
return await load()
} finally {
closeSpin()
}
}
}useContentScroll
useContentScroll() returns a scrollTo function. Pass (x, y?) or { top, left, behavior }, for example scrollContent({ top: 0, behavior: 'smooth' }). It resolves LAYOUT_CONTENT_REF at call time, so it can be created in setup and used in an event handler. It is a no-op while the layout is unmounted.
useSiderScroll
useSiderScroll() returns a function with the same signature for LAYOUT_SIDER_REF. It is a no-op in top navigation mode or when the sidebar is unmounted. It scrolls the sidebar container and leaves menu selection alone.
import { useContentScroll, useSiderScroll } from '@/hooks'
export function useScrollShortcuts() {
const scrollContent = useContentScroll()
const scrollSider = useSiderScroll()
return {
toTop: () => scrollContent(0, 0),
toMenuTop: () => scrollSider(0, 0),
}
}useMaximize source · useSpinning source · useContentScroll source · useSiderScroll source