airi 项目接入 VueUse useShare：基于 Web Share API 的响应式分享能力实战指南

airi 项目接入 VueUse useShare基于 Web Share API 的响应式分享能力实战指南【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiuseShare 是 VueUse 提供的浏览器能力组合式函数Composable它把 Web Share API 封装成 Vue 响应式接口让你可以在 Vue 3 / Nuxt 3 应用中一键唤起系统原生分享面板分享文本、链接甚至文件。在 airi 这类同时面向 Webapps/stage-web与移动端apps/stage-pocket的多端项目中useShare是与系统分享体系打通的最短路径。读完本文你将掌握useShare的基本用法、响应式参数绑定、类型约束、isSupported能力检测与降级策略并了解它在 airi 仓库中的适用上下文。一、useShare 是什么为 Web Share API 包上一层响应式外壳useShare是 VueUse 中对Web Share API的响应式封装。Web Share API 允许网页通过操作系统或浏览器原生的分享机制把text文本、url链接、title标题以及files文件分享给其他应用——例如分享到系统通讯录、聊天软件或邮件客户端。它把复制链接 打开第三方 App这类繁琐流程收敛成一次系统级分享弹窗。在 .agents/skills/vueuse-functions/references/useShare.md 中该函数被归类为category: Browser能力在 .agents/skills/vueuse-functions/SKILL.md 的 Browser 分类表中useShare的定位是 Reactive Web Share API其Invocation 规则为AUTO——即在 Vue / Nuxt 开发中只要需求匹配需要调用系统分享能力就应优先使用该组合式函数而非手写navigator.share()的胶水代码。这套.agents/skills/vueuse-functions技能目录承载了 VueUse 全量函数的决策与实现指南其核心主张是优先用 VueUse 组合式函数替代自定义代码以提升可读性、可维护性与性能。useShare正是这一主张的典型代表——它让分享逻辑无需手动管理navigator检测、无需手动封装 Promise、无需担心响应式更新。二、前置依赖在 airi 中确认 vueuse/core 已就绪useShare属于vueuse/core包使用前需确保项目中已安装该依赖。在 airi 仓库的 pnpm workspace 中vueuse/core通过 catalog 统一管理版本例如 apps/stage-web/package.json 的dependencies中就声明了vueuse/core: catalog:同仓库的apps/stage-pocket、apps/component-calling等应用同样依赖该包。也就是说airi 的 Web 端与移动端应用都天然具备直接使用useShare的条件。安装方式如果项目尚未引入pnpm add vueuse/core三、基本用法一次按钮点击触发系统分享useShare的核心返回值为share函数与isSupported布尔值。文档给出的最小可用示例import { useShare } from vueuse/core const { share, isSupported } useShare() function startShare() { share({ title: Hello, text: Hello my friend!, url: location.href, }) }关键点逐项拆解share(options)接收一个UseShareOptions对象最终会被转发给navigator.share()返回的share是一个Promisevoid分享流程完成后 resolveisSupported表示当前环境是否支持 Web Share API在调用share前应先检查它避免在不支持的浏览器中直接调用导致异常。用户手势约束为什么必须在按钮回调里调用原文档特别强调了一个平台级约束Thesharemethod has to be called following a user gesture like a button click. It can’t simply be called on page load for example. That’s in place to help prevent abuse.也就是说share()必须在用户手势如按钮点击的调用链中触发不能在页面加载、定时器等场景下直接调用。这是浏览器为防止滥用而设计的保护机制。落实到代码上startShare应当绑定在button clickstartShare这样的模板事件上而不是在onMounted里执行。四、响应式用法传入 ref 或 getter让分享参数随状态自动更新useShare的响应式特性体现在第一个参数上它可以接收MaybeRefOrGetterUseShareOptions即普通对象、ref或 getter 函数均可。原文档给出的 ref 示例import { ref } from vue const shareOptions refShareOptions({ text: foo }) const { share, isSupported } useShare(shareOptions) shareOptions.value.text bar share()这里shareOptions是一个refShareOptions作为useShare的参数传入后源 ref 的变化会实时反映到分享选项中。当你修改shareOptions.value.text bar后调用share()系统分享面板携带的文本就是bar。这一模式在真实场景中非常实用例如const shareText ref() const shareUrl ref() // getter 形式分享内容由多个响应式状态派生 const { share, isSupported } useShare(() ({ title: 来自 airi 的分享, text: shareText.value, url: shareUrl.value, }))使用 getter 时share()每次调用都会读取最新的派生值无需手动同步状态。这种参数与状态解耦、调用时取最新值的设计正是 VueUse 组合式函数响应式优先理念的体现。五、类型声明深度解析理解签名才能正确使用原文档给出了完整类型声明逐层拆解如下export interface UseShareOptions { title?: string files?: File[] text?: string url?: string }UseShareOptions是传给navigator.share()的载荷四个字段全部可选字段类型含义titlestring分享内容的标题通常显示在分享面板顶部textstring分享的正文文本urlstring分享的链接地址可配合location.href分享当前页面filesFile[]要分享的文件数组要求平台与浏览器支持文件分享其中files是 Web Share API 中相对进阶的能力可用于分享图片、文档等本地文件。文件分享对运行环境有更高要求需要 HTTPS 且浏览器/系统支持接入时应搭配isSupported与运行时错误处理并建议在文件分享前提示用户预期行为。export interface UseShareReturn extends Supportable { share: (overrideOptions?: MaybeRefOrGetterUseShareOptions) Promisevoid }UseShareReturn说明share函数本身也接受MaybeRefOrGetterUseShareOptions作为可选覆盖参数——即你在调用时传入的选项会覆盖override构造useShare时传入的默认选项二者合并后作为最终的分享载荷。Supportable混入则保证返回值中带有isSupported能力标记与 VueUse 其他浏览器能力函数保持一致。export declare function useShare( shareOptions?: MaybeRefOrGetterUseShareOptions, options?: ConfigurableNavigator, ): UseShareReturnuseShare的第二个参数ConfigurableNavigator是 VueUse 的通用可配置项用于在测试或特定运行环境中注入自定义navigator对象例如在单元测试中 mock 分享行为日常开发中通常省略。函数标注了__NO_SIDE_EFFECTS__意味着仅调用useShare()而不使用返回值时不会产生副作用可安全地在模块顶层或任意生命周期中初始化。六、isSupported 检测与优雅降级Web Share API 并非所有浏览器与操作系统都支持因此在生产代码中isSupported是接入分享功能的第一道防线。推荐模式const { share, isSupported } useShare() function startShare() { if (!isSupported.value) { // 降级方案复制到剪贴板或打开系统分享 URL return } share({ title: Hello, text: Hello my friend!, url: location.href, }) }值得注意的是isSupported是响应式布尔值在UseShareReturn extends Supportable中与 VueUse 的useSupported语义一致可安全地在模板中控制分享按钮的显隐button v-ifisSupported clickstartShare分享/button降级方案示例依赖 Web Share API 不可用时的兜底路径import { useClipboard } from vueuse/core const { share, isSupported } useShare() const { copy } useClipboard() async function startShare() { if (isSupported.value) { await share({ title: Hello, text: Hello my friend!, url: location.href }) } else { await copy(location.href) // 降级复制链接 } }另外需要说明Web Share API 通常要求页面运行在安全上下文HTTPS中本地开发时localhost一般被视作安全上下文。若在非安全上下文的局域网环境调试分享功能需要留意这一点airi 的apps/stage-web提供dev:https脚本以支持 HTTPS 本地调试。七、错误处理用户取消与异常路径share()返回Promisevoid其 reject 路径至少包括两类情况用户主动取消分享面板平台会抛出AbortError当前环境不支持或分享被拒绝如权限、安全上下文限制。因此生产代码应捕获异常区分用户取消与真正失败避免把取消误报为错误async function startShare() { try { await share({ title: Hello, text: Hello my friend!, url: location.href }) } catch (error) { if (error instanceof Error error.name AbortError) { // 用户取消了分享无需提示 return } console.error(分享失败, error) } }八、在 airi 多端架构中的定位与适用场景airi 项目Self hosted 的虚拟角色陪伴应用包含 Webapps/stage-web、移动端apps/stage-pocket基于 Capacitor与桌面端apps/stage-tamagotchi基于 Electron等多端实现。其中apps/stage-web与apps/stage-pocket均已在package.json中声明vueuse/core依赖且源码中大量使用 VueUse 组合式函数如useLocalStorage、useBreakpoints、useDevicesList、useObjectUrl等这类浏览器能力函数之所以优先走 VueUse而不是各自手写封装正是 .agents/skills/vueuse-functions/SKILL.md 强调的工程原则优先用组合式函数替代自定义代码保持实现简洁、可维护、高性能。useShare在 airi 中的典型适用场景包括分享当前对话链接、分享角色介绍卡片、把生成的媒体文件通过files分享给其他应用。桌面 Electron 端如需原生分享能力则应评估平台差异——Web Share API 以 Web 与移动端支持为主桌面端更适合使用系统级分享或复制链接等替代方案。九、小结能力说明基础调用const { share, isSupported } useShare()在用户手势回调中调用share({ title, text, url, files })响应式绑定第一个参数支持对象 /ref/ getter调用时自动取最新值参数覆盖share(overrideOptions)可在调用时覆盖默认选项能力检测isSupported响应式标记配合降级方案如剪贴板使用错误处理捕获AbortError区分用户取消与真实失败约束必须在用户手势中调用通常要求 HTTPS 安全上下文useShare的价值在于它把平台 API 的探测、封装与响应式衔接全部收敛到一个组合式函数中让业务代码只需关心分享什么而不必操心怎么分享。在 airi 这样同时依赖 VueUse 生态的多端仓库中它是接入系统级分享能力最符合项目工程习惯的选择。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考