CatchAdmin 专业版文档

主题

数据导入 ​

CatchAdmin 专业版基于 Laravel Excel 封装了一套统一的导入器。常规导入、大文件分块导入、导入校验、异步导入都走这一套。

标准导入类 ​

导入类继承 Catch\Support\Excel\Import，核心方法是 collection()。

php
<?php

declare(strict_types=1);

namespace Modules\User\Import;

use Catch\Support\Excel\Import;
use Illuminate\Support\Collection;
use Modules\User\Models\User;

class UserImport extends Import
{
    protected int $chunkSize = 200;

    protected int $start = 2;

    protected static int $importMaxNum = 5000;

    public function collection(Collection $rows): void
    {
        $rows->each(function ($row) {
            User::create([
                'username' => $row[0],
                'email' => $row[1],
                'status' => $row[2] ?? 1,
            ]);
        });
    }

    public function rules(): array
    {
        return [
            '0' => 'required|string|max:50',
            '1' => 'required|email',
            '2' => 'nullable|integer|in:1,2',
        ];
    }

    public function customMessages(): array
    {
        return [
            '1.email' => '邮箱格式不正确',
        ];
    }
}

控制器：

php
public function import(Request $request, UserImport $import): mixed
{
    return $import->import($request->file('file'));
}

常用配置 ​

属性 / 方法说明
collection(Collection $rows): void必填，处理当前分块的数据
rules(): array导入校验规则
customMessages(): array自定义错误信息
customAttributes(): array自定义字段别名
$chunkSize每次读取的块大小，默认 200
$start起始行，默认 2
$importMaxNum单次最大导入数量，默认 5000
import($file, ?string $disk = null, ?string $readerType = null)执行导入
async()开启异步导入
setParams(array $params)传入额外参数

校验规则说明 ​

  • 校验规则使用列索引作为 key，例如 '0'、'1'
  • 行数据通过 $row[0]、$row[1] 读取
  • 第一行通常是表头，所以默认从第二行开始读取

导入返回结果 ​

成功 ​

导入成功时，返回处理总数：

php
120

校验失败 ​

校验失败时，返回结构化错误信息：

php
[
    'error' => [
        '第2行错误:邮箱格式不正确',
        '第5行错误:状态字段必须是 1 或 2',
    ],
    'total' => 100,
    'path' => 'excel/import/20260419/xxxx.xlsx',
    'success' => 98,
    'failed' => 2,
    'warnings' => [],
]

path 是导入文件保存路径。异步重试和导入记录都会用到这个路径。

指定磁盘和读取类型 ​

导入文件来自指定磁盘，或者需要强制指定读取类型时，可以直接传参数：

php
use Maatwebsite\Excel\Excel;

public function import(Request $request, UserImport $import): mixed
{
    return $import->import($request->file('file'), 'uploads', Excel::CSV);
}

异步导入 ​

大批量导入优先走异步任务。

php
<?php

declare(strict_types=1);

namespace Modules\User\Import;

use Catch\Contracts\AsyncTaskInterface;
use Catch\Support\Excel\Import;
use Illuminate\Support\Collection;
use Modules\System\Support\Traits\AsyncTaskDispatch;
use Modules\User\Models\User;

class UserImport extends Import implements AsyncTaskInterface
{
    use AsyncTaskDispatch;

    public function collection(Collection $rows): void
    {
        $rows->each(function ($row) {
            User::create([
                'username' => $row[0],
                'email' => $row[1],
            ]);
        });
    }
}

控制器里开启异步模式：

php
public function import(Request $request, UserImport $import): mixed
{
    return $import->async()->import($request->file('file'));
}

异步任务配置见 异步任务。

前端接入 ​

CatchTable 直接支持导入按钮：

vue
<catch-table
  api="users"
  :columns="columns"
  importUrl="/user/import"
/>

单独使用导入组件时，直接配置上传地址：

vue
<Import action="/user/import" />

代码生成与导入模板 ​

代码生成器支持直接生成导入类，同时生成一份导入模板。模板文件默认保存到 storage/static/importTemplates。

生成后的导入类适合直接作为起点，常见的补充项有：

  • 字段去重和重复校验
  • 字典值转换
  • 关联数据检查
  • 失败记录回写

代码生成的详细用法见 代码生成。

注意事项 ​

  • 控制器上传字段名使用 file
  • 表头和导入列顺序需要保持一致
  • 大批量导入优先使用异步任务
  • chunkSize 和 importMaxNum 按业务量调整
  • 复杂业务校验尽量写在导入类里，控制器保持轻量