navigator.canShare() et la Web Share API : limites du partage
Comment navigator.canShare() et navigator.share() décident si un partage est accepté, où diffèrent les permissions et les limites de fichiers, et comment tester les deux.
BotBrowser Team
Vous voulez la documentation structurée pour Plateforme ?
Cet article fait partie de la bibliothèque éditoriale. Pour les étapes de configuration, la référence et les mises à jour continues, passez directement à la section docs.
Partager sur le web revient à remettre un contenu à une surface que la page ne contrôle pas. navigator.share() demande au navigateur de transmettre un titre, une URL, un texte ou un ensemble de fichiers vers la cible choisie par la personne, et la page apprend seulement que la promesse s’est réglée. BotBrowser peut charger un profil mobile dans un contexte contrôlé pour examiner la disposition du contrôle de partage et de sa solution de repli selon les tailles de fenêtre et les langues ; il ne dessine pas le panneau de partage du système, ne choisit aucune cible et n’accorde pas l’activation temporaire exigée par l’appel. Lorsque la cible est une PWA installée, Entrée et confidentialité d’une PWA Web Share Target explique comment valider la route de réception sans transformer la livraison en permission de conserver le contenu.
Résumé
- Appelez
navigator.share()depuis un clic ou une touche de confiance ; un délaisetTimeout()ou un appel au chargement laisse expirer l’activation temporaire. - Construisez l’objet partagé à partir de ce que la personne voit déjà et retirez d’abord le fragment, les paramètres de session, les jetons et les identifiants d’enregistrement.
- Traduisez
AbortError,NotAllowedError,TypeErroretDataErroren quatre messages distincts et ne remplacez jamais le document dans l’un de ces cas. - Gardez
navigator.clipboard.writeText(), un liendownloadet l’adresse simple visibles dès la première tentative, et non après un refus. - BotBrowser examine le parcours adaptatif autour du contrôle avec un profil choisi ; le panneau, la liste des cibles et la décision d’activation restent au navigateur et au système.
Sommaire
- Commencez par une action explicite
- Validez les données avant le transfert
- Traitez l’annulation comme une fin ordinaire
- Gardez la copie et le téléchargement au premier plan
- Rendez la solution de repli résistante aux interruptions
- Vérifiez les contextes, la prise en charge et les résultats
La spécification W3C Web Share définit le modèle et les exigences de sécurité héritées de la plateforme. Le guide MDN, navigator.share() et navigator.canShare() documentent les méthodes et les limites de compatibilité. Les trois documents décrivent une capacité conditionnelle ; aucun ne promet une cible, une disposition du panneau ni un résultat identique sur toutes les plateformes.
Commencez par une action explicite
navigator.share() ne s’exécute que dans une activation temporaire de la personne. L’appel doit avoir lieu pendant que le navigateur honore encore l’activation accordée à un événement de confiance : un setTimeout() même court, un écouteur scroll ou un appel automatique après DOMContentLoaded finissent donc par un refus NotAllowedError. Rattachez l’appel aux gestionnaires click et keydown d’un seul contrôle et laissez ce contrôle porter toute la tentative.
Testez typeof navigator.share === 'function'. Lire navigator.canShare sans l’appeler ne prouve rien, car la méthode existe aussi sur des navigateurs qui n’acceptent que les membres texte et URL. Affichez le contrôle quand la méthode existe et que window.isSecureContext est vrai ; sinon, affichez un contrôle désactivé avec une note courte indiquant que la page doit être servie en 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();
}
}
Le gestionnaire n’attend rien avant l’appel, car une promesse déjà réglée peut consommer l’activation accordée au clic. canonicalUrl() doit renvoyer une adresse absolue construite avec new URL(location.href). Un chemin relatif, une chaîne vide ou une valeur javascript: échoue à la validation et transforme un clic ordinaire en TypeError.
Nommez le contrôle d’après l’action, par exemple « Partager cette page » plutôt que « Partager ». Un déclencheur réduit à une icône a besoin d’un aria-label et d’une aide visible, et sa zone doit mesurer au moins 24 par 24 pixels CSS pour respecter la taille de cible minimale de WCAG 2.2 lorsque la page est agrandie à 200 pour cent. Un élément <button> natif transmet déjà Enter et Space au même gestionnaire, ce qui garde le parcours clavier identique au parcours pointeur sans code supplémentaire.
N’ouvrez pas le panneau à l’avance, ne préchargez pas une liste de cibles et ne déduisez pas un destinataire de la langue du navigateur. La personne choisit la destination dans le navigateur ou dans la surface du système, et la page n’en voit rien.
Validez les données avant le transfert
L’objet de partage accepte title, text, url et un tableau files. Chaque membre est facultatif, au moins un doit porter des données, et un appel dont les membres sont vides ou mal formés est refusé avec TypeError. Construisez l’objet à partir de l’état que la personne voit, jamais à partir de données de session internes.
| Membre | Source sûre | À retirer avant l’appel |
|---|---|---|
title | document.title ou un titre visible | identifiants d’enregistrement, libellés de compte |
text | une sélection du document affiché | valeurs de formulaire, notes privées, jetons |
url | canonicalUrl() sans paramètre secret | le fragment, les paramètres de téléchargement signés |
files | une exportation que la personne vient de créer | brouillons, chemins temporaires, données d’un tiers |
navigator.canShare() répond à une question étroite : ce navigateur acceptera-t-il cette forme de données. Elle ne dit pas si une cible installée l’acceptera. Un résultat false appartient à la solution de repli avant l’ouverture du panneau, ce qui coûte moins qu’un refus à interpréter. Les fichiers exigent une seconde vérification, car canShare(data) peut être vrai alors que canShare({ files: [file] }) est faux sur un navigateur qui ne partage que texte et liens.
Pour un fichier, nommez l’objet et déclarez son type : new File([blob], 'statement-2026-10.txt', { type: 'text/plain' }). Un File sans type lisible peut passer la vérification et échouer dans l’application réceptrice. Gardez l’exportation dans la limite de taille que votre propre chemin de téléchargement applique déjà, et appelez URL.revokeObjectURL() dès que la promesse se règle, afin qu’un rapport volumineux ne reste pas référencé après une annulation.
Assainissez l’adresse entière, pas seulement le chemin. location.href transporte le fragment et chaque paramètre de requête, y compris un jeton de courte durée ajouté par une redirection. Reconstruisez l’adresse partagée à partir de url.origin, url.pathname et d’un url.search autorisé, de sorte que le fragment et les paramètres de session n’atteignent jamais navigator.share(). Un partage qui laisse fuiter un access_token est une fuite d’identifiants avec un bouton aimable par-dessus.
L’autorisation ne bouge pas. La personne destinataire ouvre l’adresse dans un nouveau contexte de navigation, où le serveur doit répéter la même vérification de session, la même règle d’origine et le même chemin 403 que pour un lien collé. Credential Management API : concevoir une connexion fiable explique comment une connexion médiée par le navigateur laisse la validation au serveur, et Passkeys et WebAuthn : le parcours de connexion dans le navigateur montre où l’authentificateur prouve la possession. Aucun des deux ne change la règle selon laquelle une adresse partagée est une entrée non fiable à l’arrivée.
Traitez l’annulation comme une fin ordinaire
La promesse se règle quand le panneau se ferme après un transfert et elle est refusée quand la personne annule. Chromium signale l’annulation par AbortError, et le même nom couvre le cas où le navigateur n’a trouvé aucune cible à proposer. Les deux issues sont normales, donc un alert() à ce moment interrompt la tâche sans raison.
| Refus | Signification | Réponse de la page |
|---|---|---|
AbortError | panneau fermé ou aucune cible disponible | conserver le document, rendre le focus, rester silencieux |
NotAllowedError | activation expirée ou politique de partage bloquée | expliquer que le partage est bloqué ici |
TypeError | membres invalides, données vides, adresse inutilisable | montrer la solution de repli, corriger le constructeur |
DataError | un fichier n’a pu être lu ni partagé | nommer le fichier, proposer le téléchargement |
Ne réessayez jamais automatiquement. L’activation qui rendait le premier appel valide est consommée : une boucle de nouvelles tentatives produit une suite de refus NotAllowedError et, dans certains navigateurs, aucune réaction visible. Attendez le clic suivant, qui est aussi le moment où la personne confirme de nouveau son intention.
Restaurez l’interface sans déplacer personne. Le focus revient à l’élément qui a ouvert le panneau, la position de défilement reste où elle était et un contenu d’éditeur non enregistré survit intact. Annoncez le résultat via role="status" avec aria-live="polite", afin qu’un lecteur d’écran entende « Rien n’a été partagé » une seule fois au lieu d’interrompre la phrase en cours. Les pages qui énoncent aussi leurs messages peuvent suivre Voix de synthèse vocale et lecture accessible dans le navigateur, qui traite le choix de voix et le comportement d’interruption.
Un état en attente doit rester court et réversible. Poser button.disabled = true retire le contrôle de l’ordre de tabulation et peut avaler le clic qui a lancé l’appel : préférez donc aria-busy sur un bouton qui reste focalisable. Une cible locale règle généralement la promesse en moins d’une seconde, mais une destination distante peut garder le panneau ouvert, et la page doit rester utilisable tant que la promesse est en attente.
Enregistrez l’issue, jamais le contenu. Des compteurs nommés share-completed, share-cancelled et share-unavailable décrivent le parcours sans transporter un titre, une adresse ou un nom de fichier dans un journal. Gardez cet enregistrement de courte durée et n’utilisez pas la disponibilité du partage comme indice sur le compte, l’appareil ou le réseau.
Gardez la copie et le téléchargement au premier plan
La solution de repli porte la même intention par une surface que la page contrôle, et elle doit être affichée à côté du contrôle de partage, pas derrière un refus. Trois représentations couvrent la plupart des produits.
| Solution | Primitive | Disponible quand |
|---|---|---|
| copier le lien | navigator.clipboard.writeText(url) | contexte sécurisé et geste récent |
| téléchargement | <a download="statement.txt" href="blob:..."> | l’exportation est prête |
| lien simple | un <a href> ordinaire dans le document | toujours |
Les écritures dans le presse-papiers échouent plus souvent qu’on ne l’imagine. navigator.clipboard n’existe pas hors d’un contexte sécurisé, writeText() refuse avec NotAllowedError quand le geste a expiré, et certains navigateurs affichent une autorisation qui peut être déclinée. Un contrôle de copie a donc besoin de deux états visibles, copié et non copié, plus un champ en lecture seule sélectionnable comme dernier recours. Un input visible avec l’adresse sélectionnée est honnête ; un échec silencieux qui annonce un succès ne l’est pas. Le guide Clipboard API et intention utilisateur transforme ce repli de copie en une décision distincte de lecture et de minimisation des données.
Un téléchargement exige un nom de fichier et un format que l’application réceptrice sait ouvrir. Créez le blob, posez URL.createObjectURL(blob) sur le lien et révoquez-le à la fin du téléchargement ou au déchargement de la page. Si la génération est lente, affichez la progression et gardez le contenu d’origine lisible, car un bouton désactivé sans explication est pire qu’une attente annoncée de quelques secondes.
Gardez les trois actions dans un même groupe avec des libellés distincts : copier, télécharger et partager. Le regroupement visuel est utile, mais les autorisations et les issues ne sont pas interchangeables. Copier garde le contenu sur l’appareil courant, partager fait sortir la page de son périmètre, et une invitation créerait une relation de compte qui demande sa propre confirmation et sa propre autorisation.
Deux limites voisines comptent ici. Les limites des permissions du navigateur explique pourquoi les vérifications de capacité doivent vivre près du code qui consomme le résultat, et les workflows respectueux de la confidentialité traite l’état qu’une page doit conserver après une tâche. Une solution de repli qui réutilise la même adresse assainie hérite des deux décisions, raison pour laquelle le constructeur d’adresse doit tenir dans une seule fonction.
Rendez la solution de repli résistante aux interruptions
L’état du réseau ne prouve pas qu’un transfert a abouti. Le navigateur peut remettre des données à une application locale sans une seule requête de la page, et une destination distante peut ensuite avoir besoin de sa propre connexion. La page sait seulement qu’elle a demandé, ce qui rend honnêtes les libellés « panneau ouvert » ou « partage annulé » et fait de « livré » une affirmation que le code ne peut pas soutenir.
Une interruption change ce que la personne attend. Un onglet passé en arrière-plan pendant une promesse en attente peut revenir avec le panneau déjà fermé : relisez donc l’état du contrôle sur visibilitychange au lieu de supposer que le bloc finally s’est exécuté alors que le document était visible. Gardez le drapeau d’attente dans un endroit compatible avec un <form>, et laissez un refus tardif ne mettre à jour qu’un message encore affiché.
Une connexion absente ou intermittente ne change pas le modèle d’interaction. Un article local peut encore proposer une adresse copiable hors réseau, et une exportation peut attendre que le fichier soit généré. Indiquez si la représentation est prête, gardez le contenu courant lisible et évitez un contrôle désactivé sans motif.
Le partage cohabite souvent avec l’impression, l’enregistrement et l’invitation. Donnez à chaque action un libellé distinct et énoncez les différences réelles. L’impression garde le contenu dans l’onglet courant, l’enregistrement conserve une copie locale, le partage remet des données à une autre application, et l’invitation peut créer une relation de compte qui demande une confirmation. Les regrouper visuellement est raisonnable ; fusionner leurs autorisations ne l’est pas.
La langue change ce qui tient à l’écran. Un titre traduit long fait passer le libellé du bouton à la ligne, un texte de droite à gauche réordonne une icône placée avec une marge fixe, et une écriture non latine modifie la largeur mesurée de la même chaîne. Testez avec la langue la plus longue que vous publiez, gardez l’attribut lang du document exact et traduisez les messages d’état avec les libellés, afin qu’une annulation n’apparaisse jamais dans une seconde langue sur le même écran.
Vérifiez les contextes, la prise en charge et les résultats
Exécutez la même petite matrice de résultats dans chaque famille de navigateurs prise en charge, et conservez les lignes comme contrat produit plutôt que comme description du panneau d’un fournisseur.
| Cas | Préparation | Résultat attendu |
|---|---|---|
| parcours nominal | page sécurisée, clic réel | le panneau s’ouvre et la promesse se règle |
| annulation | panneau fermé | AbortError, document intact |
| API absente | navigator.share supprimé | solution de repli visible dès le premier rendu |
| politique bloquée | <iframe> sans allow="web-share" | NotAllowedError, la solution reste |
| données invalides | canonicalUrl() renvoie un chemin relatif | TypeError, la solution reste |
Un document intégré a besoin de allow="web-share" sur l’<iframe> et, lorsque l’hôte envoie l’en-tête, de Permissions-Policy: web-share=(self). Sans l’un des deux, l’appel est refusé avec NotAllowedError même après un clic réel, et le composant doit garder son propre chemin de copie. Cela vaut aussi pour une page ouverte dans une vue web qui ne relaie pas la directive.
Les tests automatisés peuvent remplacer la méthode de trois façons : une fonction qui se règle, une fonction qui refuse avec new DOMException('cancelled', 'AbortError') et aucune méthode. Vérifiez l’état visible plutôt que le nombre d’appels, afin de couvrir une solution atteignable, un brouillon qui survit et un message d’état qui apparaît une seule fois. Construire un DOMException conserve la propriété name utilisée par le gestionnaire, ce qu’un Error simple ne fait pas.
Mesurez le chemin que vous contrôlez. Posez une entrée performance.mark('share-complete') lorsque la solution de repli aboutit et lisez-la avec PerformanceObserver pendant une session d’assistance au lieu de la déduire de retours d’utilisateurs. PerformanceObserver pour la santé d’une application web montre comment garder cette mesure locale et de courte durée.
Sources
Conclusion pratique
Traitez le partage comme une branche facultative d’une tâche qui doit aboutir sans lui. Conditionnez navigator.share() à un événement de confiance, publiez une adresse absolue assainie et traduisez AbortError, NotAllowedError, TypeError et DataError en quatre réponses distinctes et discrètes.
Gardez navigator.clipboard.writeText(), un lien download et l’adresse simple visibles dès le premier rendu, afin qu’une cible absente, une politique bloquée ou un panneau annulé ne coûtent rien à la personne qui lit. BotBrowser prend en charge les parcours navigateur avec profil mobile pour examiner l’interface adaptative de partage d’une application, mais ne simule ni le panneau de partage du système ni ses cibles et ne garantit pas l’activation de l’utilisateur.
Cet article fait partie du guide : Surfaces de la plateforme web : carte de revue
Articles Connexes
Web Share API : limites des permissions et replis sûrs
PlateformeEntrée et confidentialité d’une PWA Web Share Target
PlateformeBadging API : limites des notifications PWA
PlateformeEyeDropper API : activation et confidentialité des couleurs
PlateformePayment Request API : consentement et solutions de repli
PlateformeIdle Detection API : contrôle, permissions et confidentialité
Exécutez la même vérification dans BotBrowser
Chargez un profil, gardez dans le navigateur les signaux que vous venez de lire, puis confirmez le résultat sur votre propre machine avant le déploiement.