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 共享 APIweb-share 权限策略限制。如果支持该权限但尚未授予该权限,则 share() 方法将抛出异常。

语法

js
navigator.share(data)

参数

data 可选

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

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

可能的值有:

url 可选

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

text 可选

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

title 可选

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

files 可选

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

返回值

一个兑现为 undefinedPromise,或者被下面给出的异常之一拒绝。

异常

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 只是创建一个用于触发共享的按钮,以及一个用于显示测试结果的段落。

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}`;
  }
});

结果

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

分享文件

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

HTML

html
<div>
  <label for="files">选择要分享的图像:</label>
  <input id="files" type="file" accept="image/*" multiple />
</div>
<button id="share" type="button">分享你的图片!</button>
<output id="output"></output>

JavaScript

请注意,传递给 navigator.canShare() 的数据对象仅包含 files 属性,因为 titletext 并不重要。

js
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 = "未选择任何文件。";
    return;
  }

  // 检测 navigator.canShare() 特性和检测 navigator.share() 特性是一样的
  if (!navigator.canShare) {
    output.textContent = "您的浏览器不支持 Web 共享 API。";
    return;
  }

  if (navigator.canShare({ files })) {
    try {
      await navigator.share({
        files,
        title: "图像",
        text: "美丽的图像",
      });
      output.textContent = "分享成功!";
    } catch (error) {
      output.textContent = `错误:${error.message}`;
    }
  } else {
    output.textContent = "您的系统不支持共享这些文件。";
  }
});

结果

规范

Specification
Web Share API
# share-method

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
share
data.files parameter
data.text parameter

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
See implementation notes.
User must explicitly enable this feature.
Has more compatibility info.

参见