更新记录

1.0.1（2026-09-02）

• 优化插件名称、搜索标签和市场简介
• 增加适用场景、能力对比、购买前说明和常见问题
• 更新接入示例，突出批量导入到业务接口的完整流程
• 移除可能触发平台文档过滤的示例字段

1.0.0（2026-09-02）

• 支持本地读取 xlsx、xls、xlsm 与 CSV 文件
• 支持多工作表选择和自定义表头行
• 支持表格预览、字段别名智能匹配与手动映射
• 支持必填、唯一、正则、数字、整数、布尔和日期校验
• 支持错误明细复制与结构化业务数据输出

平台兼容性

uni-app(5.24)

其他

Excel 批量导入、字段映射与数据校验专业版

把 Excel 导入功能从“读取文件”直接做到“可提交业务接口”。适合客户资料、商品、订单、库存、报名名单等后台批量导入场景。

用户选择文件后，组件会完成：选择工作表 → 识别表头 → 预览数据 → 智能匹配字段 → 转换类型 → 校验错误 → 输出 JSON。

为什么需要它

普通 xlsx 解析库只能把单元格读出来，真正的业务导入还需要字段匹配、类型处理、必填检查、重复检查、错误定位和交互界面。本组件把这些常见工作组合成可直接使用的完整流程。

适用场景

• 客户、会员、员工等资料批量导入
• 商品、SKU、库存和价格批量更新
• 订单、账单、报名名单批量录入
• 不同客户 Excel 模板的列名兼容
• 导入前发现缺失、重复和格式错误的数据

核心能力

• 支持 .xlsx、.xls、.xlsm、.csv
• 支持多个工作表切换和任意表头行设置
• 支持最多 10000 行读取与横向表格预览
• 根据字段 label、key、aliases 自动匹配，也可手动调整
• 支持 string、number、integer、boolean、date 类型转换
• 支持 required、unique、pattern 校验
• 错误信息包含原始行号、目标字段和具体原因
• 校验通过后输出 data、mapping、source，可直接提交后端
• 全程在用户设备本地解析，不上传业务文件

3 分钟接入

快速使用

<template>
  <dz-excel-mapper-pro
    :target-fields="fields"
    @confirm="handleConfirm"
    @error="handleError"
  />
</template>

<script setup>
const fields = [
  { key: 'productName', label: '商品名称', required: true,
    aliases: ['产品名称', '品名'] },
  { key: 'sku', label: '商品编码', required: true, unique: true,
    aliases: ['SKU', '货号'] },
  { key: 'stock', label: '库存数量', type: 'integer', required: true,
    aliases: ['库存', '数量'] }
]

function handleConfirm(result) {
  // result.data 已完成字段改名、类型转换和规则校验
  uni.request({
    url: '/api/products/import',
    method: 'POST',
    data: result.data
  })
}
</script>

字段配置示例

const fields = [
  {
    key: 'orderNo',
    label: '订单编号',
    aliases: ['订单号', '单号'],
    required: true,
    unique: true
  },
  {
    key: 'amount',
    label: '订单金额',
    aliases: ['金额', '实付金额'],
    type: 'number',
    required: true
  },
  {
    key: 'createdAt',
    label: '下单日期',
    aliases: ['日期', '创建时间'],
    type: 'date'
  }
]

属性

事件

兼容说明

当前版本面向 uni-app Vue3 的 Web（Chrome、Safari）和微信小程序。Web 从本地文件选择，微信小程序从聊天会话选择文件。普通 uni-app 的 App-vue 暂不支持内置文件选择，因此不声明 App 支持；如业务已经取得 ArrayBuffer，可通过组件实例的 loadArrayBuffer(buffer, fileName) 方法载入。

购买前说明

• 插件市场支持免费试用，建议先在目标项目验证界面与文件格式。
• 普通授权适合直接用于项目；源码授权适合需要阅读或二次调整全部源码的团队。
• 本组件重点解决“业务数据导入”，不包含 Excel 样式编辑和 Excel 文件导出。
• 加密文件、损坏文件以及包含复杂宏逻辑的文件不在支持范围内。

常见问题

Excel 列名和系统字段名不同怎么办？

在 aliases 中配置常见列名，组件会自动匹配；用户也可以在导入界面手动调整。

表头不是第一行怎么办？

组件支持切换表头行，会基于新表头重新生成预览和字段映射。

能否在校验通过后直接调用接口？

可以。监听 confirm 事件，使用 result.data 作为接口请求数据即可。

文件是否会上传到第三方服务器？

不会。文件解析和校验均在用户设备本地完成。

开源软件声明

插件内置 SheetJS Community Edition 0.20.3 官方构建，依据 Apache License 2.0 使用。详见 THIRD_PARTY_NOTICES.md。