come personalizzare l aspetto UI del toast message in GridJs

Guida personalizzazione Toast per GridJs

Panoramica

GridJs offre un sistema di notifiche toast personalizzabile e flessibile che consente di sostituire i messaggi toast predefiniti con le proprie notifiche. Questa guida illustra diversi approcci per personalizzare le notifiche toast in base alle esigenze della tua applicazione.

Indice dei Contenuti

Basic Usage

Simple Alert Example

The most basic custom toast can be implemented using the native alert() function:

const xs = x_spreadsheet('#spreadsheet');

// Define custom toast function
function myToast(title, content, callback) {
  alert(`${title}: ${content}`);
  if (callback) callback();
}

// Set custom toast
xs.customToast(myToast);

Parametri:

  • title (stringa): Il titolo della notifica toast
  • content (stringa): Il contenuto del messaggio toast
  • callback (funzione, opzionale): Funzione di callback da eseguire dopo che il toast viene chiuso

Integration Examples

1. Beautiful Custom Toast

Create a visually appealing toast notification without external dependencies:

function beautifulToast(title, content, callback) {
  // Create dimmer overlay
  const dimmer = document.createElement('div');
  Object.assign(dimmer.style, {
    position: 'fixed',
    top: 0, left: 0, right: 0, bottom: 0,
    background: 'rgba(0,0,0,0.5)',
    zIndex: 9999
  });

  // Create toast element
  const toast = document.createElement('div');
  Object.assign(toast.style, {
    position: 'fixed',
    top: '50%', left: '50%',
    transform: 'translate(-50%, -50%)',
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    color: 'white',
    padding: '20px 30px',
    borderRadius: '10px',
    boxShadow: '0 10px 40px rgba(0,0,0,0.3)',
    zIndex: 10000,
    minWidth: '300px'
  });

  toast.innerHTML = `
    <div style="display: flex; justify-content: space-between; margin-bottom: 10px; font-weight: bold;">
      <span>${title}</span>
      <span class="close" style="cursor: pointer;">×</span>
    </div>
    <div>${content}</div>
  `;

  const remove = () => {
    document.body.removeChild(toast);
    document.body.removeChild(dimmer);
    if (callback) callback();
  };

  toast.querySelector('.close').onclick = remove;
  dimmer.onclick = remove;

  document.body.appendChild(dimmer);
  document.body.appendChild(toast);

  // Auto-dismiss after 3 seconds
  setTimeout(remove, 3000);
}

xs.customToast(beautifulToast);

Caratteristiche:

  • Sfondo a gradiente
  • Overlay modale
  • Clicca per chiudere
  • Auto-chiusura dopo 3 secondi
  • pulsante di chiusura

2. Toastr Library Integration

Integrate the popular Toastr library for toast notifications.

Prerequisites:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/toastr.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/toastr.js/latest/toastr.min.js"></script>

Implementazione:

xs.customToast((title, content, callback) => {
  toastr.options = {
    closeButton: true,
    progressBar: true,
    positionClass: 'toast-top-right',
    timeOut: 3000
  };
  toastr.info(content, title);
  if (callback) callback();
});

Opzioni di personalizzazione:

  • closeButton: Mostra un pulsante di chiusura
  • progressBar: Mostra una barra di progresso del conto alla rovescia
  • positionClass: Controlla la posizione del toast (alto-destra, basso-sinistra, ecc.)
  • timeOut: Durata di auto-scarico in millisecondi

3. SweetAlert2 Integration

Use SweetAlert2 for beautiful, customizable alert dialogs.

Prerequisites:

<script src="https://cdn.jsdelivr.net/npm/sweetalert2@11"></script>

Implementazione:

xs.customToast((title, content, callback) => {
  Swal.fire({
    title: title,
    html: content,
    icon: 'info',
    confirmButtonText: 'OK'
  }).then(() => {
    if (callback) callback();
  });
});

Icone disponibili:

  • success
  • error
  • warning
  • info
  • question

4. Vue + Element UI

Integration with Vue.js and Element UI’s notification component.

new Vue({
  el: '#app',
  mounted() {
    const xs = x_spreadsheet('#spreadsheet');

    xs.customToast((title, content, callback) => {
      this.$notify({
        title: title,
        message: content,
        type: 'info',
        duration: 3000,
        onClose: callback
      });
    });
  }
});

Tipi di Notifica:

  • success
  • warning
  • info
  • error

5. React + Ant Design

Integration with React and Ant Design’s message component.

import { message } from 'antd';

const App = () => {
  useEffect(() => {
    const xs = x_spreadsheet('#spreadsheet');

    xs.customToast((title, content, callback) => {
      message.info({
        content: `${title}: ${content}`,
        duration: 3,
        onClose: callback
      });
    });
  }, []);

  return <div id="spreadsheet"></div>;
};

Componenti Alternativi di Ant Design:

  • message.success()
  • message.error()
  • message.warning()
  • notification.open() (per notifiche più complesse)

Advanced Use Cases

6. Logging and Analytics

Combine custom toast with logging and analytics tracking:

xs.customToast((title, content, callback) => {
  // Log to console
  console.log(`[Toast] ${title}:`, content);

  // Track in analytics system
  if (window.analytics) {
    analytics.track('toast_shown', {
      title: title,
      content: content,
      timestamp: new Date().toISOString()
    });
  }

  // Display custom notification
  showMyCustomToast(title, content, callback);
});

Casi d’uso:

  • Log di debug
  • Tracciamento del comportamento dell’utente
  • Monitoraggio degli errori
  • Metriche di prestazione

7. Mobile-Friendly Toast

Create a mobile-optimized toast notification:

function mobileToast(title, content, callback) {
  const toast = document.createElement('div');
  Object.assign(toast.style, {
    position: 'fixed',
    bottom: '20px',
    left: '50%',
    transform: 'translateX(-50%)',
    background: '#323232',
    color: 'white',
    padding: '12px 24px',
    borderRadius: '24px',
    fontSize: '14px',
    zIndex: 10000,
    maxWidth: '80%',
    textAlign: 'center',
    boxShadow: '0 4px 12px rgba(0,0,0,0.3)'
  });

  toast.textContent = `${title}: ${content}`;
  document.body.appendChild(toast);

  setTimeout(() => {
    document.body.removeChild(toast);
    if (callback) callback();
  }, 2000);
}

xs.customToast(mobileToast);

Funzionalità di Ottimizzazione Mobile:

  • Posizionamento in basso (adatto al pollice)
  • Larghezza percentuale (massimo 80%)
  • Durata più corta (2 secondi)
  • Obiettivi di tap più grandi
  • Nessun overlay (non bloccante)

API Reference

customToast(toastFunction)

Sets a custom toast notification function for the spreadsheet instance.

Parameters:

  • toastFunction (Function | null): Custom toast function with signature (title, content, callback) => void
    • Pass null to restore default toast behavior

Returns:

  • The spreadsheet instance (for method chaining)

Example:

// Set custom toast
xs.customToast(myToastFunction);

// Restore default
xs.customToast(null);

// Method chaining
xs.customToast(myToast)
  .loadData(data)
  .setActiveSheet(0);

Best Practices

1. Always Handle the Callback

Ensure you call the callback function if provided, as it may contain important cleanup or continuation logic:

function myToast(title, content, callback) {
  // ... show toast ...
  if (callback) callback();  // ✅ Always call
}

2. Notifiche Non Bloccanti

Per una migliore esperienza utente, utilizzare notifiche toast non bloccanti invece di avvisi modali:

// ❌ Blocks user interaction
alert(`${title}: ${content}`);

// ✅ Non-blocking
showToastNotification(title, content);

3. Durata Appropriata

Scegli durate di autoscadenza appropriate in base alla lunghezza del contenuto:

const duration = content.length > 50 ? 5000 : 3000;
setTimeout(remove, duration);

4. Accessibilità

Assicurati che il tuo toast personalizzato sia accessibile:

toast.setAttribute('role', 'alert');
toast.setAttribute('aria-live', 'polite');
toast.setAttribute('aria-atomic', 'true');

5. Gestione degli Errori

Avvolgi la funzione toast in try-catch per evitare di interrompere il foglio di calcolo:

xs.customToast((title, content, callback) => {
  try {
    // Your toast implementation
    myCustomToast(title, content);
  } catch (error) {
    console.error('Toast error:', error);
  } finally {
    if (callback) callback();
  }
});

6. Pulizia delle Risorse

Pulire sempre gli elementi DOM e gli ascoltatori di eventi:

function myToast(title, content, callback) {
  const toast = document.createElement('div');
  // ... setup toast ...

  const remove = () => {
    document.body.removeChild(toast);
    // Clean up any event listeners
    toast.onclick = null;
    if (callback) callback();
  };

  document.body.appendChild(toast);
  setTimeout(remove, 3000);
}

7. Ripristino alle Impostazioni Predefinite Quando Necessario

Fornire un modo per ripristinare il comportamento predefinito del toast:

// Set custom toast
xs.customToast(myToast);

// Later, restore default
xs.customToast(null);

Troubleshooting

Toast Not Showing

Problem: Custom toast function is called but nothing appears.

Solutions:

  1. Check z-index values (ensure they’re higher than spreadsheet elements)
  2. Verify the toast element is appended to document.body
  3. Check browser console for JavaScript errors

Callback Not Working

Problem: Operations after toast don’t execute.

Solution: Ensure you’re calling the callback function:

if (callback) callback();  // Don't forget this!

Perdita di Memoria

Problema: La pagina diventa lenta dopo molte notifiche toast.

Soluzione: Pulire gli elementi DOM e gli ascoltatori di eventi:

const remove = () => {
  document.body.removeChild(toast);
  toast.onclick = null;  // Remove event listeners
  if (callback) callback();
};

Problemi di visualizzazione su dispositivi mobili

Problema: La toastsa sembra brutta sui dispositivi mobili.

Soluzioni:

  1. Usa larghezze percentuali: maxWidth: '80%'
  2. Add viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1">
  3. Usa dimensioni font relative: fontSize: '14px' invece di pixel fissi
come creare un editor collaborativo di Excel con GridJs