WPS WebOffice 开放平台WPS WebOffice 开放平台 | 开发文档

深色模式

文档预览 ​

本节介绍文档预览相关的接口，接入方必须全部实现才能正常打开并预览文档。

获取文件信息 ​

接口：GET /v3/3rd/files/:file_id

说明：该接口用于获取文件的基本信息，在文档打开以及编辑过程中，都需要这些基本信息作为文件的标识与展示，如文档 ID 需要在接入方系统中能唯一标识一份文档。

提示

  1. 遵循「文件ID一致性」原则：接口中文件「请求ID」 和 「返回ID」需保持一致

  2. 文件ID不一致有可能影响某些功能的正常使用

参数：

字段位置必须类型说明
file_id
Path
是
string
文档 ID

返回值：

字段必须类型说明
id
是
string
文档 ID，必须与传入的file_id一致，最大长度 47
name
是
string
文档名称，最大长度 240，不能包含下列特殊字符：\/|":*?<>
version
是
integer
文档版本号，无符号 int32 位，从 1 开始，每次保存后递增，如果已经迭代了多个版本，这里您需要返回最新的版本号
size
是
integer
文档大小，单位 byte
create_time
是
integer
文档创建时间戳，单位纪元秒
modify_time
是
integer
文档最后修改时间戳，单位纪元秒
creator_id
是
string
文档创建者 Id
modifier_id
是
string
文档最后修改者 Id

返回值示例：

json
{
  "code": 0,
  "data": {
    "create_time": 1670218748,
    "creator_id": "404",
    "id": "9",
    "modifier_id": "404",
    "modify_time": 1670328304,
    "name": "统计月报.xlsx",
    "size": 18961,
    "version": 180
  }
}

获取文件下载地址 ​

说明：在线协同系统需要下载文件原件以提供协同服务，该接口需要返回指定文件 ID 所对应的下载地址

接口: GET /v3/3rd/files/:file_id/download

参数：

字段位置必须类型说明
file_id
Path
是
string
文档 Id

返回值:

字段必须类型说明
url
是
string
文档下载地址，该地址需确保外网可访问且排除访问时防火墙的限制
digest
否
string
文档校验和 (checksum)
digest_type
否
string
文档校验和算法 md5 或者 sha1
headers
否
map<string, string>
请求文档下载地址所需要的额外请求头，例如某些云存储商会要求额外的签名头等

返回值示例：

json
{
  "code": 0,
  "data": {
    "url": "https://foo.bar.com/files/9/180"
  }
}

提示

下载地址设置了Referer防盗链时，需要在返回值headers返回自定义Referer请求头。

文档用户权限 ​

说明：任何需要用户鉴权的行为都会触发该接口的调用，并且 WebOffice 会根据指定的权限位来限定特定的操作，如 download 指定该用户是否具有下载文档权限。 此接口用于标识用户具备哪些操作权限，具体的功能支持还需您的服务实现相关回调。

注意

开发者务必了解下列描述中的规则，减少您在开发过程中的疑问。

  • 当 update=1时必须返回当前用户的 user_id，并且需要实现用户信息、文档编辑 接口，控制台中打开对应的回调接口开关

  • 当 print=1时必须返回当前用户的 user_id，并且需要实现用户信息接口，控制台中打开对应的回调接口开关

  • 当 rename=1 时需要实现 文档重命名 接口

  • 当 history=1 时需要实现 历史版本相关接口 接口。

    请注意 history 是用来控制：是否可见预览历史版本入口。 入口如下图： 历史版本预览

    如果要控制右上角 历史版本入口的显隐，或者禁用。

    有2种方式供您参考：

    1. 到控制台，应用管理-app-文档配置-历史版本-只读模式下是否允许打开历史记录 和 协作记录 打开开关
    2. JSSDK 代码纯前端控制（支持禁用和隐藏）。更多的类似的入口控制可参考自定义配置项
    js
    WebOfficeSDK.init({
  fileId: 'xxx',
  officeType: 'w',
  appId: 'xxx',
  commandBars: [
    {
      cmbId: 'HeaderHistoryMenuBtn',
      attributes: {
        visible: false,
        enable: false
      }
    }
  ]
})

  • 当comment = 1。 需要注意：

    1. WebOffice默认评论也属于文档的一部分，所以当 read=1 , update=0 的只读模式下，comment=1 无法控制评论可用。
    2. 如若您的业务需要只读评论，请到 控制台，应用管理-app-文档配置-筛选对应组件分类-评论功能-是否只读权限下可评论 打开开关

  • 当comment = 0。需要注意:

    1. WebOffice默认评论也属于文档的一部分，所以当 update=1 的编辑模式下，comment=0 无法控制评论禁用。
    2. 如若您的业务需要禁用评论功能，请到 控制台，应用管理-app-文档配置-筛选对应组件分类-评论功能-是否禁用评论功能 打开开关

接口: GET /v3/3rd/files/:file_id/permission

参数：

字段位置必须类型说明
file_id
Path
是
string
文档 Id

返回值：

字段必须类型说明
user_id
否
string
当前用户 Id，当 update=1；print=1时必须返回当前用户的 user_id
read
否
integer
是否具有预览权限，0-无 1-有
update
否
integer
是否具有编辑权限，0-无 1-有
download
否
integer
是否具有下载文档权限，0-无 1-有
rename
否
integer
是否具有重命名文档权限，0-无 1-有
history
否
integer
是否具有查看文档历史记录权限，0-无 1-有
copy
否
integer
是否具有拷贝文档内容权限，0-无 1-有
print
否
integer
是否具有打印文档权限，0-无 1-有
saveas
否
integer
是否具有另存当前文档权限，0-无 1-有。该属性现阶段暂无相关入口，开发者可不用关注
comment
否
integer
是否具有评论文档权限，0-无 1-有。

返回值示例：

json
{
  "code": 0,
  "data": {
    "comment": 1,
    "copy": 1,
    "download": 1,
    "history": 1,
    "print": 1,
    "read": 1,
    "rename": 1,
    "saveas": 1,
    "update": 1,
    "user_id": "404"
  }
}

提示

关于权限接口，还有几个常见JSSDK调用失败，和permission接口相关的问题。

  1. JSSDK调用 ExportAsFixedFormat 导出的时候，提示类似"permission denied"，或者network中看到/export 接口提示"permission denied" ?

    答：导出图片，至少需要 read=1 和download=1 ，permission需要返回user_id, 并且通过 /v3/3rd/users 能查到该用户

  2. JSSDK调用 GetHtmlData 获取文档html数据，控制台提示 Cannot create property 'message’ on string 'permission denied' ?

    答：获取文档内的数据，需要开启copy=1权限

  3. 格式刷功能失效 ?

    答：格式刷功能依赖剪切板，需要开启copy=1复制权限