как настроить внешний вид UI для подсказки сообщения в GridJs

Руководство по созданию пользовательских toast сообщений для GridJs

Обзор

GridJs предлагает гибкую систему пользовательских уведомлений toast, которая позволяет вам заменить стандартные сообщения toast на свои собственные. Это руководство демонстрирует различные подходы к настройке уведомлений toast в соответствии с потребностями вашего приложения.

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);

Параметры:

title (строка): Заголовок уведомления тоста
content (строка): Содержание сообщения тоста
callback (функция, необязательно): Функция обратного вызова после закрытия тоста

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);

Особенности:

Градиентный фон
Модальный слой
Клик для закрытия
Автоматическое закрытие через 3 секунды
Кнопка закрытия

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>

Реализация:

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

Настраиваемые параметры:

closeButton: Показывать кнопку закрытия
progressBar: Отображать счетчик обратного отсчета
positionClass: Регулирует положение тоста (верхний правый, нижний левый и т.д.)
timeOut: Время автоматического закрытия в миллисекундах

3. SweetAlert2 Integration

Use SweetAlert2 for beautiful, customizable alert dialogs.

Prerequisites:

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

Реализация:

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

Доступные иконки:

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
      });
    });
  }
});

Типы уведомлений:

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>;
};

Альтернативные компоненты Ant Design:

message.success()
message.error()
message.warning()
notification.open() (для более сложных уведомлений)

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);
});

Примеры использования:

Журнал ошибок (Debug логирование)
Отслеживание поведения пользователя
Мониторинг ошибок
Метрики производительности

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);

Функции мобильной оптимизации:

Расположение внизу (удобно для большого пальца)
Ширина на основе процентов (максимум 80%)
Более короткая продолжительность (2 секунды)
Большие цели для нажатия
Без наложения (невмешивающийся)

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. Неблокирующие уведомления

Для лучшего пользовательского опыта используйте неблокирующие тост-уведомления вместо модальных оповещений:

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

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

3. Соответствующая длительность

Выбирайте подходящую длительность автоматического исчезновения в зависимости от длины контента:

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

4. Доступность

Убедитесь, что ваш пользовательский тост доступен:

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

5. Обработка ошибок

Оборачивайте функцию тоста в try-catch, чтобы избежать сбоев в таблице:

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

6. Очистка ресурсов

Всегда очищайте элементы DOM и обработчики событий:

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. Восстановление стандартных настроек при необходимости

Обеспечьте способ восстановления стандартного поведения тостов:

// 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:

Check z-index values (ensure they’re higher than spreadsheet elements)
Verify the toast element is appended to document.body
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!

Утечки памяти

Проблема: Страница становится медленной после многочисленных уведомлений тост.

Решение: Очистите DOM-элементы и обработчики событий:

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

Проблемы отображения на мобильных устройствах

Проблема: Тост выглядит плохо на мобильных устройствах.

Решения:

Используйте ширины в процентах: maxWidth: '80%'
Add viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1">
Используйте относительные размеры шрифта: fontSize: '14px' вместо фиксированных пикселей

Пользовательская функция скачивания для GridJs