前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载useTimestamp是 VueUse 核心包packages/core/useTimestamp中一个轻量却实用的组合式函数Composable用于返回一个响应式的当前时间戳。在计时器展示、动画时间基准、日志记录、倒计时场景中它让开发者无需手写setInterval或requestAnimationFrame的销毁逻辑即可获得随帧率自动刷新的毫秒级时间值。读完本文你将掌握useTimestamp的完整 API、controls/offset/callback/scheduler四个核心配置项的作用以及它在底层如何与调度器默认useRafFn协作并学会用组件形式在模板中直接使用它。useTimestamp 是什么useTimestamp的定位在 index.md 中只有一句话Reactive current timestamp响应式的当前时间戳。它被归类在Animation分类下因为其默认的刷新机制是逐帧刷新——即每触发一次requestAnimationFrame就更新一次值这使得它天然适合与动画、帧率相关的场景。从源码结构看useTimestamp实现非常精简index.ts 全文约 70 行它不直接持有定时器而是把“何时刷新”的职责委托给一个可插拔的调度器scheduler自身只负责两件事计算当前时间戳和将结果写入一个浅层响应式引用shallowRef。基础用法最基础的用法只需要一行import { useTimestamp } from vueuse/core const timestamp useTimestamp({ offset: 0 })此时timestamp是一个ShallowRefnumber模板中直接使用{{ timestamp }}即可实时显示当前时间戳且无需手动清理——调度器在组件卸载时通过tryOnScopeDispose自动停止。带控制能力controls: true如果希望拥有暂停 / 恢复的控制权可以开启controlsimport { useTimestamp } from vueuse/core const { timestamp, pause, resume } useTimestamp({ controls: true })此时返回值从单个ShallowRefnumber变为{ timestamp: ShallowRefnumber } Pausable其中Pausable是 VueUse 共享包中定义的标准控制接口包含isActive: ReadonlyShallowRefboolean—— 当前是否在运行pause(): void—— 暂停刷新之后timestamp不再变化resume(): void—— 恢复刷新值重新开始逐帧更新。注意即使暂停timestamp仍保留最后一次刷新的值并不会被重置。核心 API 与选项参数UseTimestampOptionsControls的类型定义index.ts继承自ConfigurableScheduler定义于 _configurable.ts共包含四个配置项选项类型默认值说明controlsControls extends booleanfalse是否暴露pause/resume/isActive等控制能力为true时返回值从ShallowRefnumber变为对象形式offsetnumber0加到时间戳上的偏移量单位为毫秒可用来模拟“比当前时间早/晚 N 毫秒”的时间基准callback(timestamp: number) void无每次刷新时触发的回调会收到更新后的时间戳值适合做副作用如日志、记录历史scheduler(cb: Fn) PausableuseRafFn自定义刷新调度器决定“以什么频率、什么机制”调用更新回调offset 的实际语义offset不是“偏移启动时间”而是直接参与数值运算。在源码 index.ts 中const ts shallowRef(timestamp() offset) const update () ts.value timestamp() offset初始化值与每次刷新都会执行timestamp() offset。其中timestamp是共享包提供的工具函数packages/shared/utils/is.tsexport const timestamp () Date.now()即Date.now()的数值形式毫秒级 Unix 时间戳。因此offset: 5000会让timestamp恒比真实时间多 5 秒用负值则可以回拨时间。callback 的执行细节callback被包装进刷新流程中index.tsconst cb callback ? () { update() callback(ts.value) } : update const controls scheduler(cb)注意执行顺序先更新ts.value再以更新后的值调用callback。也就是说回调参数与timestamp.value永远保持一致。scheduler可插拔的刷新引擎scheduler是useTimestamp最灵活的一点。它是一个签名(cb: Fn) Pausable的函数接收一个“刷新回调”返回一组暂停 / 恢复控制。默认值为useRafFn逐帧刷新这也是它被归入 Animation 分类的原因。从测试用例index.browser.test.ts可以看到两种典型自定义调度器延迟启动的 rAF 调度器——通过useRafFn(cb, { immediate: false })让刷新不在创建时立即开始而是等待resume()const { resume, timestamp } useTimestamp({ controls: true, scheduler: (cb: AnyFn) useRafFn(cb, { immediate: false }), callback, }) // 在 resume() 之前 timestamp 保持初始值不变 resume()基于 setInterval 的调度器——若想按固定毫秒间隔刷新而非逐帧可换成useIntervalFnconst { resume, timestamp } useTimestamp({ controls: true, scheduler: (cb: AnyFn) useIntervalFn(cb, 50, { immediate: false }), callback, })其中useIntervalFn位于 packages/shared/useIntervalFn/index.ts是setInterval的可控封装immediate: false同样表示创建时不立即启动。这一可插拔设计意味着无论底层是requestAnimationFrame、setInterval还是其他自定义循环机制useTimestamp的核心逻辑都不需要改动。返回值与类型重载useTimestamp通过 TypeScript 函数重载区分两种返回形态index.tsexport function useTimestamp(options?: UseTimestampOptionsfalse): ShallowRefnumber export function useTimestamp(options: UseTimestampOptionstrue): { timestamp: ShallowRefnumber } Pausable不传controls或传controls: false返回ShallowRefnumber可直接响应式使用传controls: true返回{ timestamp } Pausable解构得到timestamp、isActive、pause、resume。在实现中index.ts内部始终以shallowRef保存数值。由于数字是原始类型shallowRef与ref在触发响应式更新上行为一致但避免了不必要的深层代理开销。组件用法 UseTimestampuseTimestamp还提供了对应的无渲染组件UseTimestamp源码见 component.ts可以直接在模板中通过作用域插槽scoped slot使用template UseTimestamp v-slot{ timestamp, pause, resume } Current Time: {{ timestamp }} button clickpause() Pause /button button clickresume() Resume /button /UseTimestamp /template组件内部实现值得注意它声明了scheduler、callback、offset三个 propscontrols被Omit掉因为组件内部固定以controls: true调用组合式函数component.ts组件体内通过reactive(useTimestamp({ ...props, controls: true }))将返回的{ timestamp, isActive, pause, resume }转为响应式对象再作为插槽数据暴露给模板component.ts。这意味着组件形态天然就具备暂停 / 恢复能力无需额外配置。底层实现原理串讲把 index.ts 与依赖串起来useTimestamp的完整工作链路如下初始化shallowRef(timestamp() offset)建立初始值timestamp()即Date.now()构造回调将update刷新数值与可选的callback副作用组合成统一的cb启动调度调用scheduler(cb)获得Pausable控制集。默认调度器useRafFnpackages/core/useRafFn/index.ts会在创建时immediate默认为true立即发起requestAnimationFrame循环并在每帧调用cb它内部还支持fpsLimit帧率限制与once单次执行生命周期调度器的pause通过tryOnScopeDispose注册组件卸载或作用域销毁时自动停止刷新杜绝内存泄漏控制暴露若controls: true将ts与调度器的isActive/pause/resume合并返回否则直接返回ts本身。一个值得留意的细节useRafFn的回调参数是{ delta, timestamp }而useTimestamp传给它的cb并不消费这些参数它只使用Date.now()作为时间来源——两者是解耦的所以替换调度器不会影响时间戳的语义。测试用例对行为的验证仓库中的浏览器测试index.browser.test.ts用假定时器vi.useFakeTimers()验证了三个关键行为可作为使用时的行为契约默认立即启动创建后推进 20mstimestamp.value必然大于初始值rAF 调度器可延迟启动使用useRafFn(cb, { immediate: false })时未resume()前timestamp保持不变、callback不触发resume()后开始刷新interval 调度器同样可延迟启动换成useIntervalFn(cb, 50, { immediate: false })后行为与 rAF 版本一致验证了scheduler的插拔性。典型应用场景小结基于以上 API 与实现useTimestamp适合以下场景实时时钟 / 计时器展示模板中直接渲染timestamp配合useDateFormat格式化输出动画时间基准逐帧刷新天然贴合动画帧节奏日志与埋点通过callback在每次刷新时记录带时间戳的数据时间偏移模拟利用offset模拟未来或过去的时间例如倒计时剩余时间的显示。若需要进一步查看演示代码可以参考 demo.vue一段极简的{{ timestamp }}渲染示例以及同目录下的 component.ts 与 index.browser.test.ts 完整源码。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐airi 项目中的 VueUse 响应式时间戳useTimestamp 实战指南airi 项目中的 VueUse 响应式时间戳useTimestamp 实战指南 useTimestamp 是 VueUse 提供的响应式当前时间戳 compAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染VueUse 的 useWebSocket在 Vue 3 中构建响应式 WebSocket 客户端VueUse 的 useWebSocket在 Vue 3 中构建响应式 WebSocket 客户端 导读 useWebSocket 是 VueUse pac前端VueUse useNow在 Vue 3 中获取响应式当前时间的完整指南VueUse useNow在 Vue 3 中获取响应式当前时间的完整指南 useNow 是 VueUse 提供的一个轻量级组合式函数用于在 Vue 3 应用前端上一篇Comprehensive Rust 教程用 std::mem::forget 拆除 Drop Bomb——RAII 事务收尾的战术实践下一篇Terrarium 项目之 CSS 入门用 Web-Dev-For-Beginners 实战 Kaskade、Selektoren 与 Positionierung创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考