返回知识中心
平台

navigator.canShare() 与 Web Share API:分享边界

navigator.canShare() 与 navigator.share() 如何决定分享是否被接受、权限与文件限制在哪里不同,以及如何分别验证两条路径。

BotBrowser Team

文档中心

想直接进入 平台 文档吗?

这篇文章属于知识中心的指南库。若你要步骤化配置、参考说明和持续更新,请直接进入对应 docs 分区。

网页上的分享是把内容交给页面无法控制的一个界面。navigator.share() 请求浏览器把标题、URL、文本或一组文件交给用户选定的目标,页面只知道那个 promise 结束了。BotBrowser 可以在受控上下文中加载移动 profile,检查应用在不同视口和语言下如何摆放分享按钮及其替代路径;它不绘制操作系统的分享面板,不选择目标,也不授予调用所需的临时激活。当目标是已安装 PWA 时,Web Share Target PWA 的入口与隐私说明如何校验接收路由,而不把交付当作保留内容的许可。

摘要

  • 只在可信点击或按键里调用 navigator.share();用 setTimeout() 延迟或在页面加载时调用都会让临时激活过期。
  • 用用户已经看得到的内容构造分享对象,并先去掉 fragment、会话参数、令牌和记录标识。
  • 把 AbortError、NotAllowedError、TypeError 与 DataError 映射成四条不同提示,四种情况下都不要替换文档。
  • 从第一次尝试起就把 navigator.clipboard.writeText()、download 链接和普通地址放在可见位置,而不是等失败后再显示。
  • BotBrowser 在选定 profile 中检查按钮周围的响应式流程;分享面板、目标列表和激活判断仍由浏览器与操作系统负责。

本文目录

用户选择内容并查看分享交接,也可以使用替代操作

W3C Web Share 规范定义了分享模型以及它从平台继承的安全要求。MDN 指南、navigator.share() 与 navigator.canShare()说明了面向浏览器的接口与兼容性限制。三份文档描述的都是有条件的接口,没有任何一份承诺统一的目标、面板布局或跨平台结果。

从明确的用户操作开始

navigator.share() 只能在用户的临时激活期间执行。调用必须发生在浏览器仍承认可信事件授予的激活时,所以哪怕很短的 setTimeout()、scroll 监听器,或者 DOMContentLoaded 之后的自动调用,都会以 NotAllowedError 失败。把调用绑在一个控件的 click 与 keydown 处理器上,让这个控件负责整次尝试。

能力检测要写清楚:判断 typeof navigator.share === 'function'。只读 navigator.canShare 而不调用它证明不了什么,因为该方法在只接受文本与地址字段的浏览器上也存在。方法存在且 window.isSecureContext 为真时才渲染按钮;否则渲染一个禁用按钮,并简短说明页面必须通过 https 提供。

const shareButton = document.querySelector('[data-share]');

if (window.isSecureContext && typeof navigator.share === 'function') {
  shareButton.hidden = false;
  shareButton.addEventListener('click', event => {
    event.preventDefault();
    startShare(shareButton);
  });
}

async function startShare(button) {
  const data = { title: document.title, url: canonicalUrl() };
  if (!navigator.canShare(data)) return revealAlternative('copy');
  button.setAttribute('aria-busy', 'true');
  try {
    await navigator.share(data);
    announce('Share sheet closed');
  } catch (error) {
    announce(shareMessage(error));
  } finally {
    button.removeAttribute('aria-busy');
    button.focus();
  }
}

处理器在调用前不做任何 await,因为先完成的 promise 会消耗浏览器给这次点击的激活。canonicalUrl() 应返回用 new URL(location.href) 构造的绝对地址;相对路径、空字符串或 javascript: 值通不过校验,会把普通点击变成 TypeError。

按钮名称要描述动作,例如「分享这篇文章」而不是「分享」。只有图标时必须有 aria-label 与提示,并且点击区域至少 24 乘 24 个 CSS 像素,这样页面放大到 200 百分比时仍满足 WCAG 2.2 的目标尺寸下限。原生 <button> 会把 Enter 与 Space 转给同一个处理器,键盘路径因此与指针路径一致,无需额外代码。

不要预先打开面板、预取目标列表,也不要根据浏览器语言推断接收者。目标选择发生在浏览器或操作系统界面里,页面看不到这个选择。

在交接前校验数据

分享对象接受 title、text、url 和 files 数组。每个字段都可选,但至少要有一个携带数据,字段为空或格式错误的调用会以 TypeError 失败。用用户看得见的状态构造对象,而不是用内部会话数据。

字段安全来源调用前移除
titledocument.title 或可见标题记录标识、账号名称
text已渲染文档中的选中内容表单值、私人备注、令牌
url不含秘密参数的 canonicalUrl()fragment、签名下载参数
files用户刚刚生成的导出文件草稿、临时路径、他人的数据

navigator.canShare() 只回答一个很窄的问题:这个浏览器是否接受这种数据形状。它不回答已安装的目标是否会接收。结果为 false 时应在打开面板之前走替代路径,这比让用户去解读一次失败更省事。文件需要二次检查,因为在只分享文本与链接的浏览器上 canShare(data) 可能为真,而 canShare({ files: [file] }) 为假。

文件要给出名称与类型:new File([blob], 'statement-2026-10.txt', { type: 'text/plain' })。没有可读 type 的 File 能通过检查,却会在接收应用里失败。导出大小要保持在你自己下载路径已经执行的限制内,并在 promise 结束后调用 URL.revokeObjectURL(),避免大报表在取消后仍被引用。

清理地址整体,而不只是路径。location.href 带着 fragment 和全部查询参数,包括重定向添加的短期令牌。用 url.origin、url.pathname 和一份允许列表里的 url.search 重建分享地址,让 fragment 与会话参数到不了 navigator.share()。分享泄露 access_token 就是一次带着友好按钮的凭据泄露。

授权不会随分享转移。接收者在新的浏览上下文中打开地址,服务器必须重复同样的会话检查、同样的来源规则和同样的 403 路径,和粘贴链接时完全一样。关于浏览器中介的登录如何把校验留在服务器端,请参阅Credential Management API:设计更安全的浏览器登录流程;关于认证器在哪里证明持有,请参阅 Passkeys 与 WebAuthn:浏览器中的登录旅程。两者都不改变一条规则:收到的分享地址属于不可信输入。

把取消当作正常结束

交接完成、面板关闭时 promise 兑现,用户取消时 promise 被拒绝。Chromium 把取消报告为 AbortError,同一个名字也覆盖浏览器找不到可提供目标的情况。两种结果都正常,此时弹一个 alert() 只会无谓打断任务。

拒绝含义页面响应
AbortError面板被关闭,或没有可用目标保留文档,归还焦点,保持安静
NotAllowedError激活过期,或分享策略被阻止说明这里无法分享
TypeError字段非法、数据为空、地址不可用显示替代路径,修正构造逻辑
DataError文件无法读取或分享指明文件,提供下载

永远不要自动重试。让第一次调用成立的那次激活已经用完,重试循环只会产生一串 NotAllowedError,在某些浏览器里甚至没有任何可见反应。等下一次点击,那也是用户重新确认意图的时刻。

恢复界面时不要让人位移。焦点回到打开面板的元素,滚动位置保持不变,未保存的编辑器内容完好无损。用 role="status" 配 aria-live="polite" 宣布结果,让屏幕阅读器只听到一次「没有分享任何内容」,而不是打断正在朗读的句子。同时朗读消息的页面可以参考 SpeechSynthesis 语音与可访问的浏览器播放,其中讨论了语音选择与打断行为。

进行中状态要短且可逆。设置 button.disabled = true 会把控件移出 Tab 顺序,还可能吞掉发起调用的那次点击,因此更合适的做法是在仍可获得焦点的按钮上加 aria-busy。本地目标通常在一秒内完成,远程目标却可能让面板一直开着,页面必须在 promise 未结束时保持可用。

只记录结果,不记录内容。名为 share-completed、share-cancelled 与 share-unavailable 的计数器足以描述流程,不会把标题、地址或文件名写进日志。这类记录保持短期有效,也不要把分享可用性当作账号、设备或网络信号。

让复制与下载保持对等

替代路径用页面能控制的界面完成同样的意图,并且应与分享按钮同时出现在屏幕上,而不是藏在一次失败之后。三种表示能覆盖大多数产品。

替代方式原语可用条件
复制链接navigator.clipboard.writeText(url)安全上下文加新鲜手势
下载<a download="statement.txt" href="blob:...">导出文件已就绪
普通链接文档中的普通 <a href>始终可用

剪贴板写入失败比人们预想的多。navigator.clipboard 在安全上下文之外不存在,手势过期时 writeText() 以 NotAllowedError 拒绝,有些浏览器还会弹出可以被拒绝的权限提示。因此复制按钮需要两个可见状态,已复制与未复制,再加一个可选择的只读字段作为最后手段。带选中地址的可见 input 是诚实的;静默失败却宣称成功则不是。Clipboard API 与用户意图指南进一步把复制回退转化为独立的读取权限和数据最小化决定。

下载需要文件名和接收应用能打开的格式。创建 blob,把 URL.createObjectURL(blob) 设到链接上,并在下载完成或页面卸载时释放。生成过程慢时要显示进度并保持原文可读,一个没有解释的禁用按钮比不上明确说明的几秒等待。

把三个动作放在同一组里并给出不同标签:复制、下载、分享。视觉分组没问题,权限与结果却不能互换。复制把内容留在当前设备,分享把内容带出页面,而邀请会建立账号关系,需要独立的确认与授权。

这里有两个相关边界。浏览器权限边界说明能力检查为什么应靠近使用结果的代码,注重隐私的浏览器流程说明任务结束后页面应保留多少状态。替代路径复用同一个清理过的地址就会继承这两个决定,因此地址构造应集中在一个函数里。

让回退经受中断

网络状态不能证明交接完成。浏览器可以不经任何页面请求就把数据交给本地应用,远程目标也可能之后才需要自己的连接。页面只知道自己发起过请求,所以「面板已打开」或「分享已取消」是诚实标签,而「已送达」是代码无法支撑的说法。

中断会改变人的预期。带着未结束 promise 的标签页切到后台后可能带着已经关闭的面板返回,因此要在 visibilitychange 时重新读取按钮状态,而不是假设 finally 块在文档可见时执行过。把进行中的标记放在与 <form> 兼容的位置,并让迟到的拒绝只更新仍在屏幕上的提示。

离线或断续连接不改变交互模型。本地文章在断网时仍能提供可复制的地址,导出文件则可以等生成完成。要说明表示是否就绪,保持当前内容可读,避免出现没有原因的禁用控件。

分享常与打印、保存、邀请并列。给每个动作独立标签并说明实质差异。打印把内容留在当前标签页,保存产生本地副本,分享把数据交给另一个应用,邀请可能建立需要确认的账号关系。把它们视觉分组是合理的,合并它们的权限则不是。

语言会改变排版余地。较长的译文会让按钮标签换行,从右到左的文本会改变固定边距图标的顺序,非拉丁文字会改变同一字符串的测量宽度。用你发布的最长语言做测试,保持文档 lang 属性准确,并让状态提示与标签一起翻译,避免同屏出现两种语言的取消提示。

复查上下文、支持范围与结果

在每个支持的浏览器族里跑同一张小结果矩阵,并把表格行当作产品契约,而不是某一家面板的说明。

场景准备预期结果
正常路径安全页面,真实点击面板打开,promise 完成
取消关闭面板AbortError,文档保持完整
缺少 API删除 navigator.share替代路径在首帧可见
策略阻止不带 allow="web-share" 的 <iframe>NotAllowedError,替代路径仍在
数据非法canonicalUrl() 返回相对路径TypeError,替代路径仍在

内嵌文档需要在 <iframe> 上写 allow="web-share",若宿主发送响应头还需 Permissions-Policy: web-share=(self)。缺少任何一项,即便真实点击也会以 NotAllowedError 失败,组件必须保留自己的复制路径。在不转发该指令的 webview 中打开的页面同理。

自动化测试可以用三种方式替换该方法:一个兑现的函数、一个以 new DOMException('cancelled', 'AbortError') 拒绝的函数,以及完全没有该方法。断言应检查可见状态而不是调用次数,从而覆盖可达的替代路径、幸存的草稿和只出现一次的状态提示。用 DOMException 构造能保留处理器分支所依赖的 name 属性,普通 Error 做不到这一点。

测量你自己控制的那条路径。替代路径完成时打上 performance.mark('share-complete') 标记,在支持会话中用 PerformanceObserver 读取,而不是从用户反馈里猜。关于在浏览器中观察应用运行状况,可参阅 使用 PerformanceObserver 观察 Web 应用健康度。

来源

实践结论

把分享当作任务的一条可选分支,任务必须在没有分享时也能完成。把 navigator.share() 绑在可信事件上,发布清理后的绝对地址,并把 AbortError、NotAllowedError、TypeError 与 DataError 映射成四条彼此不同且安静的响应。

从首帧起就保留 navigator.clipboard.writeText()、download 链接与普通地址,让缺少目标、策略阻止或面板取消都不给读者带来代价。BotBrowser 支持使用移动 profile 浏览器流程检查应用的响应式分享界面,但不模拟操作系统分享面板或分享目标,也不保证用户激活状态。

#Web Share API#分享#可访问性#隐私

本文属于指南: Web 平台能力面:一致性复核地图

在 BotBrowser 里跑一遍同样的检查

加载 profile,让刚读到的这些信号在浏览器内部保持一致,并在正式上线前先在自己的机器上确认结果。