Navigator:share() 方法
Navigator
接口的 share()
方法调用设备的本机共享机制来共享文本、URL 或文件等数据。可用的共享目标取决于设备,但可能包括剪贴板、联系人和电子邮件应用程序、网站、蓝牙等。
该方法用 undefined
兑现 Promise
。在 Windows 上,当共享弹出窗口启动时,就会发生这种情况,而在 Android 上,一旦数据成功传递到共享目标,promise 就会兑现。
Web 共享 API 受 web-share 权限策略限制。如果支持该权限但尚未授予该权限,则 share()
方法将抛出异常。
语法
navigator.share(data)
参数
返回值
异常
Promise
可能会以下列 DOMException
值之一被拒绝:
InvalidStateError
DOMException
-
文档未完全激活,或正在进行其他共享操作。
NotAllowedError
DOMException
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
安全
示例
分享一个 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}`;
}
});
结果
单击该按钮可在你的平台上启动共享对话框。按钮下方将显示文本,指示共享是否成功或提供错误代码。
分享文件
要共享文件,请首先测试并调用 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 = "您的系统不支持共享这些文件。";
}
});
结果
规范
Specification |
---|
Web Share API # share-method |
浏览器兼容性
BCD tables only load in the browser