跳转到正文

窗口、全屏和日期 ​

交互示例 ​

查看示例源码
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>
    )
  },
})

useDevice ​

useDevice(options?) 返回 width、height 引用及 isTabletOrSmaller 计算引用。默认条件为 width <= 768。options.media 自定义断点,其他窗口尺寸选项传给 VueUse useWindowSize。observer(isSmaller, { width, height }) 会立即执行一次,此后窗口尺寸或断点判断变化时再次执行。它检测窗口宽度,无法识别设备型号;组件容器宽度请另用 CSS 或容器观察。

ts
import { useDevice } from '@/hooks'
import { computed } from 'vue'

export function useListDensity() {
  const { isTabletOrSmaller } = useDevice({ media: 900 })
  return computed(() => (isTabletOrSmaller.value ? 'small' : 'medium'))
}

useElementFullscreen ​

点击按钮,查看元素撑满视口及恢复原位置的效果。

查看示例源码
vue
<template>
  <DemoFrame>
    <div ref="preview" class="ray-demo fullscreen-demo">
      <NButton @click="toggleFullscreen">
        {{
          isFullscreen
            ? '退出全屏 / Exit full screen'
            : '元素全屏 / Full screen'
        }}
      </NButton>
    </div>
  </DemoFrame>
</template>

<script setup lang="ts">
import { useElementFullscreen } from '@ray-template/composables/useElementFullscreen'
import { NButton } from 'naive-ui'
import { useTemplateRef } from 'vue'
import DemoFrame from './DemoFrame.vue'

const { isFullscreen, toggleFullscreen } = useElementFullscreen(
  useTemplateRef('preview'),
)
</script>

<style scoped>
.fullscreen-demo {
  display: grid;
  place-items: center;
  margin: 0;
  background: var(--vp-c-bg-soft);
}
</style>

useElementFullscreen(target, options?) 返回 enter()、exit()、toggleFullscreen() 和只读 isFullscreen。目标需能解包为 HTMLElement。它用 CSS 固定定位撑满视口;同一个元素一次只能由一个实例控制,也不会调用原生 Fullscreen API。

选项行为
beforeEnter / beforeExit在覆盖或恢复样式之前执行;手动切换时抛错会中止操作。
enter / exit状态变化或样式恢复后执行,enter 不代表动画结束。
zIndex指定层级;省略时随进入顺序分配。
backgroundColor / transition指定背景与过渡。传 'none' 关闭过渡。

退出和卸载都会恢复原行内样式并取消待处理动画帧。作用域销毁会直接恢复,随后执行 exit 回调;销毁后旧实例不能再次进入全屏。若交互需要 Esc 或按钮关闭,页面应绑定 exit()。

ts
import { useElementFullscreen } from '@/hooks'
import { ref } from 'vue'

export function usePanelFullscreen() {
  const panel = ref<HTMLElement>()
  const controls = useElementFullscreen(panel, { transition: 'none' })
  return { panel, ...controls }
}

useDayjs ​

方法行为
locale(key)从应用语言映射设置 Day.js 全局 locale,未知键回退到默认语言。
isDayjs(value)判断是否为 Day.js 对象。
format(date, { format }?)格式化,默认 YYYY-MM-DD HH:mm:ss。
getStartAndEndOfDay({ format }?)返回 today、startOfDay、endOfDay 及对应三个 format… 字符串。
daysDiff(date1, date2)计算 date2 - date1 的整数天差,可为负数。
isDateInRange(date, { start, end })检查严格开区间 start < date < end,不含两端。

日界线按当前 Day.js 环境计算。后端按固定时区统计时,传统一时区的时间并在业务层处理区间边界。切换界面语言时优先使用 Setting Store,它会一并同步日期语言。

ts
import { useDayjs } from '@/hooks'

const day = useDayjs()
export const exportDate = day.format('2026-11-03', { format: 'YYYY-MM-DD' })
export const dayRange = day.getStartAndEndOfDay()

源码:useDevice · useElementFullscreen · useDayjs