跳转到正文

导航与菜单 ​

从 @/hooks 导入本页 API。菜单来源、权限和路由记录见路由指南。

交互示例 ​

查看示例源码
tsx
import {
  useAppNavigation,
  useBadge,
  useContentScroll,
  useI18n,
  useMaximize,
  useSiderBar,
  useSiderScroll,
  useSpinning,
  useTheme,
  useVueRouter,
  useWatermark,
} from '@/hooks'
import { useMenuGetters, useRuntimeGetters, useSettingGetters } from '@/store'
import { RIcon } from '@ray-template/ui/icon'
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>
    )
  },
})

useVueRouter ​

查看路由示例源码
tsx
import {
  useContextmenuCoordinate,
  useDayjs,
  useDevice,
  useDomToImage,
  useElementFullscreen,
  useI18n,
  usePagination,
  usePrint,
  useVueRouter,
} from '@/hooks'
import { useSettingActions } from '@/store'
import {
  NAlert,
  NButton,
  NDropdown,
  NFlex,
  NInput,
  NPagination,
  NTag,
  useThemeVars,
} from 'naive-ui'
import DemoPage from '../components/DemoPage'
import HookExample from './HookExample'

export default defineComponent({
  name: 'WebHooks',
  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 themeVars = useThemeVars()
    const device = useDevice()
    const dayjs = useDayjs()
    const { router } = useVueRouter()
    const { updateLocale: changeLocale } = useSettingActions()
    const [pagination, pages] = usePagination(void 0, {
      itemCount: 95,
      pageSize: 10,
    })
    const date = ref('2026-11-03')
    const dayRange = ref(dayjs.getStartAndEndOfDay())
    const target = ref<HTMLElement>()
    const fullscreen = useElementFullscreen(target)
    const capture = useDomToImage(target, { imageType: 'png', cacheBust: true })
    const printer = usePrint(target, { type: 'html', targetStyles: ['*'] })
    const image = ref('')
    const error = ref('')
    const busy = ref(false)
    const contextTarget = ref<HTMLElement>()
    const context = useContextmenuCoordinate(contextTarget)
    const contextStopped = ref(false)
    const selected = ref('')
    const rows = computed(() => {
      const start = (pages.getPage() - 1) * pages.getPageSize()

      return Array.from(
        {
          length: Math.min(
            pages.getPageSize(),
            Math.max(0, pages.getItemCount() - start),
          ),
        },
        (_, index) => start + index + 1,
      )
    })
    const createImage = async () => {
      busy.value = true
      error.value = ''

      try {
        image.value = await capture.create()
      } catch (cause) {
        error.value = cause instanceof Error ? cause.message : String(cause)
      } finally {
        busy.value = false
      }
    }
    const example = (
      name: string,
      code: string,
      children: () => JSX.Element,
    ) => (
      <HookExample
        name={name}
        description={text(`descriptions.${name}`)}
        code={code}
      >
        {children()}
      </HookExample>
    )

    return () => (
      <DemoPage
        title={label('webTitle')}
        description={text('webIntro')}
        eyebrow={label('webEyebrow')}
        meta="9 Hooks"
      >
        <h2 class="r-demo-section-heading">{label('commonUtilities')}</h2>
        <div class="r-hook-grid">
          {example(
            'useDevice',
            `const { width, height, isTabletOrSmaller } = useDevice({ media: 768 })\n// Refs update when the viewport changes; listeners are released with the scope.`,
            () => (
              <NFlex>
                <NTag>
                  {device.width.value} × {device.height.value}
                </NTag>
                <NTag>
                  {device.isTabletOrSmaller.value
                    ? text('smallScreen')
                    : text('desktop')}
                </NTag>
              </NFlex>
            ),
          )}
          {example(
            'usePagination',
            `const [pagination, { getPage, setPage, setPageSize, resetPagination }] = usePagination(loadRows, { itemCount: 95 })\n<NPagination {...pagination.value} />\n// Changing page size resets the page to 1.`,
            () => (
              <NFlex vertical>
                <NFlex>
                  {rows.value.map((row) => (
                    <NTag key={row}>#{row}</NTag>
                  ))}
                </NFlex>
                <div style="overflow-x: auto">
                  <NPagination {...pagination.value} />
                </div>
                <NFlex>
                  <NButton onClick={() => pages.setPage(2)}>
                    {text('pageTwo')}
                  </NButton>
                  <NButton onClick={() => pages.setPageSize(20)}>
                    {text('pageSize20')}
                  </NButton>
                  <NButton onClick={pages.resetPagination}>
                    {text('reset')}
                  </NButton>
                </NFlex>
              </NFlex>
            ),
          )}
          {example(
            'useDayjs',
            `const { format, daysDiff, isDateInRange, getStartAndEndOfDay, isDayjs, locale } = useDayjs()\nformat('2026-11-03', { format: 'YYYY/MM/DD' })\ndaysDiff('2026-11-01', '2026-11-03')\nisDateInRange('2026-11-03', { start: '2026-11-01', end: '2026-11-30' })`,
            () => (
              <NFlex vertical>
                <NInput
                  value={date.value}
                  onUpdateValue={(value) => {
                    date.value = value
                  }}
                  aria-label={text('date')}
                />
                <pre class="r-demo-code">
                  <code>
                    {JSON.stringify(
                      {
                        format: dayjs.format(date.value),
                        daysDiff: dayjs.daysDiff('2026-11-01', date.value),
                        inRange: dayjs.isDateInRange(date.value, {
                          start: '2026-11-01',
                          end: '2026-11-30',
                        }),
                        startOfDay: dayRange.value.formatStartOfDay,
                        endOfDay: dayRange.value.formatEndOfDay,
                      },
                      null,
                      2,
                    )}
                  </code>
                </pre>
                <NButton
                  onClick={() => {
                    dayRange.value = dayjs.getStartAndEndOfDay()
                  }}
                >
                  {text('refreshDate')}
                </NButton>
              </NFlex>
            ),
          )}
          {example(
            'useI18n',
            `const { t } = useI18n('hooks')\nt('webIntro')\nt('hooks.webIntro')\nconst { updateLocale } = useSettingActions()\nupdateLocale('en-US')`,
            () => (
              <NFlex vertical>
                <span>{text('webIntro')}</span>
                <NFlex>
                  <NButton onClick={() => changeLocale('zh-CN')}>
                    简体中文
                  </NButton>
                  <NButton onClick={() => changeLocale('en-US')}>
                    English
                  </NButton>
                </NFlex>
              </NFlex>
            ),
          )}
          {example(
            'useVueRouter',
            `const { router } = useVueRouter()\nrouter.currentRoute.value.fullPath\nrouter.replace({ path: '/web-hooks', query: { example: 'router' } })`,
            () => (
              <NFlex vertical>
                <code style="overflow-wrap: anywhere">
                  {router.currentRoute.value.fullPath}
                </code>
                <NFlex>
                  <NButton
                    onClick={() =>
                      router.replace({
                        path: '/web-hooks',
                        query: { example: 'router' },
                      })
                    }
                  >
                    {text('updateQuery')}
                  </NButton>
                  <NButton onClick={() => router.push('/template-hooks')}>
                    {text('openTemplate')}
                  </NButton>
                </NFlex>
              </NFlex>
            ),
          )}
        </div>
        <h2 class="r-demo-section-heading">{label('browserCapabilities')}</h2>
        <div
          ref={target}
          class="r-hook-capture-target"
          style={{ backgroundColor: themeVars.value.cardColor }}
        >
          <h2>Ray Template</h2>
          <p>{text('captureTarget')}</p>
          <p class="r-hook-capture-target__stack">
            Vue 3 · TypeScript · Naive UI
          </p>
          {fullscreen.isFullscreen.value ? (
            <NButton onClick={fullscreen.exit}>
              {text('exitFullscreen')}
            </NButton>
          ) : null}
        </div>
        <div class="r-hook-grid">
          {example(
            'useElementFullscreen',
            `const target = ref<HTMLElement>()\nconst { enter, exit, toggleFullscreen, isFullscreen } = useElementFullscreen(target)\n// CSS fullscreen: no browser permission required.\n<div ref={target} />`,
            () => (
              <NFlex align="center">
                <NTag>{String(fullscreen.isFullscreen.value)}</NTag>
                <NButton onClick={fullscreen.toggleFullscreen}>
                  {text('toggleElementFullscreen')}
                </NButton>
              </NFlex>
            ),
          )}
          {example(
            'useDomToImage',
            `const { create } = useDomToImage(target, { imageType: 'png' })\nconst png: string = await create()\nconst blob: Blob | null = await create('blob')`,
            () => (
              <NFlex vertical>
                <NButton loading={busy.value} onClick={createImage}>
                  {text('capture')}
                </NButton>
                {error.value ? (
                  <NAlert type="error">{error.value}</NAlert>
                ) : null}
                {image.value ? (
                  <img
                    src={image.value}
                    alt={text('capturePreview')}
                    style="max-width: 100%; height: auto"
                  />
                ) : null}
              </NFlex>
            ),
          )}
          {example(
            'usePrint',
            `const target = ref<HTMLElement>()\nconst { print } = usePrint(target, { type: 'html', targetStyles: ['*'] })\n// Call from a button click.`,
            () => (
              <NButton onClick={printer.print}>{text('print')}</NButton>
            ),
          )}
          {example(
            'useContextmenuCoordinate',
            `const { x, y, show, updateShow, stop } = useContextmenuCoordinate(target)\n<NDropdown show={show.value} x={x.value} y={y.value} trigger="manual" />\nstop() // Hides the menu and removes all listeners.`,
            () => (
              <NFlex vertical>
                <div
                  ref={contextTarget}
                  tabindex={0}
                  style="padding: 32px; border: 1px dashed var(--n-border-color)"
                  onKeydown={(event) => {
                    if (event.key === 'Escape') context.updateShow(false)
                  }}
                >
                  {text('rightClick')}
                </div>
                <code>
                  x: {context.x.value}, y: {context.y.value}, show:{' '}
                  {String(context.show.value)} {selected.value}
                </code>
                <NButton
                  disabled={contextStopped.value}
                  onClick={() => {
                    context.stop()
                    contextStopped.value = true
                  }}
                >
                  {contextStopped.value ? text('stopped') : text('stop')}
                </NButton>
                <NDropdown
                  show={context.show.value}
                  x={context.x.value}
                  y={context.y.value}
                  trigger="manual"
                  placement="bottom-start"
                  options={[
                    { key: 'copy', label: text('contextCopy') },
                    { key: 'inspect', label: text('contextInspect') },
                  ]}
                  onSelect={(key) => {
                    selected.value = String(key)
                    context.updateShow(false)
                  }}
                  onClickoutside={() => context.updateShow(false)}
                />
              </NFlex>
            ),
          )}
        </div>
      </DemoPage>
    )
  },
})

useVueRouter() 返回 { router },指向模板的共享 Vue Router 实例。当前路由用 router.currentRoute.value 读取,push、replace、back 等行为由 Vue Router 提供。它可在 setup 外取得实例。初始化后再访问依赖实际路由匹配的状态。

ts
import { useVueRouter } from '@/hooks'

export const readQuery = () => useVueRouter().router.currentRoute.value.query

useAppNavigation ​

useAppNavigation().navigationTo(target, options?) 支持三类目标:

target行为
完整路径字符串先用 Router 解析,保留动态路径、query 和 hash。未匹配或只匹配兜底路由时返回 undefined。
AppMenuOption按 fullPath 导航。
从 0 开始的整数从当前菜单取项,遇到父菜单沿第一个子项查到叶子。菜单需要先初始化。

NavigationToOptions.isPush 默认 true;设为 false 使用 router.replace。query 可覆盖字符串路径中的同名查询参数。成功发起时返回 Router Promise。负数、小数、非有限数和越界索引不会导航;实际结果仍受路由守卫影响。

ts
import { useAppNavigation } from '@/hooks'

export function useTableNavigation() {
  const { navigationTo } = useAppNavigation()
  return () =>
    navigationTo('/tables/remote?tab=people', {
      isPush: false,
      query: { tab: 'orders' },
    })
}

useAppRoot(兼容接口) ​

此接口已废弃,仅为旧调用方保留历史偏好的读写。getRootRoute、getRootPath、getRootName 是计算引用,setRootRoute({ name?, path? }) 合并更新该字段;它不再控制登录落点、标签保护或关闭全部后的导航,也没有启动时首页校验。空工作区固定使用 /welcome。新代码直接通过 Router 显式导航。

ts
import { useVueRouter } from '@/hooks'

export function useOpenWorkspace() {
  const { router } = useVueRouter()
  return () => router.replace('/welcome')
}

useSiderBar ​

操作工作区的标签页。接受 CloseMenuTag 的方法可传从 0 开始的索引、与标签 fullPath 匹配的字符串或标签对象。

方法行为
getCurrentTagIndex()当前标签索引;找不到返回 -1。
checkCloseLeft(target) / checkCloseRight(target)检查目标对应方向是否有标签可关。
close(target)关闭业务标签;激活项切到相邻项,最后一项关闭后进入空工作区。
closeLeft(target) / closeRight(target)关闭目标左侧或右侧标签。需要时切换至目标。
closeOther(target)只保留目标并激活。
closeAll()清空业务标签及其缓存,进入 /welcome,不依赖业务首页。

不要在存在未保存表单的工作流里直接调用批量关闭;这些方法不会替业务处理未保存确认。

ts
import { useSiderBar } from '@/hooks'

export function useCloseActiveTag() {
  const { close, getCurrentTagIndex } = useSiderBar()
  return () => {
    const index = getCurrentTagIndex()
    if (index >= 0) close(index)
  }
}

useBadge ​

目标接受菜单的 fullPath 或 AppMenuOption。show(target, options?) 合并配置并显示,hidden(target) 保留原配置并隐藏,update(target, options) 只更新给出的字段。菜单未加载或未找到时不会添加标记。

AppMenuExtraOptions 支持 label(字符串或数字)、i18nLabel(翻译键)、icon(VNode)、type(Naive UI Tag 类型)、show(显隐)。使用翻译键时同步维护语言包。

ts
import { useBadge } from '@/hooks'

export function useUnreadBadge() {
  const { show, hidden } = useBadge()
  const path = '/tables/remote'
  return (count: number) =>
    count > 0 ? show(path, { label: count, type: 'info' }) : hidden(path)
}

源码:useAppNavigation · useAppRoot · useSiderBar · useBadge · useVueRouter