主题、语言和水印 Hooks
交互示例
查看示例源码
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>
)
},
})useTheme
useTheme() 返回下列方法。颜色覆盖由设置 Store 和全局 Provider 一起管理。
| 方法 | 行为 |
|---|---|
lightTheme() / darkTheme() | 切换为手动浅色或深色,更新 Naive UI 的主题覆盖。 |
toggleTheme() | 根据当前实际明暗状态切换到相反的手动主题。 |
syncSystemTheme() | 读取浏览器偏好并切换到 auto,之后由设置 Store 跟随系统变化。 |
getAppTheme() | 返回 { theme, themeLabel, themeI18nLabel };theme 为 true 表示深色,themeLabel 是固定的 Dark / Light。 |
getAppTheme() 返回一次读取的对象。界面要跟随语言或主题变化时,在 computed 或渲染中调用。自定义主色请使用 Setting Store 的 changePrimaryColor。
useI18n
查看语言切换示例源码
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>
)
},
})useI18n(namespace?) 返回 t(key, ...args)、locale(lang) 和初始化时可用的 Vue I18n 全局能力。useI18n('menu').t('Dashboard') 与 useI18n('menu').t('menu.Dashboard') 指向同一翻译键。未指定命名空间时,裸字符串原样返回。初始化前,t 返回解析后的键;初始化后同一个翻译函数会读取最新实例。
@/hooks 还导出独立的 t(key),它只返回原始键,可供路由元数据和翻译工具静态识别。切换整个应用语言用 useSettingActions().updateLocale(lang),以同步 Day.js、组件库和持久化语言;直接调用 useI18n().locale 只操作 Vue I18n 和 HTML 语言属性。
import { useI18n, useTheme } from '@/hooks'
import { useSettingActions } from '@/store'
import { computed } from 'vue'
export function useAppearanceSettings() {
const { t } = useI18n('menu')
const theme = useTheme()
const { updateLocale } = useSettingActions()
const title = computed(() => t('Dashboard'))
return {
title,
followSystem: theme.syncSystemTheme,
switchToEnglish: () => updateLocale('en-US'),
}
}useWatermark
setWatermarkContent(content) 合并水印文字;空字符串直接忽略。showWatermark()、hiddenWatermark()、toggleWatermark() 修改共享显隐状态。要清除显示,请调用 hiddenWatermark()。字体、旋转和间距从 Setting Store 的 watermarkConfig 修改,显示范围由 AppWatermarkProvider 所在位置决定。
import { useWatermark } from '@/hooks'
export function useReportWatermark() {
const { setWatermarkContent, showWatermark, hiddenWatermark } = useWatermark()
return {
enable() {
setWatermarkContent('内部报表')
showWatermark()
},
disable: hiddenWatermark,
}
}源码:useTheme · useI18n · useWatermark