Navigator: метод share()

Метод share() интерфейса Navigator вызывает механизм совместного использования данных устройства для обмена данными, такими как текст, URL-адреса или файлы. Доступные цели обмена зависят от устройства, но могут включать буфер обмена, приложения контактов и электронной почты, веб-сайты, Bluetooth и т.д.

Метод разрешает Promise со значением undefined. В Windows это происходит при запуске всплывающего окна обмена, а в Android обещание выполняется, как только данные успешно переданы в цель обмена.

API веб-обмена управляется политикой разрешений web-share. Метод share() будет генерировать исключения, если разрешение поддерживается, но не предоставлено.

data Необязательно

Объект, содержащий данные для обмена.

Свойства, неизвестные пользовательскому агенту, игнорируются; данные обмена оцениваются только по свойствам, понятным пользовательскому агенту. Все свойства необязательны, но должно быть указано хотя бы одно известное свойство данных.

Возможные значения:

url Необязательно

Строка, представляющая URL-адрес, который нужно поделиться.

text Необязательно

Строка, представляющая текст, который нужно поделиться.

title Необязательно

Строка, представляющая заголовок для совместного использования. Может быть проигнорировано целевым приложением.

files Необязательно

Массив объектов File, представляющих файлы, которые нужно поделиться. См. ниже для типов файлов, которые можно поделиться.

A Promise, который завершается значением undefined, или отклоняется с одним из исключений, указанных ниже.

Обещание Promise может быть отклонено с одним из следующих DOMException значений:

InvalidStateError DOMException

Документ не полностью активен или другие операции обмена находятся в процессе.

NotAllowedError DOMException

Политика разрешений web-share Permissions Policy была использована для блокировки использования этой функции, окно не имеет взаимодействия с пользователем, или обмен файлами заблокирован по соображениям безопасности.

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 и временное активирование. (Он должен быть инициирован событием пользовательского интерфейса, таким как нажатие кнопки, и не может быть запущен в произвольные моменты скриптом). Кроме того, метод должен указывать валидные данные, поддерживаемые для обмена родной реализацией.

В приведенном ниже примере демонстрируется нажатие кнопки, вызывающее API веб-обмена для обмена URL-адресом MDN. Это взято из нашего теста веб-обмена (см. исходный код).

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://developer.mozilla.org",
};

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/ (тесты веб-платформы)