npm package: @moluoxixi/importexcel
Description: ImportExcel 组件
Latest version: 0.0.2

# ImportExcel 导入组件

基于 element-plus 与 xlsx 的 Excel 导入按钮。点击按钮选择本地文件并解析为对象数组。

## 能力概述

- 通过 `columns`, `titles`, `fields`, `tableData` 四个 props 进行配置：
  - `columns`：仅支持数组写法：`[{ label/title, prop/field, ... }]`
  - `titles`：用于从 `columns` 中匹配列头名称的字段名优先级，默认 `['title','label']`
  - `fields`：用于从 `columns`/`tableData` 中匹配字段 key 的字段名优先级，默认 `['field','prop']`
  - `tableData`：可选，保持与导出组件接口一致（当前组件不直接使用）

## 列映射规则

- 最终规则：表头名称 → 字段 key
- 当 header 列表与 key 列表等长时，按索引一一对应
- 当 header 为多值、key 为单值时，多头映射同一 key
- 当 header 为单值、key 为多值时，默认取第一个 key

## 示例一：数组写法（自动按 titles/fields 取值）

```vue
<template>
  <ImportExcel
    :columns="[
      { label: '姓名', prop: 'name' },
      { title: '年龄', field: 'age' },
      { label: '地址', prop: 'address' }
    ]"
    @success="onSuccess"
  />
  <!-- titles 默认为 ['title','label']，fields 默认为 ['field','prop'] -->
  <!-- 因此会优先从 title/field 取值，其次 fallback 到 label/prop -->
  <!-- 上例等价于混合使用 label/prop 与 title/field -->
  
  <!-- 自定义按钮 -->
  <!-- <ImportExcel :columns="columns" type="primary">选择文件导入</ImportExcel> -->

  <!-- 自定义优先级 -->
  <!-- <ImportExcel :columns="columns" :titles="['label','title']" :fields="['prop','field']" /> -->

  <!-- 可选：保持接口一致性 -->
  <!-- <ImportExcel :columns="columns" :table-data="someRows" /> -->
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
```

```vue
<script setup>
function onSuccess(rows) {
  console.log(rows) // [{ name: '张三', age: 18, address: '北京市朝阳区' }, ...]
}
</script>
```

> 说明：本组件不再支持 `columns` 的对象写法（props/fields 分类），只保留数组写法，通过 `titles/fields` 两个优先级数组控制映射。

## API

- Props
  - `columns` Array | Object 必填：
    - 数组：`Array<{ label?: string|string[], title?: string|string[], prop?: string|string[], field?: string|string[] }>`
    - 对象：`{ props?: Array<{ label: string|string[], prop: string|string[] }>, fields?: Array<{ title: string|string[], field: string|string[] }> }`
  - `titles` string[] = `['title','label']`：用于从 `columns` 中匹配列头名称
  - `fields` string[] = `['field','prop']`：用于从 `columns`/`tableData` 中匹配字段 key
  - `tableData` any[] = `[]`：可选（当前组件不直接使用）
- Events
  - `success`(rows: any[]): 解析成功数据
  - `error`(error: any): 解析失败错误
- Slots
  - `default`: 自定义按钮内容

## 支持的文件类型

`.xlsx`、`.xls`、`.csv`