★ FEATURED ARTICLE 人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载本文讲解 VueUse 的useTitlecomposable —— 一个把document.title变为响应式状态的轻量工具。在 AIRI 的多个 Vue 3 应用stage-web、stage-pocket、stage-tamagotchi 等中各应用index.html目前只有静态title如AIRI尚未接入动态标题管理通过useTitle可以基于路由、消息数等响应式状态实时改写浏览器标签页标题同时借助titleTemplate统一品牌后缀、借助restoreOnUnmount防止组件卸载后标题污染。读完本文你将掌握useTitle的全部 API 形态、选项语义与类型约束并能直接在自己的 Vue 3 组件中落地可复用的动态标题方案。背景为什么需要响应式标题浏览器标签页标题document.title是 SPA 中最直观的当前状态指示器新消息提醒、正在处理的页面、未保存的变更都应该反映在标题上。在 AIRI 仓库中多个前端应用都依赖vueuse/core见 apps/stage-pocket/package.json、apps/stage-tamagotchi/package.json、apps/component-calling/package.json 等且各应用入口 HTML 仅声明了静态标题例如 apps/stage-pocket/index.html 的titleAIRI/title。这意味着标题一旦设置便不会随页面交互变化。useTitle提供了一条更简洁、可维护的替代路径让标题成为响应式数据的一部分随ref/computed自动同步。需要特别注意的是useTitle属于 VueUse 的 Browser 分类见 SKILL.md 的函数索引它直接操作document.title因此与 SSR 不兼容在服务端渲染期间你的值只会被客户端应用。如果项目引入 SSR需要改用其他 head 管理方案。基本用法读取与设置标题useTitle的默认调用不需要任何参数返回一个可直接读写的响应式refimport { useTitle } from vueuse/core const title useTitle() console.log(title.value) // 打印当前 document.title title.value Hello // 立即改写页面标题这段代码背后是标准的ref语义读取title.value得到当前标题写入title.value触发document.title同步更新。由于返回对象是Refstring | null | undefined你也可以在script setup中直接解构后在模板或逻辑里复用实现标题的单一数据源管理。设置初始标题如果希望在调用时就立即把标题设为指定值直接把字符串作为第一个参数传入即可import { useTitle } from vueuse/core const title useTitle(New Title)这等价于先读取当前标题再写回但更简洁。传入的初始值同时也会成为返回ref的初始值后续读写都围绕它进行。响应式绑定让标题随 ref / computed 联动useTitle的第一个参数接受MaybeRefstring | null | undefined即普通字符串、ref或computed都可以。当传入一个响应式来源时标题会在该来源变化时自动更新。这是最常见的实战形态例如把标题绑定到未读消息数import { useTitle } from vueuse/core import { computed, shallowRef } from vue const messages shallowRef(0) const title computed(() { return !messages.value ? No message : ${messages.value} new messages }) useTitle(title) // document.title 会与 ref title 保持一致这里computed负责把数值派生为标题字符串useTitle只做同步职责单一。消息数变化 →computed重算 → 标签页标题自动刷新全程无需手写watch或事件监听。该模式同样适用于路由驱动例如在 apps/stage-pocket/src/main.ts 的router.afterEach钩子旁可以引入一个基于当前路由 meta 的computed配合useTitle让每个页面切换后标题自动反映当前页面名称。统一品牌后缀titleTemplate多个页面共用一个应用时通常希望标题统一带上站点名称例如对话页面 | AIRI。useTitle支持 Vue Meta 风格的标题模板titleTemplate模板中的%s占位符会被替换为实际标题import { useTitle } from vueuse/core const title useTitle(New Title, { titleTemplate: %s | My Awesome Website, })执行后标签页标题会显示为New Title | My Awesome Website。对于 AIRI 这类多应用仓库可以借此把所有页面的标题统一为页面名 | AIRI与现有静态titleAIRI/title见 apps/stage-web/index.html的品牌一致性无缝衔接。titleTemplate的类型为MaybeRefstring | ((title: string) string)这意味着它既可以是字符串模板也可以是接收当前标题并返回完整标题的函数适合需要条件拼接或国际化i18n的场景。监听外部标题变化observe默认情况下useTitle只响应由它自己驱动的值变化。若希望反过来观察document.title被其他代码第三方脚本、浏览器扩展、其他模块修改的情况可以开启observe选项const title useTitle(undefined, { observe: true, })observe基于MutationObserver监听document.title实际上监听的是包含标题文本的title元素所在节点任何外部改写都会反向同步回返回的ref形成双向同步。默认值为false。两个互斥选项observe 与 titleTemplateobserve与titleTemplate在类型层面被设计为二选一的互斥关系详见下文的联合类型声明不可同时启用::: warningobserve与titleTemplate不兼容。 :::原因从实现语义上可以理解titleTemplate会改写写出的标题写入的是模板展开后的结果此时再观察原始document.title会造成环路或语义混乱而observe模式下标题以 DOM 中的实际值而非模板为唯一事实来源。组件卸载时还原标题restoreOnUnmountrestoreOnUnmount用于解决一个常见的 SPA 隐患组件设置了动态标题但当组件卸载如用户离开页面后标题却停留在最后的状态导致后续页面顶着错误的标题。启用后useTitle会在组件卸载onScopeDispose时把标题还原为调用前的原始值const title useTitle(Hello, { restoreOnUnmount: true, })它的类型不仅仅是布尔值还支持传入自定义还原函数让你决定还原成什么restoreOnUnmount?: false | ((originalTitle: string, currentTitle: string) string | null | undefined)还原函数接收两个参数originalTitle组件挂载前的原始标题与currentTitle当前标题返回值为还原后的新标题返回null/undefined时使用默认还原逻辑。这允许做精细化控制例如仅当当前标题仍是由本组件设置时才还原否则保持现状。选项速查表选项类型默认值说明observebooleanfalse使用MutationObserver观察document.title的外部变化并反向同步与titleTemplate互斥titleTemplateMaybeRefstring \| ((title: string) string)%s标题模板字符串%s为占位符或生成完整标题的函数与observe互斥restoreOnUnmountfalse \| ((originalTitle, currentTitle) string \| null \| undefined)—组件卸载时是否/如何还原标题documentDocument继承自ConfigurableDocument当前document指定要操作的目标文档对象便于在 iframe、测试环境等场景中替换其中document选项来自ConfigurableDocument类型的继承UseTitleOptions ConfigurableDocument UseTitleOptionsBaseVueUse 中大量 Browser composable 都遵循这一约定便于单元测试中注入 mock 文档。返回类型解读useTitle有两个重载返回值随调用形态不同而变化export type UseTitleReturn | ComputedRefstring | null | undefined | Refstring | null | undefined // 传入 ReadonlyRefOrGetter 时 useTitle( newTitle: ReadonlyRefOrGetterstring | null | undefined, options?: UseTitleOptions, ): ComputedRefstring | null | undefined // 不传或传入 MaybeRef 时 useTitle( newTitle?: MaybeRefstring | null | undefined, options?: UseTitleOptions, ): Refstring | null | undefined可以推断当第一个参数是ref或 getter 时返回ComputedRef只读的派生标题视图最终值与传入来源一致当传入普通字符串或省略参数时返回可写的Ref写入操作直接作用于document.title。完整类型声明以下是本技能文档.agents/skills/vueuse-functions/references/useTitle.md中给出的官方类型声明可直接作为集成时的类型契约export type UseTitleOptionsBase { /** * Restore the original title when unmounted * param originTitle original title * returns restored title */ restoreOnUnmount?: | false | (( originalTitle: string, currentTitle: string, ) string | null | undefined) } ( | { /** * Observe document.title changes using MutationObserve * Cannot be used together with titleTemplate option. * * default false */ observe?: boolean } | { /** * The template string to parse the title (e.g., %s | My Website) * Cannot be used together with observe option. * * default %s */ titleTemplate?: MaybeRefstring | ((title: string) string) } ) export type UseTitleOptions ConfigurableDocument UseTitleOptionsBase export type UseTitleReturn | ComputedRefstring | null | undefined | Refstring | null | undefined值得注意的设计点是UseTitleOptionsBase中observe与titleTemplate被建模为互斥的联合类型分支这是把两个选项不能同时使用的约束直接编码进类型系统让错误配置在编译期就被拦截而不是留到运行时才暴露。落地建议在 AIRI 多应用仓库中的实践模式结合仓库现状多个应用已安装vueuse/core、入口 HTML 仅有静态标题、apps/stage-pocket/src/main.ts 已有路由钩子基础设施推荐以下实践路径品牌统一在main.ts或全局布局组件中调用一次useTitle(, { titleTemplate: %s | AIRI })为全站标题注入统一后缀。路由联动利用router.afterEach获取to.meta.title配合useTitle传入computed实现页面级动态标题由于useTitle不兼容 SSR且这些应用均为纯客户端渲染main.ts中无 SSR 逻辑可以安全使用。会话级提醒在聊天等实时场景中仿照未读消息数示例用computed派生新消息提示并写入标题提升用户注意力引导。局部组件若某个悬浮窗、开发工具面板需要临时改写标题启用restoreOnUnmount: true保证组件卸载后标题自动还原避免状态残留。useTitle本身是 SKILL.md 中标记为AUTO适用即用的 Browser 类函数只要项目已安装vueuse/core即可按上文任一形态直接使用无需额外安装依赖。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐VueUse 的 useTitle打造响应式页面标题的完整实战指南VueUse 的 useTitle打造响应式页面标题的完整实战指南 导读 useTitle 是 VueUseVue 3 Composition API 工具前端如何用 Video2X 3 步跑通视频超分辨率完整实战指南如何用 Video2X 3 步跑通视频超分辨率完整实战指南 Video2X 是一个基于机器学习的视频超分辨率与帧插值框架用 Real ESRGAN、Anime音视频视频处理图像处理人工智能QuickRecorder macOS 录屏工具完整上手一条命令装好5 分钟录出第一条片QuickRecorder macOS 录屏工具完整上手一条命令装好5 分钟录出第一条片 QuickRecorder 是一款给 macOS 用户用的轻量录屏屏幕录制音视频桌面应用上一篇如何为Espruino编写自定义JavaScript库从入门到精通的完整指南下一篇LLaMA-Factory模型评估自定义评估指标实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
