更新记录

1.0.4（2026-08-25） 下载此版本

更新文档

1.0.3（2026-08-17） 下载此版本

更新返回数据格式

1.0.2（2026-03-12） 下载此版本

修改说明

平台兼容性

uni-app(3.8.2)

lu-parse-excel

文档说明

本插件基于 xlsx-js-style 与 plus.io 文件系统，在 UniApp 的 H5+ / APP（Android）环境 下解析本地 .xlsx 文件。 支持：

1. 在线 Excel 通过 uni.downloadFile 下载到本地后解析；
2. 本地路径直接解析；
3. 通过 fieldMap 把 Excel 表头映射为自定义字段名；
4. 同时返回原始数据与映射后数据，便于业务侧按需使用。

功能列表

1. APP 端（Android）解析 .xlsx 文件，已在 UniApp + Vue2/3 环境测试通过；
2. 仅读取第一个 Sheet（workbook.SheetNames[0]）；
3. 空单元格使用空字符串兜底（defval: ""），避免下游 undefined / null 判空麻烦；
4. 可选字段映射（fieldMap），同时返回映射前后的两份数据；
5. 通过 plus.io.FileReader.readAsDataURL + atob 解码，再交给 XLSX.read 解析，兼容 H5+ 的本地文件 API。

目录

1. 功能列表
2. 安装依赖
3. API 说明
4. 返回值结构
5. 完整示例
6. 关键注意事项
7. 常见问题排查

一、安装依赖

本插件依赖 xlsx-js-style：

# 使用 pnpm 安装依赖
pnpm add xlsx-js-style

# 或者使用 npm 安装依赖
npm install xlsx-js-style

# 或者使用 yarn 安装依赖
yarn add xlsx-js-style

二、API 说明

parseExcelFile(filePath, fieldMap?)

解析本地 Excel 文件，返回 Promise。

三、返回值结构

Promise 成功时返回：

{
    headers: string[],       // Excel 第一行表头
    data: Array<Object>,     // 应用 fieldMap 后的数据行（无 fieldMap 时与 rawData 一致）
    rawData: Array<Object>,  // 原始数据行（按 Excel 表头为 key 的对象数组，未应用 fieldMap）
}

四、完整示例

场景一：在线 Excel 下载后解析

<template>
    <view class="container">
        <button type="primary" @click="start">解析 Excel</button>
        <view v-if="result.data.length">
            已解析 {{ result.data.length }} 条数据
        </view>
    </view>
</template>

<script>
import { parseExcelFile } from "@/uni_modules/lu-parse-excel/js_sdk/excelUtils.js";

export default {
    data() {
        return {
            // 在线 Excel 链接（需先下载到本地再解析）
            excelUrl:
                "https://example.com/xxx.xlsx",
            result: {
                headers: [],
                data: [],
                rawData: [],
            },
        };
    },
    methods: {
        async start() {
            console.log("[STEP 0] 点击按钮");
            uni.showLoading({ title: "解析中..." });

            try {
                // 1. 下载到本地，得到 tempFilePath
                const res = await new Promise((resolve, reject) => {
                    uni.downloadFile({
                        url: this.excelUrl,
                        success: resolve,
                        fail: reject,
                    });
                });
                const tempFilePath = res.tempFilePath;
                console.log("[STEP 1] 下载成功，路径:", tempFilePath);

                // 2. 定义字段映射：key=Excel 表头，value=自定义字段名
                const fieldMap = {
                    姓名: "name",
                    年龄: "age",
                    性别: "sex",
                };

                // 3. 解析
                const result = await parseExcelFile(tempFilePath, fieldMap);
                this.result = result;

                console.log("[STEP 7] headers:", result.headers);
                console.log("[STEP 7] data:", result.data);
                console.log("[STEP 7] rawData:", result.rawData);

                uni.showToast({ title: "解析成功", icon: "success" });
            } catch (err) {
                console.error("[ERROR] 流程出错:", err);
                uni.showToast({ title: err.message, icon: "none" });
            } finally {
                uni.hideLoading();
            }
        },
    },
};
</script>

<style>
.container {
    padding: 40rpx;
}
</style>

场景二：本地路径直接解析

import { parseExcelFile } from "@/uni_modules/lu-parse-excel/js_sdk/excelUtils.js";

// tempFilePath 可以是任意 plus.io 可识别的本地路径，例如：
// _doc/xxx.xlsx、_download/xxx.xlsx、/storage/emulated/0/xxx.xlsx 等
const result = await parseExcelFile("_download/inventory.xlsx");
console.log(result.headers);   // 表头
console.log(result.rawData);  // 原始数据（无字段映射）

场景三：无需字段映射

// 不传 fieldMap，或传 null / {}，data 与 rawData 完全一致
const result = await parseExcelFile(tempFilePath);
console.log(result.data);     // 原始数据

场景四：自定义字段映射示例

const fieldMap = {
    姓名: "name",
    年龄: "age",
    性别: "sex",
    手机号: "phone",
    邮箱: "email",
    地址: "address",
    备注: "remark",
};

映射规则说明：

• key 为 Excel 表头文本；
• value 为自定义字段名；
• 遍历每行时按 row[originKey] 取值并写入 newRow[customKey]，未命中的字段为 ""；
• 不在 fieldMap 中的列会被丢弃，若需保留原始字段请使用 result.rawData。

五、关键注意事项

1. 依赖 xlsx-js-style：实际实现 import 的是 xlsx-js-style，不是原生 xlsx，请按此安装；
2. 运行环境为 H5+ / APP：依赖 plus.io.resolveLocalFileSystemURL 与 plus.io.FileReader，仅支持 APP（Android）端，不适用于 Web、小程序、H5；
3. 仅解析第一个 Sheet：当前实现固定读取 workbook.SheetNames[0]，多 Sheet 文件其余 Sheet 会被忽略；
4. 空单元格兜底：使用 defval: ""，空单元格不会出现 undefined / null，但纯空白字符串与真正的空值无法区分；
5. 在线文件需先下载：必须先通过 uni.downloadFile 把文件下载到本地，得到 tempFilePath 后再调用 parseExcelFile；
6. 文件格式限制：仅解析 .xlsx；.xls / .csv 需自行扩展；
7. fieldMap 缺失列会丢字段：例如 Excel 有 5 列但 fieldMap 只映射 3 列，则 data 中每行仅剩 3 个字段，其余请使用 rawData；
8. uni-app x 兼容性：package.json 仅声明了 uni-app（vue2/vue3）平台，未对 uni-app x 做声明。

六、常见问题排查

1. plus is not defined / resolveLocalFileSystemURL is not a function：当前不在 H5+ / APP 环境，本插件不适用于 Web / 小程序 / H5；
2. 解析结果为空数组：检查 Excel 第一行是否真有表头、是否首 Sheet 为空 Sheet，或文件格式非 .xlsx；
3. 字段全为 ""：确认 fieldMap 的 key 与 Excel 表头完全一致（区分大小写、首尾空格）；
4. 下载失败 downloadFile fail：检查网络、excelUrl 是否可访问、是否需要鉴权头（uni.downloadFile 不支持自定义 header，可在服务端预签名 URL）；
5. XLSX.read 报错：通常是文件损坏或非 xlsx 格式，可先用桌面端 Excel 重新另存为 .xlsx 再上传；
6. iOS 不支持：本插件目前仅在 Android 验证通过。