大网数据广告活动
Web 标准与前端开发

Navigator:share() 方法

· 52CE 我爱测

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

Web Share API

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

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

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

语法

share(data)

参数

  • data
    • : 包含要共享的数据的对象。

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

      可能的值有:

      • url
        • : 表示要共享的 URL 的字符串。
      • text
        • : 表示要共享的文本的字符串。
      • title
        • : 表示要共享的标题的字符串。
      • files
        • : 表示要共享的文件的 File 对象数组。有关可共享的文件类型,请参阅下文。

返回值

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

异常

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

  • InvalidStateError DOMException
    • : 文档未完全激活,或正在进行其他共享操作。
  • NotAllowedError DOMException
    • : web-share 权限策略已用于阻止使用此特性,或当前文档不处于transient activation状态,或者出于安全考虑,文件共享被阻止。
  • 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 权限策略和transient activation状态。(它必须由 UI 事件触发,例如单击按钮,并且不能由脚本在任意点启动。)此外,该方法必须指定本机实现的支持共享的有效数据。

示例

分享一个 URL

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

HTML

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

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

JavaScript

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

结果

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

分享一个 URL

分享文件

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

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 属性,因为 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 = "未选择任何文件。";
    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 = "您的系统不支持共享这些文件。";
  }
});

结果

分享文件

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。