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.club.tw",
};

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 平臺測試)