Navigator: share() 方法

语法

share(data)

参数

data 可选

包含要共享数据的对象。

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

可能的值是

url 可选

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

text 可选

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

title 可选

表示要共享的标题的字符串。目标可能会忽略此字段。

files 可选

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

返回值

一个 Promise，它将以 `undefined` 解析，或使用下方的异常之一拒绝。

异常

该 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 Share API 来共享 MDN 的 URL。这摘自我们的Web share 测试（查看源代码）。

HTML

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

<p><button>Share MDN!</button></p>
<p class="result"></p>

JavaScript

const shareData = {
  title: "MDN",
  text: "Learn web development on MDN!",
  url: "https://mdn.org.cn",
};

const btn = document.querySelector("button");
const resultPara = document.querySelector(".result");

// Share must be triggered by "user activation"
btn.addEventListener("click", async () => {
  try {
    await navigator.share(shareData);
    resultPara.textContent = "MDN shared successfully";
  } catch (err) {
    resultPara.textContent = `Error: ${err}`;
  }
});

结果

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

共享文件

要共享文件，请先测试并调用 navigator.canShare()。然后在对 navigator.share() 的调用中包含文件列表。

HTML

<div>
  <label for="files">Select images to share:</label>
  <input id="files" type="file" accept="image/*" multiple />
</div>
<button id="share" type="button">Share your images!</button>
<output id="output"></output>

JavaScript

请注意，传递给 navigator.canShare() 的数据对象仅包含 files 属性，因为 title 和 text 不应该有影响。

const input = document.getElementById("files");
const output = document.getElementById("output");

document.getElementById("share").addEventListener("click", async () => {
  const files = input.files;

  if (files.length === 0) {
    output.textContent = "No files selected.";
    return;
  }

  // feature detecting navigator.canShare() also implies
  // the same for the navigator.share()
  if (!navigator.canShare) {
    output.textContent = `Your browser doesn't support the Web Share API.`;
    return;
  }

  if (navigator.canShare({ files })) {
    try {
      await navigator.share({
        files,
        title: "Images",
        text: "Beautiful images",
      });
      output.textContent = "Shared!";
    } catch (error) {
      output.textContent = `Error: ${error.message}`;
    }
  } else {
    output.textContent = `Your system doesn't support sharing these files.`;
  }
});

结果

规范

浏览器兼容性

另见

• navigator.canShare()
• https://wpt.live/web-share/ (Web 平台测试)