navigator.canShare() и Web Share API: границы обмена
Как navigator.canShare() и navigator.share() решают, будет ли обмен принят, чем отличаются разрешения и ограничения файлов и как проверить оба пути.
BotBrowser Team
Нужна структурированная документация по теме Платформа?
Эта статья относится к редакционной библиотеке. Для пошаговой настройки, справки и постоянных обновлений переходите сразу в соответствующий раздел docs.
Обмен в вебе есть передача содержимого поверхности, которой страница не управляет. navigator.share() просит браузер передать заголовок, URL, текст или набор файлов той цели, которую выберет человек, а страница узнаёт лишь то, что обещание завершилось. BotBrowser может загрузить мобильный профиль в контролируемом контексте и проверить, как приложение располагает кнопку обмена и резервный путь при разных размерах окна и языках; он не рисует системную панель обмена, не выбирает цель и не выдаёт временную активацию, которой требует вызов. Если целью является установленная PWA, вход Web Share Target PWA и приватность объясняет проверку принимающего маршрута без превращения доставки в разрешение хранить содержимое.
Кратко
- Вызывайте
navigator.share()из доверенного клика или нажатия клавиши; задержка черезsetTimeout()или вызов при загрузке страницы дают временной активации истечь. - Собирайте объект обмена из того, что человек уже видит, и заранее убирайте фрагмент, параметры сессии, токены и идентификаторы записей.
- Различайте
AbortError,NotAllowedError,TypeErrorиDataErrorчетырьмя разными сообщениями и ни в одном случае не подменяйте документ. - Держите
navigator.clipboard.writeText(), ссылкуdownloadи обычный адрес видимыми с первой попытки, а не после отказа. - BotBrowser проверяет адаптивный сценарий вокруг кнопки в выбранном профиле; панель, список целей и решение об активации остаются за браузером и операционной системой.
Содержание
- Начните с явного действия пользователя
- Проверяйте данные до передачи
- Считайте отмену обычным завершением
- Сохраняйте копирование и скачивание равноправными
- Сделайте резервный путь устойчивым к прерываниям
- Проверяйте контексты, поддержку и результаты
Спецификация W3C Web Share описывает модель и требования безопасности, унаследованные от платформы. MDN, navigator.share() и navigator.canShare() описывают методы и ограничения совместимости. Все три документа описывают условную возможность; ни один не обещает одну цель, одну раскладку панели или одинаковый результат на всех платформах.
Начните с явного действия пользователя
navigator.share() выполняется только внутри временной активации пользователя. Вызов должен произойти, пока браузер ещё учитывает активацию, выданную доверенному событию, поэтому setTimeout() даже с короткой задержкой, слушатель scroll или автоматический вызов после DOMContentLoaded заканчиваются отказом NotAllowedError. Привязывайте вызов к обработчикам click и keydown одной кнопки и оставляйте всю попытку этой кнопке.
Проверяйте typeof navigator.share === 'function'. Чтение navigator.canShare без вызова ничего не доказывает, потому что метод существует и в браузерах, принимающих только поля текста и адреса. Показывайте кнопку, когда метод есть и window.isSecureContext истинно; иначе показывайте неактивную кнопку с короткой пометкой, что странице нужен https.
const shareButton = document.querySelector('[data-share]');
if (window.isSecureContext && typeof navigator.share === 'function') {
shareButton.hidden = false;
shareButton.addEventListener('click', event => {
event.preventDefault();
startShare(shareButton);
});
}
async function startShare(button) {
const data = { title: document.title, url: canonicalUrl() };
if (!navigator.canShare(data)) return revealAlternative('copy');
button.setAttribute('aria-busy', 'true');
try {
await navigator.share(data);
announce('Share sheet closed');
} catch (error) {
announce(shareMessage(error));
} finally {
button.removeAttribute('aria-busy');
button.focus();
}
}
Обработчик ничего не ждёт перед вызовом, потому что уже завершённое обещание способно израсходовать активацию, выданную клику. canonicalUrl() должен возвращать абсолютный адрес, собранный через new URL(location.href). Относительный путь, пустая строка или значение javascript: не проходят проверку и превращают обычный клик в TypeError.
Называйте кнопку по действию, например «Поделиться статьёй», а не «Поделиться». Кнопке только с иконкой нужны aria-label и видимая подсказка, а её площадь должна быть не меньше 24 на 24 пикселя CSS, чтобы при увеличении страницы до 200 процентов сохранялся минимальный размер цели по WCAG 2.2. Нативный <button> сам передаёт Enter и Space в тот же обработчик, поэтому путь с клавиатуры совпадает с путём мыши без дополнительного кода.
Не открывайте панель заранее, не подгружайте список целей и не выводите получателя из языка браузера. Человек выбирает назначение внутри браузера или системной поверхности, и страница этого выбора не видит.
Проверяйте данные до передачи
Объект обмена принимает title, text, url и массив files. Каждое поле необязательно, хотя бы одно должно нести данные, а вызов с пустыми или неверно оформленными полями отклоняется с TypeError. Собирайте объект из того состояния, которое человек видит, а не из внутренних данных сессии.
| Поле | Безопасный источник | Что убрать до вызова |
|---|---|---|
title | document.title или видимый заголовок | идентификаторы записей, названия аккаунтов |
text | выделение из отрисованного документа | значения формы, личные заметки, токены |
url | canonicalUrl() без секретных параметров | фрагмент, подписанные параметры скачивания |
files | экспорт, который человек только что создал | черновики, временные пути, чужие данные |
navigator.canShare() отвечает на узкий вопрос: примет ли этот браузер такую форму данных. Она не говорит, примет ли её установленная цель. Результат false ведёт в резервный путь до открытия панели, и это дешевле отказа, который человеку приходится разбирать. Для файлов нужна вторая проверка, потому что canShare(data) может быть истинным, а canShare({ files: [file] }) ложным в браузере, который делится только текстом и ссылками.
Для файла задайте имя и тип: new File([blob], 'statement-2026-10.txt', { type: 'text/plain' }). File без читаемого type проходит проверку и затем подводит в принимающем приложении. Держите экспорт в пределах размера, который уже ограничивает ваш путь скачивания, и вызывайте URL.revokeObjectURL() сразу после завершения обещания, чтобы крупный отчёт не оставался в памяти после отмены.
Очищайте весь адрес, а не только путь. location.href несёт фрагмент и все параметры запроса, включая короткоживущий токен, добавленный перенаправлением. Собирайте адрес для обмена из url.origin, url.pathname и разрешённого url.search, чтобы фрагмент и параметры сессии не доходили до navigator.share(). Обмен, который выдаёт access_token, становится утечкой учётных данных с дружелюбной кнопкой сверху.
Авторизация не переезжает. Получатель открывает адрес в новом контексте навигации, где сервер обязан повторить ту же проверку сессии, то же правило источника и тот же путь 403, что и для вставленной ссылки. Credential Management API: надёжный вход через браузер показывает, как вход через посредство браузера оставляет проверку серверу, а Passkeys и WebAuthn: путь входа в браузере объясняет, где аутентификатор доказывает владение. Ни один из материалов не меняет правила о том, что полученный адрес является недоверенным вводом.
Считайте отмену обычным завершением
Обещание исполняется, когда панель закрывается после передачи, и отклоняется, когда человек отменяет действие. Chromium сообщает об отмене как AbortError, и то же имя покрывает случай, когда браузер не нашёл ни одной цели. Оба исхода нормальны, поэтому alert() в этот момент прерывает задачу без причины.
| Отказ | Значение | Ответ страницы |
|---|---|---|
AbortError | панель закрыта или цели не нашлось | сохранить документ, вернуть фокус, молчать |
NotAllowedError | активация истекла или политика обмена заблокирована | объяснить, что обмен здесь заблокирован |
TypeError | неверные поля, пустые данные, непригодный адрес | показать резервный путь, исправить сборку |
DataError | файл не удалось прочитать или передать | назвать файл, предложить скачивание |
Никогда не повторяйте попытку автоматически. Активация, сделавшая первый вызов допустимым, израсходована, поэтому цикл повторов даёт цепочку отказов NotAllowedError, а в некоторых браузерах вообще никакой видимой реакции. Ждите следующего клика: в этот момент человек заново подтверждает намерение.
Возвращайте интерфейс, никого не перемещая. Фокус возвращается к элементу, открывшему панель, позиция прокрутки остаётся на месте, а несохранённый текст редактора переживает всё без изменений. Объявляйте результат через role="status" и aria-live="polite", чтобы экранный диктор один раз услышал «Ничего не отправлено», а не перебивал читаемое предложение. Страницы, которые ещё и проговаривают сообщения, могут опереться на Голоса синтеза речи и доступное воспроизведение в браузере, где рассматривается выбор голоса и прерывание.
Состояние ожидания должно быть коротким и обратимым. button.disabled = true убирает кнопку из порядка табуляции и может проглотить клик, начавший вызов, поэтому предпочтителен aria-busy на кнопке, которая остаётся в фокусе. Локальная цель обычно завершает обещание меньше чем за секунду, но удалённая может держать панель открытой, и страница должна оставаться рабочей, пока обещание не завершено.
Записывайте исход, но не содержимое. Счётчики share-completed, share-cancelled и share-unavailable описывают сценарий, не перенося заголовок, адрес или имя файла в журнал. Храните такую запись недолго и не используйте доступность обмена как признак аккаунта, устройства или сети.
Сохраняйте копирование и скачивание равноправными
Резервный путь несёт то же намерение через поверхность, которой страница управляет, и должен быть на экране рядом с кнопкой обмена, а не за отказом. Три представления покрывают большинство продуктов.
| Альтернатива | Примитив | Доступна когда |
|---|---|---|
| копировать ссылку | navigator.clipboard.writeText(url) | защищённый контекст и свежий жест |
| скачивание | <a download="statement.txt" href="blob:..."> | экспорт готов |
| обычная ссылка | обычный <a href> в документе | всегда |
Запись в буфер обмена отказывает чаще, чем ожидают. navigator.clipboard не существует вне защищённого контекста, writeText() отклоняется с NotAllowedError, когда жест истёк, а некоторые браузеры показывают запрос разрешения, от которого можно отказаться. Поэтому кнопке копирования нужны два видимых состояния, скопировано и нет, плюс доступное для выделения поле только для чтения как последний вариант. Видимый input с выделенным адресом честен, а молчаливый отказ, выдающий себя за успех, нет. Руководство по API буфера обмена и намерению пользователя превращает этот запасной путь копирования в отдельное решение о чтении и минимизации данных.
Скачиванию нужны имя файла и формат, который принимающее приложение умеет открыть. Создайте blob, поставьте URL.createObjectURL(blob) на ссылку и освободите его, когда скачивание завершится или страница выгрузится. Если генерация медленная, показывайте прогресс и оставляйте исходное содержимое читаемым: неактивная кнопка без объяснения хуже названного ожидания в несколько секунд.
Держите все три действия в одной группе с разными подписями: копировать, скачать, поделиться. Визуальная группировка уместна, а разрешения и результаты не взаимозаменяемы. Копирование оставляет содержимое на текущем устройстве, обмен выводит его за пределы страницы, а приглашение создало бы связь с аккаунтом, требующую отдельного подтверждения и авторизации.
Здесь важны две смежные границы. Границы разрешений браузера объясняют, почему проверка возможностей должна жить рядом с кодом, который использует результат, а приватность веб-процессов описывает, сколько состояния страница вправе хранить после задачи. Резервный путь, переиспользующий тот же очищенный адрес, наследует оба решения, поэтому сборщик адреса должен быть одной функцией.
Сделайте резервный путь устойчивым к прерываниям
Состояние сети не доказывает, что передача состоялась. Браузер может отдать данные локальному приложению без единого запроса страницы, а удалённой цели позже понадобится собственное соединение. Страница знает лишь, что запросила передачу, поэтому «панель открыта» и «обмен отменён» остаются честными подписями, а «доставлено» превращается в утверждение, которого код не подтверждает.
Прерывание меняет ожидания человека. Вкладка, ушедшая в фон с незавершённым обещанием, может вернуться с уже закрытой панелью, поэтому перечитывайте состояние кнопки по visibilitychange, а не предполагайте, что блок finally выполнился при видимом документе. Храните признак ожидания в совместимом с <form> месте и позволяйте позднему отказу обновлять только сообщение, которое ещё на экране.
Отсутствующее или нестабильное соединение не меняет модель взаимодействия. Локальная статья может предложить копируемый адрес и без сети, а экспорт может подождать, пока файл сгенерируется. Показывайте, готова ли репрезентация, сохраняйте читаемость текущего содержимого и избегайте неактивной кнопки без причины.
Обмен часто стоит рядом с печатью, сохранением и приглашением. Дайте каждому действию отдельную подпись и называйте реальные различия. Печать оставляет содержимое во вкладке, сохранение создаёт локальную копию, обмен передаёт данные другому приложению, а приглашение может создать связь с аккаунтом и требует подтверждения. Группировать их визуально разумно, а объединять их разрешения нельзя.
Язык меняет то, что помещается. Длинный переведённый заголовок переносит подпись кнопки, текст справа налево переставляет иконку с фиксированным отступом, а нелатинская письменность меняет измеренную ширину той же строки. Проверяйте на самом длинном поставляемом языке, держите атрибут lang документа точным и переводите сообщения о состоянии вместе с подписями, чтобы отмена не появлялась на втором языке на том же экране.
Проверяйте контексты, поддержку и результаты
Прогоняйте одну и ту же небольшую матрицу результатов в каждом поддерживаемом семействе браузеров и храните строки как продуктовый контракт, а не как описание панели одного поставщика.
| Случай | Подготовка | Ожидаемый результат |
|---|---|---|
| обычный путь | защищённая страница, реальный клик | панель открывается, обещание завершается |
| отмена | панель закрыта | AbortError, документ цел |
| нет API | navigator.share удалён | резервный путь виден с первой отрисовки |
| заблокированная политика | <iframe> без allow="web-share" | NotAllowedError, резервный путь остаётся |
| неверные данные | canonicalUrl() вернул относительный путь | TypeError, резервный путь остаётся |
Встроенному документу нужны allow="web-share" на <iframe> и, если хост отправляет заголовок, Permissions-Policy: web-share=(self). Без любого из двух вызов отклоняется с NotAllowedError даже после реального клика, и компонент обязан сохранить собственный путь копирования. То же относится к странице, открытой внутри webview, который не передаёт директиву.
Автотесты подменяют метод тремя способами: функция, которая исполняется, функция, которая отклоняется с new DOMException('cancelled', 'AbortError'), и полное отсутствие метода. Проверяйте видимое состояние, а не число вызовов, чтобы покрыть достижимый резервный путь, сохранённый черновик и сообщение о состоянии, которое появляется один раз. Создание DOMException сохраняет свойство name, по которому ветвится обработчик, а обычный Error этого не даёт.
Измеряйте тот путь, которым управляете. Ставьте отметку performance.mark('share-complete'), когда резервный путь завершается, и читайте её через PerformanceObserver во время сеанса поддержки вместо догадок по отзывам. PerformanceObserver для здоровья веб-приложения показывает, как держать такое измерение локальным и недолгим.
Источники
Итоги и практические выводы
Считайте обмен необязательной ветвью задачи, которая должна завершаться и без него. Ставьте navigator.share() в зависимость от доверенного события, публикуйте очищенный абсолютный адрес и различайте AbortError, NotAllowedError, TypeError и DataError четырьмя отдельными и спокойными ответами.
Держите navigator.clipboard.writeText(), ссылку download и обычный адрес видимыми с первой отрисовки, чтобы отсутствующая цель, заблокированная политика или закрытая панель ничего не стоили читателю. BotBrowser поддерживает мобильные сценарии браузера с профилем для проверки адаптивного интерфейса «Поделиться», но не имитирует системную панель обмена и её получателей и не гарантирует активацию пользователя.
Эта статья входит в руководство: Поверхности веб-платформы: карта проверки
Похожие статьи
Web Share API: границы разрешений и безопасные запасные варианты
ПлатформаВход Web Share Target PWA и конфиденциальность
ПлатформаBadging API: границы уведомлений PWA
ПлатформаEyeDropper API: активация и приватность цвета
ПлатформаPayment Request API: согласие и безопасный запасной путь
ПлатформаIdle Detection API: контроль, разрешения и приватность
Выполните ту же проверку в BotBrowser
Загрузите профиль, сохраните внутри браузера те сигналы, о которых только что прочитали, и подтвердите результат на своей машине до раскатки.