Themes, Language, and Watermark Hooks
Interactive example
View example source
import {
useAppNavigation,
useBadge,
useContentScroll,
useI18n,
useMaximize,
useSiderBar,
useSiderScroll,
useSpinning,
useTheme,
useVueRouter,
useWatermark,
} from '@/hooks'
import { useMenuGetters, useRuntimeGetters, useSettingGetters } from '@/store'
import { useMenuKeyboard } from '@ray-template/admin-shell'
import { useMenu } from '@ray-template/composables/useMenu'
import { RIcon } from '@ray-template/ui/icon'
import { useTimeoutFn } from '@vueuse/core'
import { NButton, NFlex, NInput, NMenu, 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 menuKeyboard = useMenuKeyboard(false)
const { menuRef, menuProps, showOption } = useMenu({
options: [
{ key: 'overview', label: () => text('menuOverview') },
{
key: 'reports',
label: () => text('menuReports'),
children: [
{ key: 'daily', label: () => text('menuDaily') },
{ key: 'monthly', label: () => text('menuMonthly') },
],
},
],
value: 'monthly',
expandedKeys: [],
})
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="10 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>
),
)}
{example(
'useMenu',
`const { menuRef, menuProps, showOption } = useMenu({
options: [
{ key: 'overview', label: 'Overview' },
{
key: 'reports',
label: 'Reports',
children: [
{ key: 'daily', label: 'Daily report' },
{ key: 'monthly', label: 'Monthly report' },
],
},
],
value: 'monthly',
expandedKeys: [],
})
// TSX
<NMenu ref={menuRef} {...menuProps} />
<NButton onClick={() => showOption('monthly')}>Reveal monthly report</NButton>`,
() => (
<NFlex vertical>
<nav
aria-label={text('menuExample')}
onKeydown={menuKeyboard.onKeydown}
>
<NMenu
ref={menuRef}
{...menuProps}
nodeProps={menuKeyboard.nodeProps}
/>
</nav>
<NFlex>
<NButton onClick={() => showOption('monthly')}>
{text('menuReveal')}
</NButton>
<NButton
disabled={menuProps.value === null}
onClick={() => (menuProps.value = null)}
>
{text('menuClear')}
</NButton>
</NFlex>
<code>
{t('menuState', {
selected: menuProps.value ?? '—',
expanded: menuProps.expandedKeys?.join(', ') || '—',
})}
</code>
</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() returns these methods. Setting Store and the global provider manage color overrides together.
| Method | Behavior |
|---|---|
lightTheme() / darkTheme() | Select manual light or dark mode and update Naive UI theme overrides. |
toggleTheme() | Select the manual mode opposite the current resolved mode. |
syncSystemTheme() | Read the browser preference and switch to auto. Setting Store then follows system changes. |
getAppTheme() | Returns { theme, themeLabel, themeI18nLabel }. theme: true means dark. themeLabel is the literal Dark or Light. |
getAppTheme() returns a snapshot. Call it in a computed value or render function for UI that follows language or theme. Set a custom primary color with changePrimaryColor in Setting Store.
useI18n
View language switching source
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?) exposes t(key, ...args), locale(lang), and the Vue I18n global API when initialized. useI18n('menu').t('Dashboard') and useI18n('menu').t('menu.Dashboard') use the same key. Without a namespace, a bare string is returned as written. Before initialization, t returns the resolved key. The same function reads the current instance after initialization.
@/hooks also exports a standalone t(key) that returns the original key for route metadata and static translation tooling. Change the whole application language with useSettingActions().updateLocale(lang) to sync Day.js, the UI library, and persisted settings. Calling useI18n().locale directly updates only Vue I18n and the HTML language attribute.
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) merges new watermark text and ignores an empty string. showWatermark(), hiddenWatermark(), and toggleWatermark() change shared visibility. To hide it, use hiddenWatermark(). Update font, rotation, and spacing in Setting Store's watermarkConfig. The position of AppWatermarkProvider determines its scope.
import { useWatermark } from '@/hooks'
export function useReportWatermark() {
const { setWatermarkContent, showWatermark, hiddenWatermark } = useWatermark()
return {
enable() {
setWatermarkContent('Internal report')
showWatermark()
},
disable: hiddenWatermark,
}
}