Navigator：share() 方法

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

安全上下文: 此项功能仅在一些 支持的浏览器 的 安全上下文 （HTTPS）中可用。

Navigator 接口的 share() 方法调用设备的本机共享机制来共享文本、URL 或文件等数据。可用的 共享目标 取决于设备，但可能包括剪贴板、联系人和电子邮件应用程序、网站、蓝牙等。

该方法用 undefined 兑现 Promise 。在 Windows 上，当共享弹出窗口启动时，就会发生这种情况，而在 Android 上，一旦数据成功传递到 共享目标 ，promise 就会兑现。

Web 共享 API 受 web-share 权限策略限制。如果支持该权限但尚未授予该权限，则 share() 方法将抛出异常。

语法

js 
navigator.share(data)
  
data 可选

    
包含要共享的数据的对象。

    
用户代理未知的属性将被忽略；共享数据仅根据用户代理可识别的属性进行评估。所有属性都是可选的，但必须至少指定一个已知的数据属性。

    
可能的值有：

      
url 可选

        
表示要共享的 URL 的字符串。

      
text 可选

        
表示要共享的文本的字符串。

      
title 可选

        
表示要共享的标题的字符串。

      
files 可选

        
表示要共享的文件的 File 对象数组。有关可共享的文件类型，请参阅下文。

返回值

一个兑现为 undefined 的 Promise ，或者被下面给出的 异常 之一拒绝。

异常

Promise 可能会以下列 DOMException 值之一被拒绝：

InvalidStateError DOMException

文档未完全激活，或正在进行其他共享操作。

NotAllowedError DOMException

web-share 权限策略 已用于阻止使用此特性，或当前文档不处于 瞬态激活 状态，或者出于安全考虑，文件共享被阻止。

TypeError

无法验证指定的共享数据。可能的原因包括：

  • data 参数被完全省略或仅包含具有未知值的属性。请注意，用户代理无法识别的任何属性都会被忽略。
  • URL 格式错误。
  • 指定了文件但用户代理实现不支持文件共享。
  • 共享的指定数据将被用户代理视为“恶意共享”。
    • AbortError DOMException

    用户取消了共享操作或没有可用的共享目标。

    DataError DOMException

    启动共享目标或传输数据时出现问题。

    可分享的文件类型

    以下是通常可共享的文件类型的列表。但是，你应该始终使用 navigator.canShare() 方法测试共享是否将会成功。

  • .pdf —— application/pdf
  • .flac —— audio/flac
  • .m4a —— audio/x-m4a
  • .mp3 —— audio/mpeg （也接受 audio/mp3 ）
  • .oga —— audio/ogg
  • .ogg —— audio/ogg
  • .opus —— audio/ogg
  • .wav —— audio/wav
  • .weba —— audio/webm
  • .avif —— image/avif
  • .bmp —— image/bmp
  • .gif —— image/gif
  • .ico —— image/x-icon
  • .jfif —— image/jpeg
  • .jpeg —— image/jpeg
  • .jpg —— image/jpeg
  • .pjp —— image/jpeg
  • .pjpeg —— image/jpeg
  • .png —— image/png
  • .svg —— image/svg+xml
  • .svgz —— image/svg+xml
  • .tif —— image/tiff
  • .tiff —— image/tiff
  • .webp —— image/webp
  • .xbm —— image/x-xbitmap
  • .css —— text/css
  • .csv —— text/csv
  • .ehtml —— text/html
  • .htm —— text/html
  • .html —— text/html
  • .shtm —— text/html
  • .shtml —— text/html
  • .text —— text/plain
  • .txt —— text/plain
  • .m4v —— video/mp4
  • .mp4 —— video/mp4
  • .mpeg —— video/mpeg
  • .mpg —— video/mpeg
  • .ogm —— video/ogg
  • .ogv —— video/ogg
  • .webm —— video/webm

    • 安全

    此方法要求当前文档具有 web-share 权限策略和 瞬态激活 状态。（它必须由 UI 事件触发，例如单击按钮，并且不能由脚本在任意点启动。）此外，该方法必须指定本机实现的支持共享的有效数据。

    示例

    分享一个 URL

    下面的示例显示了单击按钮调用 Web 共享 API 来共享 MDN 的 URL。这是取自我们的 Web 共享测试 （ 查看源代码 ）。

    HTML 只是创建一个用于触发共享的按钮，以及一个用于显示测试结果的段落。

    html 
    <p><button>分享 MDN！</button></p>
<p class="result"></p>

    JavaScript
    

    js
    const shareData = {
  title: "MDN",
  text: "在 MDN 上学习 Web 开发！",
  url: "https://developer.mozilla.org",
const btn = document.querySelector("button");
const resultPara = document.querySelector(".result");
// 分享必须由“用户激活”触发
btn.addEventListener("click", async () => {
  try {
    await navigator.share(shareData);
    resultPara.textContent = "MDN 分享成功";
  } catch (err) {
    resultPara.textContent = `错误：${err}`;

    单击该按钮可在你的平台上启动共享对话框。按钮下方将显示文本，指示共享是否成功或提供错误代码。