更新记录

v1.1.0（2026-04-22） 下载此版本

更新动态配置token，和请求头header

v1.0.0（2026-04-22） 下载此版本

版本

平台兼容性

uni-app(3.8.0)

xianglei-excelupload 使用说明

面向 uni-app 的 Android App 端 Excel（.xls / .xlsx）选择与安全上传：通过系统文档选择器（SAF）选取文件，将 content:// 拷贝到应用沙箱后，使用 uni.uploadFile 上传到你的业务接口。

本包为 JavaScript SDK（dcloudext.type: sdk-js），通过 plus.android 调用 Android API，不是 UTS 原生插件。

一、环境要求

不支持：H5、iOS App 上调用选表上传主流程（源码中会做平台判断并提示）。小程序等其它端请自行评估，勿依赖本插件的选文件能力。

老项目若为 uni-app 2.x，不保证以 uni_modules 开箱即用；可将 js_sdk/excel-uploader 拷入工程 common 等目录后自行联调。

二、安装与引入

1. 将本插件置于宿主工程目录：uni_modules/xianglei-excelupload/（文件夹名须与 package.json 的 id 一致）。
2. 在页面或逻辑中引入：

import { pickAndUploadExcel, pickExcel, uploadExcel } from '@/uni_modules/xianglei-excelupload';
// 或默认导出（同上三个方法）
// import sdk from '@/uni_modules/xianglei-excelupload';

3. 可选 UI 组件 xianglei-excel-upload-bar：依赖宿主 easycom 能解析 uni_modules 组件；若不能，请在页面中 显式 import 并注册组件。

三、快速开始（完整：选文件 + 上传）

仅在 Android App 真机/模拟器上测试。

import { pickAndUploadExcel } from '@/uni_modules/xianglei-excelupload';

export default {
  methods: {
    onImportExcel() {
      pickAndUploadExcel({
        uploadUrl: 'https://你的域名/api/import',
        maxSizeMB: 20,
        fieldName: 'file', // 与后端 multipart 字段名一致
        withAuthToken: true,
        // 动态 token：在此函数内按项目改写（vuex、多 key、Bearer 前缀等）；未传 getAuthToken 时才会用 authTokenStorageKey / 默认 'token'
        getAuthToken: () => uni.getStorageSync('token') || '',
        // 若只需改本地存储的 key，可删除上一行 getAuthToken，改用：authTokenStorageKey: 'access_token',
        // 动态 header（可选）：按端/后端要求组装 uni.uploadFile 的 header；入参见 5.2 节
        // getUploadHeaders: ({ token, base }) => ({ ...base, 'X-Requested-With': 'XMLHttpRequest' }),
        onSuccess: (data, res) => {
          // data：解析后的响应体；res：uni.uploadFile 原始 success 参数
          console.log('业务成功', data);
        },
        onFail: (err) => {
          console.error(err);
        }
      });
    }
  }
};

配合可选上传条（仅样式 + 点击事件，上传逻辑仍由你调用 pickAndUploadExcel）：

<template>
  <xianglei-excel-upload-bar @click="onImportExcel" />
</template>

<script>
import { pickAndUploadExcel } from '@/uni_modules/xianglei-excelupload';

export default {
  methods: {
    onImportExcel() {
      pickAndUploadExcel({
        uploadUrl: 'https://你的域名/api/import',
        getAuthToken: () => uni.getStorageSync('token') || '',
        // 需要与其它端统一 header 时再写；见 5.2
        // getUploadHeaders: ({ token, base }) => Object.assign({}, base, { 'X-App': 'uni-app' })
      });
    }
  }
};
</script>

组件 props：

四、API 说明

4.1 pickAndUploadExcel(options)

作用：打开系统文档选择器 → 校验扩展名与大小 → 将 content:// 拷贝到本地 → uni.uploadFile 上传。

返回：Promise。成功时 resolve 的对象形如 { ok: true|false, data, raw, message? }（业务“成功/失败”以 ok 与后端约定为准，见下文）；平台不支持、缺少 uploadUrl、用户取消等会 reject 或在 catch 中处理。

必填：uploadUrl。

与上传请求相关的 options 主要包括：fieldName、withAuthToken、authTokenStorageKey、getAuthToken、extraHeaders、getUploadHeaders（自定义最终 uni.uploadFile 的 header，详见 5.1 / 5.2）。

4.2 pickExcel(options)

作用：仅选文件并完成本地拷贝与校验，不上传。

返回：Promise，resolve 为 { path, name, size }（本地绝对路径、展示文件名、字节大小，具体以运行时为准）。

无需 uploadUrl。

4.3 uploadExcel(filePath, fileName, options)

作用：对已有本地路径发起上传（需已落在可读的本地文件路径上）。

必填：uploadUrl。

上传阶段的 header 与 pickAndUploadExcel 使用同一套 options 规则（含 getUploadHeaders），见 5.1 / 5.2。

五、options 参数一览

与 DEFAULT_OPTIONS 合并，未传则使用下列默认。与 uni.uploadFile 相关的字段主要为：uploadUrl、fieldName、header 的生成逻辑（下表及 5.1、5.2）。

5.1 鉴权 Token 说明

• 推荐：在业务代码里显式写 getAuthToken（与第三节「快速开始」一致），token 来源集中在一处，便于按项目改写。
• 默认：withAuthToken: true 且未配置 getAuthToken 时，等价于以前的行为：uni.getStorageSync('token') 取不到则空字符串。
• 只改存储 key：设置 authTokenStorageKey: 'access_token'（示例）即可。
• 完全自定义：传入 getAuthToken，例如从 Vuex、多字段拼接、Bearer 前缀等；函数在发起 uni.uploadFile 时同步调用，若 token 需异步获取，请在调用 pickAndUploadExcel / uploadExcel 之前先准备好并在闭包或模块变量中可读。
• 不传 token：设 withAuthToken: false，或自行用 extraHeaders 覆盖/补充（注意勿设置 Content-Type）。

示例：

pickAndUploadExcel({
  uploadUrl: 'https://你的域名/api/import',
  authTokenStorageKey: 'jwt'
});

pickAndUploadExcel({
  uploadUrl: 'https://你的域名/api/import',
  getAuthToken: () => {
    const u = uni.getStorageSync('userInfo');
    return (u && u.token) ? String(u.token) : '';
  }
});

5.2 上传请求头 header（getUploadHeaders）

不同端或网关对 uni.uploadFile 的 header 字段名、大小写、是否带 Bearer、是否必须带某业务头等要求可能不同。插件会先按当前选项拼好 base（顺序为：withAuthToken → 写入 Authorization 与 Annotoken；再 Object 合并 extraHeaders）。若配置了 getUploadHeaders，则在其内收到 { opts, token, base }，并用其返回值作为传给 uni.uploadFile 的 header 最终值（不再自动与 base 二次合并；若你要保留默认头，请在回调里自行合并 base）。

• 签名：getUploadHeaders({ opts, token, base }) => object
  • opts：本次调用合并后的完整 options。
  • token：已解析的字符串（withAuthToken 为 false 时一般为 ''）。
  • base：默认合并结果的浅拷贝，可在其上增删后返回；也可完全忽略，自行返回新对象。
• 返回值：须为普通对象（非 null、非数组）；若返回无效或抛错，则回退使用插件默认的 base（与未配置 getUploadHeaders 时一致）。
• 禁止在 header 里设置 Content-Type，否则会破坏 multipart 边界，导致上传失败。

示例（在默认头基础上追加字段）：

pickAndUploadExcel({
  uploadUrl: 'https://你的域名/api/import',
  getAuthToken: () => uni.getStorageSync('token') || '',
  getUploadHeaders: ({ token, base }) => ({
    ...base,
    'X-App-Platform': 'android',
    'X-Requested-With': 'XMLHttpRequest'
  })
});

若构建目标为 Vue2 / 较老 JS，不支持对象展开运算符，可改为：

getUploadHeaders: ({ base }) =>
  Object.assign({}, base, {
    'X-App-Platform': 'android',
    'X-Requested-With': 'XMLHttpRequest'
  })

完全自定义（不沿用 base 里的 Authorization / Annotoken）时，在 getUploadHeaders 内自行组装返回对象即可；token 参数仍可供你拼 Bearer 等格式。

六、与后端约定的“成功”判断

插件在 uni.uploadFile 的 success 里将 res.data 尝试 JSON.parse 后，按下述逻辑判断是否为业务成功（isOk）：

• HTTP statusCode === 200
• 且解析后的 data 存在
• 且满足 data.code === 200 或 data.code === 0 或 data.success 为真

满足则 resolve({ ok: true, data, raw })，否则 resolve({ ok: false, ... }) 并可能弹出错误提示。

若你的后端字段不同，请 fork 本插件 修改 doUploadExcel 中的判断逻辑，或自行封装一层只使用 pickExcel + 自定义上传。

七、权限与隐私说明（摘要）

• 使用系统文档选择器读取用户已选择的文件；插件说明见 package.json → dcloudext.declaration。
• 网络访问随宿主工程配置，用于 uploadFile。
• Token 与上传请求头见 第五节（withAuthToken、authTokenStorageKey、getAuthToken、extraHeaders、getUploadHeaders），请与后端鉴权字段、前缀（如 Bearer）及各端约定一致。

八、插件 ID 与 fork 注意（上架 / 发 ZIP）

• package.json 的 id 与 目录名 必须一致，并符合 DCloud 规范：作者ID-插件英文名（仅英数字，勿用保留关键字）。
• 若 fork 改名，请同步修改：目录名、package.json#id、文档与代码中的 @/uni_modules/新id、以及 easycom 依赖的组件路径/标签名。

发 ZIP / 付费插件：只打包 uni_modules/你的插件id/ 这一目录，勿包含 unpackage、node_modules、.git 等。

样式：示例组件使用 @import '@/uni.scss'，依赖宿主提供 uni.scss 变量（与官方 uni-app 模板一致）。

九、常见问题

1. 点击无反应或提示不支持
   确认运行在 Android App，且非 H5 / iOS 依赖本流程。

2. 后端收不到文件
   核对 fieldName 与后端 multipart 字段名；Header 勿手动覆盖 Content-Type。

3. 一直提示导入失败
   对照第六节，检查后端返回的 HTTP 状态码与 JSON 中的 code / success 是否与插件约定一致。

4. 拷贝大文件很慢
   大文件从 content:// 拷贝到沙箱可能耗时数秒至更久，属正常现象；可适当关闭 debug 减少日志。

5. Header 里没有 token 或仍是旧 key
   检查是否配置了 getAuthToken / authTokenStorageKey；withAuthToken 是否为 true。

6. 自定义了 getUploadHeaders 后鉴权头丢失
   返回值必须是包含你所需字段的完整对象；若仍需要插件默认的 Authorization / Annotoken，请基于入参 base 合并后再返回（见 5.2）。若回调抛错或返回非对象，插件会回退为未配置 getUploadHeaders 时的默认 base。

十、导出清单（入口文件）

@/uni_modules/xianglei-excelupload 与 js_sdk/excel-uploader/index.js 对齐，导出：

• 命名导出：pickAndUploadExcel、pickExcel、uploadExcel
• 默认导出：上述三方法组成的对象

详细实现与注释见：js_sdk/excel-uploader/index.js。