跳转到正文

布局与滚动 Hooks ​

本页 API 操作模板默认布局。替换布局内容或侧栏前,先确认插槽和布局实例仍在预期位置。

交互示例 ​

查看示例源码
tsx
import { RIcon } from '@/components'
import {
  useAppNavigation,
  useBadge,
  useContentScroll,
  useI18n,
  useMaximize,
  useSiderBar,
  useSiderScroll,
  useSpinning,
  useTheme,
  useVueRouter,
  useWatermark,
} from '@/hooks'
import { useMenuGetters, useRuntimeGetters, useSettingGetters } from '@/store'
import { useTimeoutFn } from '@vueuse/core'
import { NButton, NFlex, NInput, 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 { 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="9 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>
            ),
          )}
        </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?) 返回 isLayoutContentMaximized(isFullscreen 是同一状态的别名)、maximize(full, options?)、toggleFullscreen()。页面、标签菜单和退出按钮共享同一个 Pinia 状态。需要单独放大一个 DOM 元素时,使用 useElementFullscreen。

每次调用的 options 覆盖 defaults。支持 zIndex(默认 999)、backgroundColor、transition、scrollToOptions: { left?, top?, behavior? },以及 beforeEnter、enter、beforeExit、exit。前置回调先执行,完成回调在下一次 Vue 更新后执行,并非 CSS 动画完成事件。进入时可以调整滚动位置。连续切换只执行最新状态的完成回调;切到当前状态时直接返回。

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 ​

返回方法用途
openSpin() / closeSpin()开关布局内容区的加载动画,不改变应用全局 Spin。
reload(wait?)卸载当前内容后重新挂载,缺省等待 800ms。

内容区用细线进度与普通文本提示呈现加载;openSpin 持续超过 120ms 才显示,短操作不会闪烁,reload 则立即显示。只想表示请求未完成时调用 openSpin,并在 finally 用 closeSpin 关闭。reload 会丢失当前页面未持久化的本地状态;多次重载时,Runtime Store 只保留最后一次恢复计时。

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() 直接返回 scrollTo 函数。可传 (x, y?) 或 { top, left, behavior },例如 scrollContent({ top: 0, behavior: 'smooth' })。调用时读取 LAYOUT_CONTENT_REF,所以可以在 setup 创建,在事件触发时使用。没有挂载布局实例时不执行。

useSiderScroll ​

useSiderScroll() 返回同签名的函数,操作 LAYOUT_SIDER_REF。顶部模式、未挂载或侧栏已卸载时安全忽略。它滚动侧栏容器,不改变菜单选中项。

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 · useSpinning · useContentScroll · useSiderScroll