xlsx-to-json-img
Version:
Convert Excel (.xlsx) to JSON with embedded images as Base64. Supports custom column mapping.
271 lines (232 loc) • 8.43 kB
Markdown
# excel 导入图片
## options
以下是针对 `options` 配置对象的**详细文档说明**：
### 📄 `excelToJsonWithImages` 方法配置项 `options` 说明文档
该 `options` 对象用于配置 `xlsx-to-json-img` 库中 `excelToJsonWithImages(file, options)` 方法的解析规则，主要用于将 Excel 文件中的多个工作表（Sheet）按指定格式转换为 JSON 数据，并支持提取单元格中的图片。
#### 🔧 配置结构概览
```js
const options = {
[SheetName]: {
columns: [...],
headerIndex: Number
},
...
};
```
### ✅ 字段详细说明
| 字段名 | 类型 | 必填 | 说明 |
|-------|------|------|-----------------------------------------------------------------------------------|
| `SheetName` | `String` | 是 | Excel 文件中工作表（Sheet）的名称，如 `"测试"`、`"Sheet2"`。该名称必须与 Excel 中的实际工作表名称**完全一致**（区分大小写）。 |
| `columns` | `Array` | 是 | 定义当前工作表中需要解析的列信息，按顺序对应表头。 |
| `headerIndex` | `Number` | 是 | 指定该工作表中**表头所在行的索引**（从 0 开始计数），即第几行是列名所在行。例如：`headerIndex: 1` 表示第 2 行是表头。 |
### 📌 `columns` 列配置项说明
`columns` 是一个对象数组，每个对象描述一列的映射规则。
| 字段名 | 类型 | 必填 | 说明 |
|-------|------|----|------|
| `name` | `String` | 是 | Excel 表格中该列**表头显示的文本**（即列名），用于匹配实际的列。例如：`"联系人"`、`"车牌号"`。匹配时不支持模糊匹配，需完全一致。 |
| `field` | `String` | 是 | 转换为 JSON 后，该列数据对应的**字段名（key）**。例如：`"contactPerson"`、`"plateNum"`。可用于后续数据处理。 |
| `isImage` | `Boolean` | 是 | 标识该列是否包含**图片数据**。若为 `true`，则库会尝试提取该单元格内的图片（如插入的图片、图像对象等），并以 Base64形式返回。 |
> ⚠️ 注意：
> - `isImage: true` 的列，其 `name` 必须与 Excel 表头完全匹配。
> - 若同一行多个列设置 `isImage: true`，需确保每列对应单元格中确实有图片，否则可能解析失败或遗漏。
### 📚 示例说明
```js
const options = {
测试: {
columns: [
{ name: '序号', field: 'index', isImage: false },
{ name: '联系人', field: 'contactPerson', isImage: false },
{ name: '联系电话', field: 'phone', isImage: false },
{ name: '车牌号', field: 'plateNUm', isImage: false },
{ name: '车牌颜色', field: 'color', isImage: false },
{ name: '图片1', field: 'image1', isImage: true },
{ name: '图片2', field: 'image2', isImage: true },
{ name: '图片3', field: 'image3', isImage: true }
],
headerIndex: 1
},
Sheet2: {
columns: [
{ name: '序号', field: 'index', isImage: false },
{ name: '姓名', field: 'name', isImage: false },
{ name: '地址', field: 'address', isImage: false },
{ name: '图片', field: 'image', isImage: true },
{ name: '照片', field: 'image2', isImage: true }
],
headerIndex: 0
}
};
```
#### 解析逻辑说明：
- **工作表 "测试"**
- 表头位于第 2 行。
- 前 5 列为普通文本字段，映射为 `index`, `contactPerson`, `phone` 等。
- 后 3 列为图片列，将尝试提取图片并分别赋值给 `image1`, `image2`, `image3` 字段。
- **工作表 "Sheet2"**
- 表头位于第 1 行。
> 💡 建议：如果有多张图片，使用不同的 `field` 名称（如 `photo1`, `photo2`）以避免数据覆盖。
### ⚠️ 使用注意事项
1. **表头匹配严格**：`name` 必须与 Excel 中实际显示的文本完全一致（包括空格、标点）。
2. **headerIndex 从 0 开始**：`headerIndex: 0` 表示第一行。
3. **字段命名唯一性**：尽量避免多个列使用相同的 `field` 名，防止数据被覆盖。
4. **编码问题**：确保 Excel 文件保存为 `.xlsx` 格式，暂未验证是否支持 `.xls`。
### Example
```vue
<template>
<div class="container">
<input type="text" class="ct-input" :value="filePath" />
<label class="ui-upload">浏览<input ref="file" type="file" style="display: none" @change="handleChange" /></label>
</div>
</template>
<script setup>
import { ref } from 'vue';
import { excelToJsonWithImages } from 'xlsx-to-json-img';
const filePath = ref('');
const file = ref();
/**
* 上传前处理
*/
const handleChange = async (e) => {
const file = e.target.files[0];
const options = {
测试: {
columns: [
{
name: '序号',
field: 'index',
isImage: false,
},
{
name: '联系人',
field: 'contactPerson',
isImage: false,
},
{
name: '联系电话',
field: 'phone',
isImage: false,
},
{
name: '车牌号',
field: 'plateNum',
isImage: false,
},
{
name: '车牌颜色',
field: 'color',
isImage: false,
},
{
name: '图片1',
field: 'image1',
isImage: true,
},
{
name: '图片2',
field: 'image2',
isImage: true,
},
{
name: '图片3',
field: 'image3',
isImage: true,
},
],
headerIndex: 1,
},
Sheet2: {
columns: [
{
name: '序号',
field: 'index',
isImage: false,
},
{
name: '姓名',
field: 'name',
isImage: false,
},
{
name: '地址',
field: 'address',
isImage: false,
},
{
name: '图片',
field: 'image',
isImage: true,
},
{
name: '照片',
field: 'image2',
isImage: true,
},
],
headerIndex: 0,
},
};
const result = await excelToJsonWithImages(file, options);
console.log('result', result);
// result 输出结果
};
</script>
<style scoped></style>
```
### Result
```js
reslut = {
images: [
{
descr: "ID_1", // 图片的原始名称
form: "A1", // 在表格中的位置，
id: "rId1", // 图片的源文件Id
imgId: "ID_E3145AF054DF49A69460818F674ECF08", // 图片的Id
isFloat: false, // 是否是浮动式，true-是浮动式， false-非浮动式
path: "data:image/image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...",// 图片的basea64
col: 7, // 列号
row: 1, // 行号
sheetName: "测试", // 表格sheet的名称
sheetId: "1", // 表格sheet的Id
},
...
],
metadata: {
sheetCount: 2, // 表格数量
imageCount: 11, // 图片数量
fileName: "excel测试文档.xlsx", // 文件名称
fileSize: 9266081, // 文件大小
fileLastModified: 1758088337026 // 文件最后修改时间
},
sheets: {
Sheets2:[
{
address: "测试地址1号",
image: "data:image/image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...",
image2: "data:image/image/jpeg;base64,/9j/4f2lRXhpZgAASUkq...",
index: 1,
name: "李四"
}
],
测试:[
{
color: "蓝色",
contactPerson: "张三",
image1: "data:image/image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...",
image2: "data:image/image/jpeg;base64,/9j/4Q5mRXhpZgAATU0A...",
image3: "data:image/image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...",
index: 1,
phone: 13112345678,
plateNum: "测试A12345"
},
...
]
}
}
```