Skip to content
ReferenceVersion 6.0.2

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
tsx
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.

ts
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 ​

MethodPurpose
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.

ts
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.

ts
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