UploadExcel Excel 上传

UploadExcel Excel 上传 的基础用法、公开 API 与示例。

基础示例

选择 Excel 文件并解析表头与数据。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref } from "vue";
import { exportJsonToExcel } from "@/common/utils";
import { UploadExcel } from "@/components/page/excel-upload";

const rows = ref(0);
const downloadSample = () =>
  exportJsonToExcel(["name", "quantity"], [["演示材料", 2]], "idx-demo");
const demoProps = {
  onSuccess: (data: import("@/components/page/excel-upload").ExcelData) => {
    rows.value = data.results.length;
  },
};
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <el-button @click="downloadSample">下载本地示例 Excel</el-button>
      <UploadExcel v-bind="demoProps"></UploadExcel>
      <p role="status">已解析 {{ rows }} 行</p>
    </div>
  </ClientOnly>
</template>

隐藏源代码

拖拽上传

开启拖拽区域，并在上传前校验文件后缀。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref } from "vue";
import { UploadExcel } from "@/components/page/excel-upload";

const message = ref("拖拽或选择 Excel 文件后会显示解析结果");

const beforeUpload = (file: File) => {
  const valid = /\.(xlsx|xls|csv)$/.test(file.name);
  message.value = valid ? `准备解析：${file.name}` : "只支持 xlsx、xls、csv 文件";
  return valid;
};

const handleSuccess = (data: { header: string[]; results: Record<string, unknown>[] }) => {
  message.value = `读取 ${data.results.length} 行，表头：${data.header.join("、") || "无"}`;
};
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <UploadExcel drag :before-upload="beforeUpload" :on-success="handleSuccess" />
      <p class="excel-tip">{{ message }}</p>
    </div>
  </ClientOnly>
</template>

<style scoped>
.excel-tip {
  margin: 12px 0 0;
  color: #667085;
}
</style>

隐藏源代码

引入方式

import { UploadExcel } from "@/components/page/excel-upload";

Props

参数	说明	类型	默认值	必填
drag	是否显示拖拽区域。boolean 类型，默认为 false	boolean	false	否
beforeUpload	上传前回调。(file: File) => boolean 类型	(file: File) => boolean	-	否
onSuccess	上传成功回调。(excelData: ExcelData) => void 类型	(excelData: ExcelData) => void	-	是

Events

事件名	说明	回调参数
-	该组件未声明 Events。	-

Slots

插槽名	说明	参数
-	该组件未声明 Slots。	-

Expose

名称	说明	类型
-	该组件未声明 Expose。	-

Module API

名称	说明	类型
UploadExcel	导出 UploadExcel 供业务侧复用。	useInstall(index)

Types

UploadExcelProps

导出 UploadExcelProps 供业务侧复用。

字段	说明	类型	默认值	必填
drag	是否显示拖拽区域。boolean 类型，默认为 false	boolean	-	否
beforeUpload	上传前回调。(file: File) => boolean 类型	(file: File) => boolean	-	否
onSuccess	上传成功回调。(excelData: ExcelData) => void 类型	(excelData: ExcelData) => void	-	是

ExcelData

Excel 上传解析后的数据。

字段	说明	类型	默认值	必填
results	表格数据行	Record<string, unknown>[]	-	是
header	表头字段	string[]	-	是

API 根据当前组件源码生成；同步版本与验证记录见维护说明。