如何定制 GridJs 中消息提示的界面外观

GridJs 自定义提示指南

概述

GridJs 提供了一个灵活的自定义提示通知系统，允许你用自己的通知实现替代默认的提示消息。本指南演示了根据应用需求自定义提示通知的各种方法。

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

可用图标：

成功
错误
警告
信息
问题

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

通知类型：

成功
警告
信息
错误

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

用例：

调试日志
用户行为追踪
错误监控
性能指标

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的自定义下载功能