copyTextToClipboard

Paquete: @tiendana/utils

Copia texto al portapapeles del navegador usando la Clipboard API moderna, con notificación automática de éxito mediante snackbar.

Características

✅ Usa Clipboard API moderna (navigator.clipboard)
✅ Notificación automática de éxito
✅ Maneja valores null/undefined
✅ Operación asíncrona (Promise)
✅ Requiere contexto seguro (HTTPS)
✅ Integración con sistema de snackbars

Firma

function copyTextToClipboard(text?: string | null): Promise<void>

Parámetros

Parámetro	Tipo	Descripción	Requerido
text	string | null | undefined	Texto a copiar al portapapeles	❌

Retorno

Tipo: Promise<void>

Promise que se resuelve cuando el texto se ha copiado exitosamente. Automáticamente muestra snackbar de confirmación.

Ejemplos de Uso

Copiar Texto Simple

import { copyTextToClipboard } from '@tiendana/utils';

await copyTextToClipboard('Hola Mundo');
// Muestra snackbar: "Copiado al portapapeles"

Copiar al Hacer Click

function handleCopyClick() {
  const textToCopy = document.getElementById('text-content')?.textContent;
  copyTextToClipboard(textToCopy);
}

// En el template
<button onClick={handleCopyClick}>Copiar</button>

Copiar Código

function CopyCodeButton({ code }: { code: string }) {
  const handleCopy = async () => {
    await copyTextToClipboard(code);
  };
  
  return (
    <button onClick={handleCopy}>
      📋 Copiar código
    </button>
  );
}

Copiar URL

function ShareButton() {
  const copyUrl = () => {
    const currentUrl = window.location.href;
    copyTextToClipboard(currentUrl);
  };
  
  return <button onClick={copyUrl}>Compartir URL</button>;
}

Copiar Desde Input

function CopyInputValue() {
  const inputRef = useRef<HTMLInputElement>(null);
  
  const handleCopy = () => {
    if (inputRef.current) {
      copyTextToClipboard(inputRef.current.value);
    }
  };
  
  return (
    <div>
      <input ref={inputRef} type="text" />
      <button onClick={handleCopy}>Copiar</button>
    </div>
  );
}

Copiar JSON Formateado

function CopyJsonButton({ data }: { data: any }) {
  const handleCopy = () => {
    const formatted = JSON.stringify(data, null, 2);
    copyTextToClipboard(formatted);
  };
  
  return <button onClick={handleCopy}>Copiar JSON</button>;
}

Copiar Datos de Tabla

interface User {
  name: string;
  email: string;
  phone: string;
}

function CopyUserData({ user }: { user: User }) {
  const copyData = () => {
    const text = `
Nombre: ${user.name}
Email: ${user.email}
Teléfono: ${user.phone}
    `.trim();
    
    copyTextToClipboard(text);
  };
  
  return <button onClick={copyData}>📋 Copiar</button>;
}

Copiar con Confirmación Manual

async function copyWithCustomFeedback(text: string) {
  try {
    // Nota: Esta función ya muestra snackbar automáticamente
    await copyTextToClipboard(text);
    
    // Si necesitas lógica adicional después de copiar:
    console.log('Texto copiado exitosamente');
  } catch (error) {
    console.error('Error al copiar:', error);
  }
}

Copiar Enlace de Descarga

function DownloadLinkButton({ fileUrl }: { fileUrl: string }) {
  const copyDownloadLink = () => {
    const fullUrl = `${window.location.origin}${fileUrl}`;
    copyTextToClipboard(fullUrl);
  };
  
  return (
    <button onClick={copyDownloadLink}>
      🔗 Copiar enlace de descarga
    </button>
  );
}

Copiar Token de Autenticación

function CopyAuthTokenButton({ token }: { token: string }) {
  const handleCopyToken = () => {
    copyTextToClipboard(token);
  };
  
  return (
    <div className="auth-token">
      <code>{token.substring(0, 20)}...</code>
      <button onClick={handleCopyToken}>📋</button>
    </div>
  );
}

Casos de Uso Comunes

• Copiar código: Snippets de código en documentación
• Compartir URLs: Enlaces de páginas o recursos
• Copiar tokens: API keys, tokens de autenticación
• Copiar datos: Información de usuarios, productos, etc.
• Copiar texto: Contenido de artículos, comentarios
• Copiar JSON: Datos estructurados para debugging
• Copiar comandos: Comandos CLI en tutoriales
• Copiar credenciales: Passwords generados, códigos de acceso

Comportamiento

Valores Vacíos

Si el parámetro text es null, undefined o '', la función no hace nada (no copia ni muestra snackbar).

await copyTextToClipboard(null);      // No hace nada
await copyTextToClipboard(undefined); // No hace nada
await copyTextToClipboard('');        // No hace nada (la condición es `navigator.clipboard && text`)

Notificación Automática

La función usa internamente openSnackbar para mostrar el mensaje "Copiado al portapapeles" automáticamente.

// No necesitas manejar la notificación manualmente
await copyTextToClipboard('Texto');
// ✅ Automáticamente muestra snackbar

Operación Asíncrona

La función retorna una Promise, por lo que puedes usar await o .then():

// Con await
await copyTextToClipboard('Texto');
console.log('Copiado');

// Con .then()
copyTextToClipboard('Texto').then(() => {
  console.log('Copiado');
});

Notas Técnicas

• Clipboard API: Usa navigator.clipboard.writeText() (API moderna)
• Contexto seguro: Requiere HTTPS o localhost para funcionar
• Browser support: Navegadores modernos (Chrome 63+, Firefox 53+, Safari 13.1+)
• Permisos: Puede requerir permisos del usuario en algunos navegadores
• Dependencia: Usa openSnackbar de @tiendana/utils para notificaciones
• Error handling: Si clipboard API no está disponible o text es null, no hace nada

Limitaciones

Requiere HTTPS

La Clipboard API solo funciona en contextos seguros (HTTPS) o localhost:

// ✅ Funciona
https://example.com
http://localhost:3000

// ❌ No funciona
http://example.com (sin SSL)

Si necesitas soporte para HTTP, considera usar el método legacy con document.execCommand('copy').

Sin Snackbar Personalizable

La función muestra automáticamente el mensaje "Copiado al portapapeles" usando openSnackbar. No se puede personalizar el mensaje sin modificar la función.

Si necesitas mensajes personalizados:

// Opción 1: Usar navigator.clipboard directamente
await navigator.clipboard.writeText(text);
openSnackbar({ msj: 'Mensaje personalizado' });

// Opción 2: Extender la función
async function copyWithCustomMessage(text: string, message: string) {
  if (navigator.clipboard && text) {
    await navigator.clipboard.writeText(text);
    openSnackbar({ msj: message });
  }
}

Permisos de Navegador

Algunos navegadores pueden solicitar permisos al usuario la primera vez que se use la Clipboard API. El usuario debe aceptar para que funcione.

Browser Support

Navegador	Versión Mínima
Chrome	63+
Firefox	53+
Safari	13.1+
Edge	79+
Opera	50+

Para navegadores antiguos, considera usar un polyfill o el método legacy document.execCommand('copy').

Ver También

• downloadFile - Descargar archivos
• Cookies - Trabajar con cookies del navegador