---
nav:
  title: 组件
  order: 1
group:
  title: Data Entry
  order: 1
title: PisellImport
order: 2
category: atom
---

# PisellImport 导入按钮

导入触发器组件，样式与 PisellExport 一致，支持「仅图标」与「图标+文案」两种形态、三种尺寸。点击后打开系统文件选择框，可选择文件并做大小校验，通过后通过 `onImport(files)` 回调将文件列表交给调用方处理上传或解析。

## 何时使用

- 批量导入 Excel/CSV 等文件
- 与 PisellExport 搭配的导入导出能力
- 需要限制文件类型、大小或多选的导入场景

## 代码演示

### 基础用法

点击后打开文件选择，选择完成后在 `onImport` 中拿到 `File[]`，由调用方实现上传或解析。

```tsx
import React from 'react';
import { PisellImport } from '@pisell/materials';

export default () => {
  return (
    <PisellImport
      onImport={(files) => {
        console.log('已选文件', files);
        // 调用方：上传、解析等
      }}
    />
  );
};
```

### 限制文件类型与大小

通过 `accept` 限制可选类型，通过 `maxSize`（MB）限制单文件大小；超出时触发 `onError`。

```tsx
import React from 'react';
import { PisellImport } from '@pisell/materials';
import { message } from 'antd';

export default () => {
  return (
    <PisellImport
      accept=".xlsx,.xls,.csv"
      maxSize={10}
      onImport={(files) => {
        message.success(`已选择 ${files.length} 个文件`);
      }}
      onError={({ message: msg }) => {
        message.error(msg);
      }}
    />
  );
};
```

### 多选文件

`multiple={true}` 时允许一次选择多个文件。

```tsx
import React from 'react';
import { PisellImport } from '@pisell/materials';

export default () => {
  return (
    <PisellImport
      multiple
      label="选择多个文件"
      onImport={(files) => {
        console.log('已选', files.length, '个文件', files.map((f) => f.name));
      }}
    />
  );
};
```

### 仅图标与不同尺寸

与 PisellExport 相同，支持 `variant="icon"` 和 `size`。

```tsx
import React from 'react';
import { PisellImport } from '@pisell/materials';

export default () => {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
      <PisellImport variant="icon" onImport={() => {}} />
      <PisellImport size="small" onImport={() => {}} />
      <PisellImport size="large" type="primary" onImport={() => {}} />
    </div>
  );
};
```

### 与导出并排

常与 PisellExport 一起使用。

```tsx
import React from 'react';
import { PisellImport, PisellExport } from '@pisell/materials';

export default () => {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
      <PisellImport
        accept=".xlsx,.csv"
        maxSize={10}
        onImport={(files) => console.log('导入', files)}
        onError={({ message: msg }) => console.error(msg)}
      />
      <PisellExport onExport={() => console.log('导出')} />
    </div>
  );
};
```

## API

### PisellImport Props

| 参数      | 说明                         | 类型                                                                 | 默认值    | 必填 |
| --------- | ---------------------------- | -------------------------------------------------------------------- | --------- | ---- |
| variant   | 展示形态                     | `'icon' \| 'button'`                                                | `'button'` | ❌   |
| size      | 尺寸                         | `'small' \| 'medium' \| 'large'`                                   | `'medium'` | ❌   |
| type      | 视觉类型                     | `'default' \| 'primary'`                                            | `'default'` | ❌   |
| disabled  | 是否禁用                     | `boolean`                                                            | `false`   | ❌   |
| label     | Button 形态文案               | `ReactNode`                                                          | 国际化默认 | ❌   |
| icon      | 自定义图标                   | `ReactNode`                                                          | 内置导入图标 | ❌   |
| accept    | 接受的文件类型               | `string`（如 `.xlsx,.csv`）                                          | -         | ❌   |
| multiple  | 是否多选                     | `boolean`                                                            | `false`   | ❌   |
| maxSize   | 单文件最大体积（MB）         | `number`                                                             | -         | ❌   |
| onImport  | 选择文件并校验通过后回调     | `(files: File[], e: React.ChangeEvent<HTMLInputElement>) => void`   | -         | ❌   |
| onError   | 校验失败时回调（如文件过大） | `(error: { type: 'MAX_SIZE'; message: string; file: File }) => void` | -         | ❌   |
| className | 自定义类名                   | `string`                                                             | -         | ❌   |
| style     | 自定义样式                   | `CSSProperties`                                                      | -         | ❌   |

### onError 参数

当 `maxSize` 校验不通过时，`onError` 会收到：

- `type`: `'MAX_SIZE'`
- `message`: 提示文案（含体积限制，支持国际化）
- `file`: 超限的 File 对象

可在回调中使用 `message.error(error.message)` 等方式提示用户。

## 注意事项

1. **回调必传**：实际使用中建议传入 `onImport`，否则选择文件后无法处理
2. **文件校验**：需限制类型时传 `accept`，需限制大小时传 `maxSize` 并实现 `onError` 提示用户
3. **多选**：`multiple={true}` 时一次可选多个文件，`onImport` 收到的 `files` 为数组
4. **搭配使用**：常与 PisellExport 并排使用，形成导入导出能力

## 相关文档

- [设计文档](./pisellImport.$tab-design.md)
- [开发文档](./pisellImport.$tab-dev.md)
- [测试文档](./pisellImport.$tab-test.md)
