Skip to content
ReferenceVersion 6.0.2

Themes, Language, and Watermark Hooks ​

Interactive example ​

View example source
tsx
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.

MethodBehavior
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
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>
    )
  },
})

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.

ts
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.

ts
import { useWatermark } from '@/hooks'

export function useReportWatermark() {
  const { setWatermarkContent, showWatermark, hiddenWatermark } = useWatermark()
  return {
    enable() {
      setWatermarkContent('Internal report')
      showWatermark()
    },
    disable: hiddenWatermark,
  }
}

useTheme source · useI18n source · useWatermark source