navigator.canShare() y la Web Share API: límites del uso compartido
Cómo navigator.canShare() y navigator.share() deciden si se acepta un uso compartido, dónde difieren los permisos y los límites de archivos, y cómo probar ambos.
BotBrowser Team
Quieres la documentación estructurada de Plataforma?
Este artículo forma parte de la biblioteca editorial. Para pasos de configuración, material de referencia y actualizaciones continuas, entra en la sección de docs.
Compartir en la web es una entrega a una superficie que la página no controla. navigator.share() pide al navegador que entregue un título, una URL, un texto o un conjunto de archivos al destino que elija la persona, y la página solo sabe que la promesa se resolvió. BotBrowser puede cargar un perfil móvil en un contexto controlado para revisar cómo se presenta el control de compartir y su alternativa en distintos tamaños de ventana y idiomas; no puede dibujar la hoja de compartir del sistema operativo, no elige destino y no concede la activación temporal que exige la llamada. Cuando el destino es una PWA instalada, Entrada y privacidad de una PWA Web Share Target explica cómo validar la ruta receptora sin convertir la entrega en permiso para conservar contenido.
Resumen
- Llama a
navigator.share()desde un clic o una pulsación de tecla de confianza; un retraso consetTimeout()o una llamada al cargar deja caducar la activación temporal. - Construye el objeto compartido con lo que la persona ya ve y elimina antes el fragmento, los parámetros de sesión, los tokens y los identificadores de registro.
- Traduce
AbortError,NotAllowedError,TypeErroryDataErroren cuatro mensajes distintos y no sustituyas el documento en ninguno de los cuatro casos. - Mantén
navigator.clipboard.writeText(), un enlacedownloady la URL simple visibles desde el primer intento, no después de un rechazo. - BotBrowser revisa el flujo adaptable alrededor del control con un perfil seleccionado; la hoja, la lista de destinos y la decisión de activación siguen siendo del navegador y del sistema operativo.
Contenido de esta guía
- Empieza con una acción explícita
- Valida los datos antes de la entrega
- Trata la cancelación como un final normal
- Mantén la copia y la descarga al mismo nivel
- Haz que la alternativa resista interrupciones
- Revisa contextos, compatibilidad y resultados
La especificación W3C Web Share define el modelo y los requisitos de seguridad que hereda de la plataforma. La guía de MDN, navigator.share() y navigator.canShare() describen los métodos del navegador y sus notas de compatibilidad. Los tres documentos describen una capacidad condicional; ninguno promete un destino, una disposición de la hoja ni un resultado igual en todas las plataformas.
Empieza con una acción explícita
navigator.share() solo se ejecuta dentro de una activación temporal de la persona. La llamada debe ocurrir mientras el navegador todavía respeta la activación concedida a un evento de confianza, así que un setTimeout() con un retraso corto, un escucha de scroll o una llamada automática tras DOMContentLoaded acaban en un rechazo NotAllowedError. Asocia la llamada a los manejadores click y keydown de un único control y deja que ese control gobierne todo el intento.
La detección de capacidad debe ser explícita. typeof navigator.share === 'function' es la comprobación que vale. Leer navigator.canShare sin llamarlo no demuestra nada, porque el método existe en navegadores que aceptan solo los miembros de texto y URL. Muestra el control cuando el método exista y window.isSecureContext sea verdadero; en caso contrario, muestra un control deshabilitado con una nota breve de que la página debe servirse por 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();
}
}
El manejador no espera nada antes de la llamada, porque una promesa resuelta primero puede consumir la activación que el navegador concedió al clic. canonicalUrl() debería devolver una dirección absoluta creada con new URL(location.href). Una ruta relativa, una cadena vacía o un valor javascript: no pasan la validación y convierten un clic normal en un TypeError.
Da al control un nombre que describa la acción, por ejemplo «Compartir esta página» en lugar de «Compartir». Un disparador solo con icono necesita aria-label y una ayuda visible, y su área debe medir al menos 24 por 24 píxeles CSS para cumplir el tamaño mínimo de objetivo de WCAG 2.2 con la página ampliada al 200 por ciento. Un elemento <button> nativo ya envía Enter y Space al mismo manejador, lo que mantiene el recorrido de teclado idéntico al del puntero sin código extra.
No abras la hoja de antemano, no precargues una lista de destinos y no deduzcas un destinatario a partir del idioma del navegador. La persona elige el destino dentro del navegador o de la superficie del sistema, y la página no ve esa elección.
Valida los datos antes de la entrega
El objeto de compartir acepta title, text, url y un arreglo files. Cada miembro es opcional, al menos uno debe llevar datos, y una llamada con miembros vacíos o mal formados rechaza con TypeError. Construye el objeto con estado que la persona ya ve, no con datos internos de la sesión.
| Miembro | Origen seguro | Quitar antes de la llamada |
|---|---|---|
title | document.title o un encabezado visible | identificadores de registro, etiquetas de cuenta |
text | una selección del documento renderizado | valores de formulario, notas privadas, tokens |
url | canonicalUrl() sin parámetros secretos | el fragmento, parámetros de descarga firmados |
files | una exportación que la persona acaba de generar | borradores, rutas temporales, datos de otra persona |
navigator.canShare() responde una pregunta estrecha: si este navegador aceptará esta forma de datos. No responde si algún destino instalado la aceptará. Un resultado false corresponde a la alternativa antes de abrir la hoja, lo que cuesta menos que un rechazo que la persona debe interpretar. Los archivos requieren una segunda comprobación, porque canShare(data) puede ser verdadero mientras canShare({ files: [file] }) es falso en un navegador que solo comparte texto y enlaces.
Para un archivo, nombra el objeto y declara su tipo: new File([blob], 'statement-2026-10.txt', { type: 'text/plain' }). Un File sin un type legible puede pasar la comprobación y fallar en la aplicación receptora. Mantén la exportación dentro del límite de tamaño que ya aplica tu propia ruta de descarga y llama a URL.revokeObjectURL() cuando la promesa se resuelva, para que un informe grande no siga referenciado tras una cancelación.
Sanea la dirección completa, no solo la ruta. location.href arrastra el fragmento y todos los parámetros de consulta, incluido un token de corta vida añadido por una redirección. Reconstruye la dirección compartida con url.origin, url.pathname y un url.search permitido, de modo que el fragmento y los parámetros de sesión nunca lleguen a navigator.share(). Un uso compartido que filtra un access_token es una fuga de credenciales con un botón amable encima.
La autorización no se mueve. El destinatario abre la dirección en un contexto de navegación nuevo, donde el servidor debe repetir la misma comprobación de sesión, la misma regla de origen y el mismo camino 403 que para un enlace pegado. Credential Management API: diseña un inicio de sesión seguro explica cómo un inicio de sesión mediado por el navegador deja el control en el servidor, y Passkeys y WebAuthn: el recorrido de inicio de sesión en el navegador muestra dónde el autenticador demuestra posesión. Ninguno cambia la regla de que una dirección compartida es entrada no confiable al llegar.
Trata la cancelación como un final normal
La promesa se resuelve cuando la hoja se cierra tras una entrega y se rechaza cuando la persona cancela. Chromium informa la cancelación como AbortError, y el mismo nombre cubre el caso en que el navegador no encontró ningún destino que ofrecer. Ambos resultados son normales, así que un alert() en ese momento interrumpe la tarea sin motivo.
| Rechazo | Significado | Respuesta de la página |
|---|---|---|
AbortError | hoja cerrada o ningún destino disponible | conservar el documento, devolver el foco, no interrumpir |
NotAllowedError | activación caducada o política de share bloqueada | explicar que compartir está bloqueado aquí |
TypeError | miembros inválidos, datos vacíos, dirección inutilizable | mostrar la alternativa, corregir el constructor |
DataError | un archivo no se pudo leer ni compartir | nombrar el archivo, ofrecer la descarga |
No reintentes de forma automática. La activación que hizo válida la primera llamada se ha gastado, así que un bucle de reintentos produce una cadena de rechazos NotAllowedError y, en algunos navegadores, ninguna reacción visible. Espera el siguiente clic, que además es el momento en que la persona vuelve a confirmar la intención.
Restaura la interfaz sin mover a nadie. El foco vuelve al elemento que abrió la hoja, el desplazamiento se queda donde estaba y el contenido sin guardar del editor sigue intacto. Anuncia el resultado mediante role="status" con aria-live="polite", para que un lector de pantalla escuche «No se compartió nada» una vez en lugar de interrumpir la frase que se está leyendo. Las páginas que además hablan sus mensajes pueden seguir Voces de síntesis de voz y reproducción accesible en el navegador, que trata la selección de voz y el comportamiento de interrupción.
El estado pendiente debe ser corto y reversible. Asignar button.disabled = true saca el control del orden de tabulación y puede tragarse el clic que inició la llamada, así que es preferible aria-busy en un botón que siga recibiendo foco. Un destino local suele resolver la promesa en menos de un segundo, pero un destino remoto puede mantener la hoja abierta, y la página tiene que seguir siendo usable mientras la promesa está pendiente.
Registra el resultado, nunca el contenido. Contadores llamados share-completed, share-cancelled y share-unavailable describen el flujo sin llevar un título, una dirección o un nombre de archivo a un registro. Mantén ese registro de vida corta y no uses la disponibilidad de compartir como señal sobre la cuenta, el dispositivo o la red.
Mantén la copia y la descarga al mismo nivel
La alternativa lleva la misma intención por una superficie que la página sí controla, y debe estar en pantalla junto al control de compartir, no detrás de un rechazo. Tres representaciones cubren la mayoría de los productos.
| Alternativa | Primitiva | Disponible cuando |
|---|---|---|
| copiar enlace | navigator.clipboard.writeText(url) | contexto seguro y gesto reciente |
| descarga | <a download="statement.txt" href="blob:..."> | la exportación está lista |
| enlace simple | un <a href> normal en el documento | siempre |
Las escrituras en el portapapeles fallan más de lo que se espera. navigator.clipboard no existe fuera de un contexto seguro, writeText() rechaza con NotAllowedError cuando el gesto ha caducado, y algunos navegadores muestran un permiso que se puede rechazar. Un control de copia necesita por tanto dos estados visibles, copiado y no copiado, más un campo de solo lectura seleccionable como último recurso. Un input visible con la dirección seleccionada es honesto; un fallo silencioso que declara éxito no lo es. La guía Clipboard API e intención del usuario convierte este respaldo de copia en una decisión separada sobre lectura y minimización de datos.
Una descarga necesita un nombre de archivo y un formato que la aplicación receptora pueda abrir. Crea el blob, asigna URL.createObjectURL(blob) al ancla y revócalo cuando termine la descarga o se descargue la página. Si la generación es lenta, muestra progreso y mantén legible el contenido original, porque un botón deshabilitado sin explicación es peor que una espera declarada de unos segundos.
Mantén las tres acciones en un grupo con etiquetas distintas: copiar, descargar y compartir. La agrupación visual está bien, pero los permisos y los resultados no son intercambiables. Copiar deja el contenido en el dispositivo actual, compartir saca la página del camino y una invitación crearía una relación de cuenta que necesita su propia confirmación y autorización.
Dos límites cercanos importan aquí. Los límites de permisos del navegador explica por qué las comprobaciones de capacidad van junto al código que consume el resultado, y los flujos web con privacidad cubre cuánto estado debe retener una página al terminar una tarea. Una alternativa que reutiliza la misma dirección saneada hereda ambas decisiones, y por eso el constructor de direcciones debe vivir en una sola función.
Haz que la alternativa resista interrupciones
El estado de la red no demuestra que la entrega se completara. El navegador puede pasar datos a una aplicación local sin una sola petición de la página, y un destino remoto puede necesitar después su propia conexión. La página solo sabe que pidió la entrega, así que «se abrió la hoja» o «se canceló el uso compartido» son etiquetas honestas y «entregado» es una afirmación que el código no puede sostener.
Una interrupción cambia lo que la persona espera. Una pestaña que pasa a segundo plano con una promesa pendiente puede reanudarse con la hoja ya cerrada, así que vuelve a leer el estado del control en visibilitychange en lugar de suponer que el bloque finally se ejecutó con el documento visible. Guarda la marca pendiente en un lugar compatible con <form> y deja que un rechazo tardío actualice solo un mensaje que siga en pantalla.
Las conexiones sin red o intermitentes no cambian el modelo de interacción. Un artículo local puede seguir ofreciendo una dirección copiable mientras la red está caída, y una exportación puede esperar a que el archivo termine de generarse. Indica si la representación está lista, mantén legible el contenido actual y evita un control deshabilitado sin motivo.
Compartir suele convivir con imprimir, guardar e invitar. Da a cada acción una etiqueta distinta y declara las diferencias materiales. Imprimir deja el contenido en la pestaña actual, guardar conserva una copia local, compartir entrega datos a otra aplicación e invitar puede crear una relación de cuenta que necesita confirmación. Agruparlas visualmente es razonable; fusionar sus permisos no lo es.
El idioma cambia lo que cabe. Un título traducido largo envuelve la etiqueta del botón, el texto de derecha a izquierda reordena un icono colocado con margen fijo y una escritura no latina cambia el ancho medido de la misma cadena. Prueba con el idioma más largo que publiques, mantén el atributo lang del documento correcto y traduce los mensajes de estado junto con las etiquetas para que una cancelación no aparezca en un segundo idioma en la misma pantalla.
Revisa contextos, compatibilidad y resultados
Ejecuta la misma matriz pequeña de resultados en cada familia de navegador que admitas y conserva las filas como contrato de producto en lugar de como descripción de la hoja de un proveedor.
| Caso | Preparación | Resultado esperado |
|---|---|---|
| camino correcto | página segura, clic real | la hoja se abre y la promesa se resuelve |
| cancelación | hoja cerrada | AbortError, documento intacto |
| API ausente | navigator.share eliminado | alternativa visible desde el primer pintado |
| política bloqueada | <iframe> sin allow="web-share" | NotAllowedError, la alternativa permanece |
| datos inválidos | canonicalUrl() devuelve una ruta relativa | TypeError, la alternativa permanece |
Un documento incrustado necesita allow="web-share" en el <iframe> y, donde el host envíe la cabecera, Permissions-Policy: web-share=(self). Sin uno de los dos, la llamada rechaza con NotAllowedError incluso después de un clic real, y el componente tiene que conservar su propia ruta de copia. Lo mismo vale para una página abierta dentro de una vista web que no reenvía la directiva.
Las pruebas automatizadas pueden sustituir el método de tres formas: una función que resuelve, otra que rechaza con new DOMException('cancelled', 'AbortError') y ninguna función. Verifica el estado visible en lugar del número de llamadas, de modo que la prueba cubra una alternativa alcanzable, un borrador que sobrevive y un mensaje de estado que aparece una sola vez. Construir un DOMException conserva la propiedad name que ramifica el manejador, cosa que un Error simple no hace.
Mide el camino que controlas. Marca una entrada performance.mark('share-complete') cuando termine la alternativa y léela con PerformanceObserver durante una sesión de soporte en lugar de deducirla de comentarios de usuarios. PerformanceObserver para la salud de una aplicación web muestra cómo mantener esa medición local y de vida corta.
Fuentes
Conclusión práctica
Trata compartir como una rama opcional de una tarea que debe terminar sin ella. Condiciona navigator.share() a un evento de confianza, publica una dirección absoluta saneada y traduce AbortError, NotAllowedError, TypeError y DataError en cuatro respuestas distintas y discretas.
Mantén navigator.clipboard.writeText(), un enlace download y la dirección simple visibles desde el primer pintado, para que un destino ausente, una política bloqueada o una hoja cancelada no le cuesten nada a quien lee. BotBrowser permite probar flujos de navegador con perfiles móviles y revisar el diseño adaptable de compartir de una aplicación, pero no simula la hoja de compartir del sistema operativo ni sus destinos y no garantiza la activación de la persona.
Este artículo forma parte de la guía: Superficies de la plataforma web: mapa de revisión
Artículos Relacionados
Web Share API: límites de permisos y respaldos seguros
PlataformaEntrada y privacidad de una PWA Web Share Target
PlataformaBadging API: límites de notificaciones PWA
PlataformaEyeDropper API: activación y privacidad del color
PlataformaPayment Request API: consentimiento y alternativas seguras
PlataformaIdle Detection API: control, permisos y privacidad
Ejecuta la misma comprobación en BotBrowser
Carga un perfil, mantén dentro del navegador las señales que acabas de leer y confirma el resultado en tu propia máquina antes del despliegue.