自定义文件传输面板，解决将文件从邮件、OA等系统中拉取文件上传到云文档过程中，传输进度无法跟踪的问题

定制导致文档上传逻辑改变，传输面板无法正常唤起，怎么办？

本定制方案仅适用于私有化WPS365版本

1. 方案概述

用户上传文件时，文档中心页面会出现一个显示“文件上传进度”的面板，这就是传输面板。

上传文件时	这里会显示上传进度，这就是“传输面板”

当企业在WPS文档中心上做了某些定制能力，可能导致WPS文档中心原有的上传逻辑被改变，影响传输面板的正常唤起，使得企业用户上传文件时，无从得知“文件还有多久传完”“是否成功上传”，也无法取消＼暂停文件上传。

已知哪些定制能力，会导致传输面板无法正常唤起？

已知哪些定制能力，会导致传输面板无法正常唤起？ ①安全扫描，在企业用户上传文件时进行病毒、关键词等安全扫描 ②文档安全等级对比，自动对比“上传文件”和“目的地文件夹”的安全等级是否一致

定制化解决方案

针对这类问题，我们可以使用文档中心Web端的开放能力，重新定制一个传输面板：

实现效果	即使企业的定制打断了文档中心正常上传逻辑，完成传输面板定制后，仍可唤起传输面板。
涉及接口	请求文件上传信息上传实体文件提交文件上传完
依赖版本	版本24-11a（含）以上
依赖操作系统	支持X86、XC
备注	仅支持定制文档中心Web端（PC端）的传输面板，不支持定制H5端（移动端）的传输面板。但用户仍可用手机正常上传文件，只是不会唤起传输面板。

2. 使用指南

👉依赖能力

• 前端埋点

功能	埋点	适用版本	是否支持多插件	是否支持异步
拖拽拦截	sdk.kdrive.upload.onDragInterecpt	23-08b	是	是
按钮统一点击拦截	sdk.kdrive.uploadButton.onClick	24-02b	是	是
头部右侧图标管理	sdk.kdrive.header.rightPanel.uploadIcon	23-10b	/	/
历史版本屏蔽上传	sdk.commonComponents.historyVersion	24-01a	/	/

• 后端接口

📌 注意

365网关接口：!365网关接口

graph（o）网关接口：!365网关接口

功能	URL	适用版本	备注
请求文件上传信息	/openapi+/v7/drives/{drive_id}/files/{parent_id}/request_upload	24-11a	接口详细介绍
上传实体文件	请求文件上传信息返回值中获取	/	接口详细介绍
提交文件上传完成	/openapi+/v7/drives/{drive_id}/files/{parent_id}/commit_upload	24-11a	接口详细介绍

👉实现步骤

💡 原因

目前拦截上传前后两个阶段做定制处理时，会造成云文档文件上传逻辑阻断，需重新实现一套文件选择->文件上传->结果展示的组件逻辑。

1. 屏蔽原有逻辑

因需重新实现云文档上传的传输面板，需对原有传输面板进行屏蔽处理，因未提供传输面板本身的屏蔽功能埋点，故需要对触发云文档原有上传逻辑的情况进行拦截，避免触发云文档提供的传输面板。

1.1 屏蔽头部工具栏入口

首先对头部工具栏入口进行屏蔽，使用sdk上的hide方法对于具有data-eciskey属性的dom节点进行隐藏。

需要隐藏位置

sdk.kdrive.header.rightPanel.uploadIcon.hide();

1.2 拦截上传按钮功能

当前版本中含有多种上传文件(夹)按钮的入口，在202402B版本后，可以使用UploadButton埋点一次全部拦截。

文件列表右上方	左侧导航栏	团队无文档时	空白位置右键

sdk.kdrive.uploadButton.onClick((data) => {
  // 使用data进行定制操作
  // true时拦截原本逻辑，false时会正常调用
  return true;
});

1.3 拖拽上传拦截

可以使用upload.onDragInterecpt埋点对拖拽上传进行拦截

sdk.kdrive.upload.onDragInterecpt((data)=>{
  // 使用data进行定制操作
  // true时拦截原本逻辑，false时会正常调用
  return true
})

1.4 历史版本上传

该逻辑不会调用原有传输面板逻辑，可根据自身需求决定是否拦截。

sdk.commonComponents.historyVersion.onMounted((data) => {
    data.ecisConfig.showUploadButton = false;
})

文件选择逻辑

💡

由于拦截入口后，云文档上传文件逻辑被截断，需要从上传文件开始重新实现。

可使用原生input框进行实现，根据点击情况来判断文件选择器是否支持多文件、文件夹选择等，逻辑较为简单，不再详细介绍。

文件上传逻辑

📌 提示

这里以小文件上传三步走为例，大文件分块上传监听进度原理大致相同，可自行设计实现。

3.1 文件请求上传(第一步)

使用request_upload或其对应封装接口即可，无特别注意事项，如有文件名冲突，跳过检查权限等需求可自行修改请求参数。

返回值中包含有上传第二步中请求的minio的请求地址

3.2 文件传输(第二步)

使用xhr发送请求，并实现实时监听上传进度和上传情况并展示即可

xhr.upload.onprogress = function (e) {
  if (e.lengthComputable) {
    const percentComplete = Math.ceil((e.loaded / e.total) * 100);
    updateTask({ ...task, status: "uploading", progress: percentComplete });
  }
};

xhr.upload.onload = function (e) {
  updateTask({ ...task, status: "uploading", progress: 100 });
};

3.3 文件提交上传(第三步)

使用commit_upload或其对应封装接口即可，info_token参数需要从第二步请求的响应头中获取，如有文件名冲突，跳过检查权限等需求可自行修改请求参数。

返回值中文件相关参数可进行后续优化体验操作时参数。

面板展示逻辑

使用状态管理，当选择文件后展示面板，点击非面板内部时关闭面板即可。如想展示更多内容，可使用获取文件信息接口获取上传后文件的详细内容进行展示。

由于模板库添加位置亦为头部slot埋点，如需添加头部工具栏入口且启用模板库时需注意样式。

📌 提示

这里仅以使用上传按钮选择单独小文件上传时唤出自定义传输面板为例，对于具体情况如重名等问题未进行处理，其余多文件、大文件、拖拽上传等情景原理相似，可自行设计实现，上传后刷新，css样式等优化体验内容未实现，可自行实现。

效果：