布局与滚动 Hooks
本页 API 操作模板默认布局。替换布局内容或侧栏前,先确认插槽和布局实例仍在预期位置。
交互示例
查看示例源码
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 动画完成事件。进入时可以调整滚动位置。连续切换只执行最新状态的完成回调;切到当前状态时直接返回。
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 只保留最后一次恢复计时。
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。顶部模式、未挂载或侧栏已卸载时安全忽略。它滚动侧栏容器,不改变菜单选中项。
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