导航与菜单
从 @/hooks 导入本页 API。菜单来源、权限和路由记录见路由指南。
交互示例
查看示例源码
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
查看路由示例源码
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 外取得实例。初始化后再访问依赖实际路由匹配的状态。
import { useVueRouter } from '@/hooks'
export const readQuery = () => useVueRouter().router.currentRoute.value.queryuseAppNavigation
useAppNavigation().navigationTo(target, options?) 支持三类目标:
| target | 行为 |
|---|---|
| 完整路径字符串 | 先用 Router 解析,保留动态路径、query 和 hash。未匹配或只匹配兜底路由时返回 undefined。 |
AppMenuOption | 按 fullPath 导航。 |
| 从 0 开始的整数 | 从当前菜单取项,遇到父菜单沿第一个子项查到叶子。菜单需要先初始化。 |
NavigationToOptions.isPush 默认 true;设为 false 使用 router.replace。query 可覆盖字符串路径中的同名查询参数。成功发起时返回 Router Promise。负数、小数、非有限数和越界索引不会导航;实际结果仍受路由守卫影响。
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 显式导航。
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,不依赖业务首页。 |
不要在存在未保存表单的工作流里直接调用批量关闭;这些方法不会替业务处理未保存确认。
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(显隐)。使用翻译键时同步维护语言包。
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