Clipboard API: Leer y Escribir en el Portapapeles
Aprende a usar la API Clipboard moderna para leer y escribir texto, imágenes y datos en el portapapeles del sistema desde JavaScript.
TL;DR - Resumen rápido
- Clipboard API permite leer y escribir en el portapapeles del sistema
- writeText() escribe texto en el portapapeles
- write() escribe imágenes y otros tipos de datos
- readText() lee texto del portapapeles
- Los eventos clipboard detectan cambios en el portapapeles
Introducción a Clipboard API
La API Clipboard permite a las aplicaciones web leer y escribir en el portapapeles del sistema. Es especialmente útil para funcionalidades como copiar datos al portapapeles, pegar contenido desde el portapapeles, y detectar cuando el usuario copia o pega algo.
La API moderna Clipboard reemplaza los métodos antiguos como document.execCommand('copy'), que ahora están obsoletos. La nueva API es asíncrona, más segura y permite trabajar con diferentes tipos de datos, no solo texto.
- Copiar texto o datos al portapapeles con un clic
- Leer el contenido del portapapeles al cargar la página
- Detectar cuando el usuario copia o pega contenido
- Copiar imágenes al portapapeles para pegar en otras aplicaciones
- Implementar botones de copiar con feedback visual
Requisitos de seguridad
La API Clipboard solo funciona en contextos seguros: HTTPS, localhost, o archivos locales. Además, requiere que el usuario haya interactuado con la página (clic, tecla) antes de poder escribir en el portapapeles.
¿Qué es Clipboard API?
La API Clipboard proporciona acceso al portapapeles del sistema a través del objeto navigator.clipboard. Este objeto tiene métodos para leer y escribir datos, y la API también incluye eventos para detectar cambios en el portapapeles. La API es asíncrona, lo que permite trabajar con datos grandes sin bloquear el hilo principal.
Este ejemplo muestra cómo verificar si la API está disponible y cómo usarla básicamente. Es importante verificar la disponibilidad porque algunos navegadores antiguos no soportan la API moderna. Si no está disponible, puedes usar métodos alternativos como document.execCommand().
Escribir en el Portapapeles
Para escribir en el portapapeles, usas los métodos writeText() y write() del objeto navigator.clipboard. writeText() es para texto simple, mientras que write() permite escribir diferentes tipos de datos incluyendo imágenes, HTML y blobs.
writeText: Escribir Texto
writeText() es el método más simple para escribir en el portapapeles. Acepta una string y devuelve una promesa que se resuelve cuando el texto se ha copiado exitosamente. Es ideal para botones de copiar, enlaces de compartir, y cualquier funcionalidad que necesite copiar texto.
Este ejemplo muestra cómo implementar un botón de copiar con feedback visual. El método writeText() devuelve una promesa, por lo que puedes usar async/await para manejar el resultado. Es importante capturar errores porque el usuario puede denegar el permiso o el navegador puede no soportar la API.
write: Imágenes y Blobs
write() es el método más versátil de la API Clipboard. Acepta un array de ClipboardItem, donde cada item puede ser de un tipo diferente: texto, HTML, imágenes, o cualquier blob. Esto permite copiar contenido rico al portapapeles.
Este ejemplo muestra cómo copiar una imagen al portapapeles. El ClipboardItem se crea con un blob y el tipo MIME correspondiente. Cuando el usuario pega la imagen en otra aplicación, recibirá la imagen completa, no una referencia.
Tipos MIME comunes para imágenes
image/png - Imagen PNGimage/jpeg - Imagen JPEGimage/gif - Imagen GIFimage/webp - Imagen WebPimage/svg+xml - Gráfico SVG
Leer del Portapapeles
Para leer del portapapeles, usas los métodos readText() y read(). readText() lee texto plano, mientras que read() permite leer diferentes tipos de datos. Ambos métodos devuelven promesas y requieren permiso del usuario.
readText: Leer Texto
readText() lee el contenido de texto del portapapeles y devuelve una promesa que se resuelve con el texto. Si el portapapeles contiene una imagen u otro tipo de dato, la promesa se rechaza. Es ideal para detectar si hay texto disponible al pegar.
Este ejemplo muestra cómo leer texto del portapapeles y manejar el caso cuando no hay texto disponible. El método readText() requiere permiso del usuario, por lo que el navegador mostrará un diálogo solicitando acceso al portapapeles.
read: Leer Imágenes
read() permite leer diferentes tipos de datos del portapapeles. Especificas el tipo MIME que esperas y el método devuelve un blob con los datos. Esto es útil para leer imágenes que el usuario ha copiado de otra aplicación.
Este ejemplo muestra cómo leer una imagen del portapapeles. El método read() acepta un array de tipos MIME y devuelve el primer tipo disponible. Si el portapapeles contiene texto, la promesa se rechaza porque no coincide con el tipo solicitado.
Clipboard Items
ClipboardItem es un objeto que representa un elemento en el portapapeles. Cada item puede contener múltiples representaciones del mismo dato: texto plano, HTML, imagen, etc. Esto permite que las aplicaciones elijan el formato más apropiado cuando pegan contenido.
Este ejemplo muestra cómo crear un ClipboardItem con múltiples representaciones. Cuando el usuario pega este contenido en una aplicación que soporta HTML, recibirá el HTML. Si la aplicación solo soporta texto plano, recibirá el texto.
Múltiples formatos
Puedes crear un ClipboardItem con múltiples tipos de datos. Por ejemplo, un enlace puede tener representación de texto plano ("https://ejemplo.com") y HTML ("Enlace").
Eventos del Portapapeles
Los eventos clipboard (copy, cut, paste) se disparan cuando el usuario interactúa con el portapapeles. Estos eventos son útiles para detectar cambios, modificar el contenido antes de copiar, o prevenir ciertas operaciones de pegado.
- <strong>copy</strong> - Se dispara cuando el usuario copia contenido
- <strong>cut</strong> - Se dispara cuando el usuario corta contenido
- <strong>paste</strong> - Se dispara cuando el usuario pega contenido
- Usa <code>event.clipboardData</code> para acceder al contenido
- Llama a <code>preventDefault()</code> para personalizar el comportamiento
Este ejemplo muestra cómo escuchar eventos de clipboard. El evento paste proporciona acceso al contenido a través de clipboardData, que es una API diferente de navigator.clipboard. Puedes usar preventDefault() para prevenir el pegado predeterminado y procesar el contenido de forma personalizada.
Permisos del usuario
Para leer del portapapeles con navigator.clipboard.read(), el usuario debe conceder permiso explícitamente. El navegador mostrará un diálogo preguntando si permite que la página acceda al portapapeles.
Errores Comunes
Al trabajar con Clipboard API, hay varios errores comunes que puedes encontrar. Conocerlos de antemano te ayudará a evitar problemas y a crear implementaciones más robustas.
El primer error ocurre cuando intentas escribir en el portapapeles sin interacción del usuario. El segundo muestra el problema de no verificar si la API está disponible. El tercero demuestra cómo manejar errores de permiso cuando el usuario deniega el acceso.
Requiere interacción del usuario
La API Clipboard requiere que el usuario haya interactuado con la página (clic, tecla) antes de poder escribir en el portapapeles. No puedes escribir automáticamente al cargar la página sin interacción previa del usuario.
Resumen: Clipboard API
Conceptos principales:
- •Clipboard API permite leer y escribir en el portapapeles del sistema
- •writeText() escribe texto, write() escribe cualquier tipo de dato
- •readText() lee texto, read() lee diferentes tipos MIME
- •ClipboardItem representa un elemento en el portapapeles
- •Los eventos copy/cut/paste detectan interacciones con el portapapeles
Mejores prácticas:
- •Verifica si la API está disponible antes de usarla
- •Usa async/await para manejar las promesas de la API
- •Proporciona feedback visual al copiar al portapapeles
- •Maneja errores de permiso y compatibilidad
- •Usa múltiples formatos en ClipboardItem para máxima compatibilidad