import{_ as j}from"./chunks/AdminExample.vue_vue_type_script_setup_true_lang.wPcM-fsm.js";import{aa as R,ab as O,S as V,p as H,d as M,ac as z,o as x,b as L,w as f,j as t,E as o,k as F,a as C,t as Y,_ as $,c as U,a3 as v}from"./chunks/framework.D8G7yXPy.js";import{u as G}from"./chunks/unref-element.BgeEuJ_j.js";import{B as X,_ as J}from"./chunks/DemoFrame.vue_vue_type_script_setup_true_lang.BibqOSJQ.js";import"./chunks/light.BQgF5P5u.js";function W(k){return R()?(O(k),!0):!1}let K=999;const r="data-element-fullscreen",c=new WeakSet,Q=(k,d)=>{const{beforeEnter:i,beforeExit:p,enter:e,exit:h,backgroundColor:B,zIndex:b,transition:N="all 0.3s cubic-bezier(0.4, 0, 0.2, 1)"}={},E=H(!1);let u=!1,l,a;const g=()=>{a&&(p==null||p(),a(),h==null||h())},D=()=>{if(u)return;const s=G(k);if(!(s instanceof HTMLElement)||c.has(s))return;a&&g(),i==null||i();const{top:S,left:_,width:T,height:q}=s.getBoundingClientRect(),A={position:"fixed","box-sizing":"border-box",top:`${S}px`,left:`${_}px`,width:`${T}px`,height:`${q}px`,transform:"translate(0, 0)","z-index":String(b??++K),transition:"none",...B?{"background-color":B}:{}},P=Object.keys(A).map(n=>[n,s.style.getPropertyValue(n),s.style.getPropertyPriority(n)]),m=s.getAttribute(r);c.add(s),a=()=>{l!==void 0&&cancelAnimationFrame(l),l=void 0;for(const[n,y,I]of P)s.style.setProperty(n,y,I);m===null?s.removeAttribute(r):s.setAttribute(r,m),a=void 0,c.delete(s),E.value=!1},s.setAttribute(r,"true");for(const[n,y]of Object.entries(A))s.style.setProperty(n,y);s.offsetHeight,s.style.transition=N,l=requestAnimationFrame(()=>{Object.assign(s.style,{top:"0px",left:"0px",width:"100dvw",height:"100dvh"}),l=void 0}),E.value=!0,e==null||e()},w=()=>{E.value?g():D()};return W(()=>{u=!0,a&&(a(),h==null||h())}),{enter:D,exit:g,toggleFullscreen:w,isFullscreen:V(E)}},Z={ref:"preview",class:"ray-demo fullscreen-demo"},ss=M({__name:"FullscreenDemo",setup(k){const{isFullscreen:d,toggleFullscreen:i}=Q(z("preview"));return(p,e)=>(x(),L(J,null,{default:f(()=>[t("div",Z,[o(F(X),{onClick:F(i)},{default:f(()=>[C(Y(F(d)?"退出全屏 / Exit full screen":"元素全屏 / Full screen"),1)]),_:1},8,["onClick"])],512)]),_:1}))}}),is=$(ss,[["__scopeId","data-v-32a633ef"]]),ps=JSON.parse('{"title":"窗口、全屏和日期","description":"","frontmatter":{},"headers":[],"relativePath":"reference/hooks/browser.md","filePath":"reference/hooks/browser.md"}'),as={name:"reference/hooks/browser.md"},es=Object.assign(as,{setup(k){return(d,i)=>(x(),U("div",null,[i[0]||(i[0]=t("h1",{id:"窗口、全屏和日期",tabindex:"-1"},[C("窗口、全屏和日期 "),t("a",{class:"header-anchor",href:"#窗口、全屏和日期","aria-label":'Permalink to "窗口、全屏和日期"'},"")],-1)),i[1]||(i[1]=t("h2",{id:"交互示例",tabindex:"-1"},[C("交互示例 "),t("a",{class:"header-anchor",href:"#交互示例","aria-label":'Permalink to "交互示例"'},"")],-1)),o(j,{path:"/web-hooks",title:"窗口宽度和日期范围",focus:"useDevice,useDayjs"}),i[2]||(i[2]=v(`查看示例源码
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(options?) 返回 width、height 引用及 isTabletOrSmaller 计算引用。默认条件为 width <= 768。options.media 自定义断点,其他窗口尺寸选项传给 VueUse useWindowSize。observer(isSmaller, { width, height }) 会立即执行一次,此后窗口尺寸或断点判断变化时再次执行。它检测窗口宽度,无法识别设备型号;组件容器宽度请另用 CSS 或容器观察。
import { useDevice } from '@/hooks'
import { computed } from 'vue'
export function useListDensity() {
const { isTabletOrSmaller } = useDevice({ media: 900 })
return computed(() => (isTabletOrSmaller.value ? 'small' : 'medium'))
}点击按钮,查看元素撑满视口及恢复原位置的效果。
`,6)),o(is),i[3]||(i[3]=v(`<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()。
import { useElementFullscreen } from '@/hooks'
import { ref } from 'vue'
export function usePanelFullscreen() {
const panel = ref<HTMLElement>()
const controls = useElementFullscreen(panel, { transition: 'none' })
return { panel, ...controls }
}| 方法 | 行为 |
|---|---|
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,它会一并同步日期语言。
import { useDayjs } from '@/hooks'
const day = useDayjs()
export const exportDate = day.format('2026-11-03', { format: 'YYYY-MM-DD' })
export const dayRange = day.getStartAndEndOfDay()