服务端回调常见问题

WebOffice 会不会保存接入方的文件？

WebOffice 不会保存接入方的文件，每次新打开的文件都会通过接入方的回调服务获取文件的下载地址。

如何通过 WebOffice 新建文件，或者基于某个文件模板新建文件？

WebOffice 不托管文件系统，只负责文档的在线预览和编辑。新建文件或者基于模板新建文件的操作均需要您在自己的业务系统内完成。

如何理解文档的版本？

通过 WebOffice SDK 打开文档时，WebOffice 服务将会根据文档 ID 和版本号定位到唯一的文档对象，所以文档的版本号，每次保存后都需要递增，以匹配一个新的文件实体，完成正常编辑流。

综上所述，在获取文件信息接口中，您必须返回当前文件 ID 最新的版本号，以保证用户打开的文档是最新的版本。而在扩展能力的历史版本接口中，则需要根据文件 ID 和不同的版本号获取到不同版本的文档信息。

已实现接口但仍无法编辑文档？

一些用户在服务端实现本接口后，发现打开文档后仍然为只读模式。在这里我们特别说明下，对于文档编辑来说，该接口的实现是必要条件，但并不是唯一条件，如果要以编辑模式打开文档，请检查下您是否已完成如下四点：

• 实现本节所述的文件上传接口，单阶段提交或三阶段保存任选其一
• 在 WebOffice 控制台【应用管理】-【回调配置】内的此项接口配置为已开启，点击右侧的接口【调试】能验证通过
• 由于文件的编辑保存需要使用到用户信息，所以您需要同时实现获取用户信息的接口，和上一步一样，确保该接口在 WebOffice 控制台内已开启并调试通过
• 实现文档用户权限接口，确保返回值的update字段为 1，而且返回当前用户的user_id

触发回调服务save接口(文件存盘)的时机有哪些？

并不是用户的每次编辑操作都会触发存盘，WebOffice 内部有一套机制专门处理此类情况：

1. 当用户主动触发保存，例如通过键盘Ctrl + S、通过 SDK 的save方法，都可以触发一次存盘。
2. 用户主动关闭文档也会触发一次存盘操作。
3. WebOffice每5秒触发一次检查，判断的逻辑为最近一次保存时间和最后一次编辑时间，最近一次编辑时间距离现在超过一分钟并且最近一次保存时间距离现在超过一分钟，触发文档存盘。
4. 当所有用户关闭文档，编辑会话并不会立即退出，WebOffice 会在五分钟后将会话销毁。

接入方实现的回调接口通过 postman 等工具调试成功，但是使用我们的 WebOffice 控制台调试失败

出现这种情况可能是您的网络受到了限制，解决方案：

• 对接方实现的回调接口必须部署在公网。（需要保证能被 WPS WebOffice 服务器访问到）
• 目标公司属于内网需要配置对应的出口IP 地址 Solution 回调服务出口IP
• 该问题和对接方 ssl 证书有关，可以用这个网站可以检查下 （https://www.digicert.com/help/）

文档打开失败，接口返回 ApplnfoNotExists

出现该问题是因为系统查询不到您的 APPID，解决方案：

• 请检查 AppID 是否正确
• 是否实现了网关和预览接口
• 接口回调返回格式是否正确
• Web 服务框架使用不当

前端设置 token 以后，服务端获取不到，报错 GetTokenTimeout

{"errno":10000,"msg":"","reason":"","result":"ApplnfoNotExists"} 出现这种问题可能是由于 token 没有成功传入我们的系统中或者获取方式有误，解决方案：

1. 检查前端有没有调用 setToken 方法，以及 setToken 方法传递的参数格式是否正确
2. 检查 WebOffice 前端 XHR 请求是否携带 X-WebOffice-Token 请求头字段
3. 无痕模式对 cookie 存储有限制，鉴权 token 存不了。只有当 iframe 内外同源（相同域名、IP、端口）时，无痕模式才可以存储 cookie，此时鉴权机制可以正常工作
4. 服务端获取方式是否是 request.getHeader("X-WebOffice-Token")

用户名或图像显示异常

出现这种原因可能是您的回调接口返回的数据有误，解决方案：

• 如果协作记录/评论等位置的用户名、头像显示异常，则需检查 users 回调接口是否返回了正确数据，JSON 数据中的 name 和 avatar_url 字段是否正确
• WPS WebOffice 会 POST 传递所有 userid 给业务方 users 接口，进行批量获取用户的信息，对接方需确保该接口返回的所有 userid 的信息

如何导出源文件？

由于安全原因，WebOffice 暂未开放导出源文件功能（即下载源文件）。

建议：用户可以自己实现一个后端业务接口，通过 fileId 查询到 download_url，前端拿到 download_url 后通过 window.open 下载源文件。可以在 WebOffice 中添加一个自定义按钮，也可在 WebOffice 外面的业务层自行添加下载按钮。

注意

window.open(download_url) // 用 window.open，不要用 location.href，因为后者会改变当前页面 url，本质上已经离开当前页面了，所以后续 API 和请求都会报错

如何切换文档的只读/编辑权限？

可以通过以下几种方式，切换文档的只读/编辑权限：

1. 设置回调接口 /v3/3rd/files/:file_id/permission 的data.read 为 1 ，data.update 为 0，具体可参考文档用户权限
2. 通过 JSAPI ActiveDocument.SetReadOnly() 将打开的文档临时设置为只读（目前仅文字支持该 JSAPI，其他组件暂不支持），具体可参考SetReadOnly()
3. 文档预览 url 后面拼接 ?readonly 参数

注意

上述三种方法中只有通过方法一回调接口返回设置的只读文档，支持返回comment为1时在控制台-文档配置中配置只读可评论权限，具体可参考文档用户权限；后面两种设置只读方法一般适用于前端快速切换只读预览模式，不支持再单独配置评论权限。

移动端兼容性适配问题

问题描述：在移动端使用 WebOffice 时，如果未进行移动端适配，内嵌的 iframe 可能会表现异常，例如：

• 文字、图标、工具栏等部件显示偏小，双击后界面放大
• 顶部的刘海、底部的小黑条展示异常（WOA 新建体验优化反馈）
• 文字组件编辑、缩放时，出现“字体重影”现象（文档中台 广东省财政厅 反馈）
• 表格组件缩放时，显示比例异常（私有化 阿里 IMM 反馈）

出现上述问题，您可以在 HTML head 部分添加以下代码即可解决，目的是让页面做移动端适配

<meta
  name="viewport"
  content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
/>

错误码 15008，接口报“Unavailable”错误

打开文档后显示“你的操作权限不足”，“For input string:”接口报“Unavailable”，错误码为 15008

Unavailable 的原因是由于您回调接口GET /v3/3rd/files/:file_id/download中提供了一个访问超时的 download url，解决方案：请替换成可访问的地址，同时检查下 download url 响应服务器是否存在防火墙等限制。

docx 格式的文件提示为 TXT 格式

当您出现文件名为 xxx.docx，但 WebOffice 文档提示当前文档为 TXT 格式，仅能保存文档内容，很有可能是您的文件名后缀和实际文件格式不匹配，因为文件名不代表文件的真实格式，请确认返回的下载地址的文件的实际格式。

文档手动 ctrl+s 保存，提示内部错误保存失败 err_code 10000

当您的文件自动保存是正常的，但是手动 ctrl+s 保存显示内部错误，错误码 10000，显示的数据无异常

出现该问题的原因可能是文件编辑回调接口没有按照要求返回数据，比如字段类型不一致，或者字段名不一致。

返回的文件信息数据要求请参考下表：

字段	必须	类型	说明
id	是	string	文档 ID，必须与传入的file_id一致
name	是	string	文档名称
version	是	integer	文档版本号，从 1 开始，每次保存后递增
size	是	integer	文档大小，单位 byte
create_time	是	integer	文档创建时间戳，单位纪元秒
modify_time	是	integer	文档最后修改时间戳，单位纪元秒
creator_id	是	string	文档创建者 Id
modifier_id	是	string	文档最后修改者 Id