如何使用 ImportKit：在 10 分钟内为你的 React 应用添加 CSV/Excel 导入

抱歉，我需要您提供要翻译的具体文本内容（文章正文）。请把您想要翻译的完整文字粘贴在这里，我会按照要求保留源链接并进行简体中文翻译。

概览

从头构建 CSV 导入功能需要数周时间——你需要文件解析、列映射 UI、验证逻辑、错误处理以及 Excel 支持。ImportKit 提供了所有这些功能，作为可直接使用的 React 组件，你可以在一个下午内集成。

本指南演示一个常见场景：让用户将联系人列表导入到 CRM 应用中。

前置条件

您需要：

• 一个 React 18.x 或 React 19.x 应用（包括 Next.js）
• 一个 ImportKit 账户 – 在此注册
• 大约 10 分钟

ImportKit 将 React 18 和 React 19 列为 peer 依赖，因此它可在任何现代 React 环境中使用。

第一步：安装包

ImportKit 在 npm 上以 @importkit/react 发布。该包采用 MIT 许可证，并包含 TypeScript 类型定义。

npm install @importkit/react

该库通过 tsup 提供 ESM/CJS 双构建，因此可在现代和传统打包工具中使用。

第2步：获取 API 密钥

1. 登录 ImportKit 仪表板。
2. 前往 API Keys → Generate New Key。

该小部件需要 API 密钥进行身份验证和使用跟踪。密钥按用户范围分配，可在仪表板中撤销。

• 免费层 – 每月 500 行（通过 Supabase pg_cron 在每月 1 日自动重置）。
• 入门版 – 每月 5 000 行。
• 专业版 – 每月 50 000 行。
• 企业版 – 无限行。

第3步：定义数据模式

ImportKit 使用字段配置来描述您期望的数​​据。对于联系人导入，您可以这样定义：

const contactFields = [
  {
    name: 'email',
    label: 'Email Address',
    type: 'email',
    required: true,
  },
  {
    name: 'firstName',
    label: 'First Name',
    type: 'text',
    required: true,
  },
  {
    name: 'lastName',
    label: 'Last Name',
    type: 'text',
    required: false,
  },
  {
    name: 'status',
    label: 'Status',
    type: 'enum',
    enum: {
      values: ['Active', 'Inactive', 'Pending'],
      hints: ['enabled,live', 'disabled,off', 'waiting,review'],
    },
  },
  {
    name: 'age',
    label: 'Age',
    type: 'number',
    validate: [
      {
        type: 'min',
        value: 0,
        message: 'Age must be positive',
      },
    ],
  },
];

字段类型

ImportKit 支持 text、email、number、date 和 enum。每种类型都可以拥有自定义验证规则，例如：

• 邮箱格式检查
• 数值范围（min、max）
• 字符串长度约束（minLength、maxLength）
• 正则表达式模式

enum 类型使用六步匹配级联（精确匹配、大小写不敏感、客户学习、全局学习、开发者提示、AI 语义）来自动映射混乱的源值。

第 4 步：将 Widget 添加到您的组件

import { ImportWidget } from '@importkit/react';

function ContactImportPage() {
  const handleComplete = (data: any[]) => {
    console.log('Imported contacts:', data);
    // Send to your API
    fetch('/api/contacts/bulk', {
      method: 'POST',
      body: JSON.stringify(data),
      headers: { 'Content-Type': 'application/json' },
    });
  };

  return (
    <>
      {/* ImportWidget goes here */}
      <ImportWidget
        fields={contactFields}
        apiKey="YOUR_API_KEY"
        onComplete={handleComplete}
      />
    </>
  );
}

该 Widget 负责处理所有内容：

• 拖拽式文件上传
• 解析 CSV 与 Excel 文件（.csv、.xlsx、.xls）
• 列映射 UI
• 验证与错误纠正
• 多步骤引导界面

第5步：让 AI 处理列映射

当文件上传时，ImportKit 会将 CSV 表头和您的目标字段发送到 /api/suggest-mapping。该端点调用 OpenAI gpt‑4o‑mini（temperature = 0），并接收带有置信度分数的结构化 JSON 响应。

如果 AI 服务不可用，组件会回退到快速子字符串匹配，确保导入仍能正常工作。

示例映射（CSV 列：“E‑mail”、 “First”、 “Last”、 “Account Status”）：

用户可以手动覆盖任何建议。

第6步：导入前验证

ImportKit 实时验证每一行数据，并在预览步骤中显示内联错误。用户可以：

• 仅导入通过验证的行，或
• 在继续之前直接在 UI 中修复错误。

支持的验证规则包括：

• 邮箱格式
• 数值范围（min、max）
• 字符串长度（minLength、maxLength）
• 正则表达式模式
• 枚举值匹配
• 必填字段强制

这种预先验证可以减少错误数据进入系统，并降低支持工单数量。

可选：使用模板进行可复用配置

如果你有多个导入场景（例如，联系人、产品、订单），或希望让高级用户自行管理导入，可以将字段配置保存为 模板 并动态加载：

import { ImportWidget, loadTemplate } from '@importkit/react';

const template = await loadTemplate('contacts');

模板可以存储在数据库或 CDN 中，便于在项目之间维护一套导入定义库。

就是这样！

只需几分钟的设置，ImportKit 为您提供强大的 CSV/Excel 导入、AI‑assisted 列映射和全面的验证——全部封装在精致的 React 组件中。祝导入愉快！

Source: …

ImportKit – 快速参考指南

1. 加载已保存的导入配置

模板存储在 Supabase 的 import_templates 表中，并通过组件的 templateId 属性加载：

这使得在不同用户和会话之间保持导入的一致性，同时减少实现时间。非技术用户可以通过仪表盘的 CRUD UI 管理导入配置。

2. 可选：自定义外观

ImportKit 支持完整的主题定制，以匹配您的品牌。您可以自定义颜色、边框、字体，并隐藏 “Powered by ImportKit” 品牌标识：

将 showBranding 设置为 false 可移除页脚，实现白标体验。

3. 可选：设置 Webhook 发送

注意： Webhook 仅在 Pro 或 Enterprise 级别可用。

1. 在仪表盘中 配置 webhook URL。
2. ImportKit 在每次导入完成后 POST 导入数据到您的端点。

请求头

• X-ImportKit-Signature：请求体的 HMAC‑SHA256 签名。
• 密钥通过 crypto.randomBytes(32) 生成。

重试策略

• 最多 3 次 重试，采用指数退避（1 秒 → 4 秒）。
• 每次尝试 10 秒 超时。

负载示例

{
  "event": "import.completed",
  "importId": "uuid",
  "rowCount": 150,
  "templateName": "Contact Import",
  "timestamp": "2024-01-28T10:30:00Z"
}

如果所有重试均失败，系统会记录失败但 不会 阻塞导入响应。对用户而言，Webhook 为“发送即忘”。

4. 背后发生的工作

所有身份验证均通过请求体中的 API key 完成（不使用 cookie）。

5. 何时使用 ImportKit 与自行实现

组件的源代码采用 MIT 许可证，位于 github.com/gthorr/importkit。仪表盘和后端属于托管服务的一部分。

6. 更多资源

• GitHub 仓库：
• 官方文档：

如有实现问题，欢迎在 GitHub 上提交 Issue，或查阅文档获取更深入的集成细节。