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

深色模式

快速开始 ​

本节将为您介绍如何通过 WebOffice SDK，实现 WebOffice 文档在您的网页内显示。

注意

本节介绍的内容适用于 JSSDK v1.1.20 及以上版本，旧版的快速开始教程见：旧版教程。

前提条件 ​

  1. 已通过 WebOffice 控制台创建好 WebOffice 应用。
  2. 已按照要求实现回调服务的相关接口，并且在 WebOffice 控制台的回调配置内调试通过。

步骤 1：下载 ​

我们为您提供了多个版本的 JSSDK，建议下载最新版本，以使用我们开发的新功能，下载地址：JSSDK。

步骤 2：引用 ​

在上一步下载的 JSSDK 压缩包中，我们提供了 UMD、AMD、CommonJS、ES6 多种模块化规范的包，根据您的业务前端技术栈选择一个即可，更多的引用方式见其它引用方式。

下面的例子以 UMD 方式引用为例。

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"
    />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>WebOffice</title>
  </head>
  <body>
    <script src="./web-office-sdk-solution.umd.js"></script>
    <script>
      console.log('引入后可以开始使用 jssdk 了！')
      console.log(WebOfficeSDK)
    </script>
  </body>
</html>

步骤 3：初始化 ​

通过 UMD 的形式引入 JSSDK 后，会在全局对象上挂载一个 WebOfficeSDK 对象，我们可以通过该对象提供的 init()函数完成文档的初始化。

使用方式如下：

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>WebOffice</title>
  </head>
  <script src="./web-office-sdk-solution.umd.js"></script>
  <body>
    <script>
      window.onload = () => {
        const instance = WebOfficeSDK.init({
          officeType: WebOfficeSDK.OfficeType.Writer,
          appId: 'xxxxx',
          fileId: 'xxxxx'
        })
      }
    </script>
  </body>
</html>

该初始化函数接收的参数options为一个对象，里面主要包括两个部分的内容：

  • 一部分是初始化参数相关，主要用来完成 WebOffice 文档在业务前端网页的加载。
  • 另一部分是初始化配置相关,用来配置 WebOffice 文档的界面、自定义功能和事件。

初始化参数 ​

参数名必须类型示例值默认值说明
appId
是
string
SX20230206BVNMKZ
/
应用 id,请前往 控制台 查看
officeType
是
string
WebOfficeSDK.OfficeType.Writer
/
文件的类型，请根据 fileId 对应的文件的实际类型去设置，如果两者不匹配的话，文件可能会打开失败或者打开后出现乱码。OfficeType 枚举值参见下表 #OfficeType 枚举值
fileId
是
string
EOCVQPCDCCE4ZJ2X6MTF
/
文件 id，用户自定义
mount
否
string | HTMLElement
#app | document.querySelector(".container")
document.body
该属性为 WebOfficeSDK.config 也支持的属性，为文档 iframe 的挂载节点
token
否
string | tokenData{}
CCSJiXMpPIibHJxDaJPaqMXQ55L9E7Kkb | {"token":"CCSJiXMpPIib","timeout":600000}
/
用于透传业务方系统的 token，将会在回调接口中通过请求头的 X-WebOffice-Token 带回，可通过此 token 进行用户信息识别和文档权限控制，详情见 业务数据请求头，timeout 的单位为毫秒
refreshToken
否
Function
() => new Promise(resolve=> { resolve({token:"xxx",timeout: 10 * 60 * 1000 }) })
/
搭配 token 使用，实现定时刷新，timeout 的单位为毫秒
endpoint
否
string
https://o.wpsgo.com
https://o.wpsgo.com
此选项一般不用配置
customArgs
否
{}
{"user":"张三","number":2658}
/
用户自定义参数，会传递至 WebOffice 服务，WebOffice 服务会解析此参数并通过业务数据请求头的X-User-Query字段透传至接入方服务端回调服务，可根据业务场景进行配置。注意，自定义参数不能使用内部保留字段如：type、version、mode、history_id、share_id等，强烈建议采用业务前缀_参数来命名，例如业务前缀abc，则可以这样定义abc_参数
attrAllow
否
string | string[]
["autoplay","camera *","geolocation https://example.com"]
clipboard-read; clipboard-write;
配置 iframe attribute 的 allow 属性 MDN iframe#attr-allow
isListenResize
否
boolean
false
true
默认跟随浏览器resize事件自动修改容器大小，设置为false时不自动修改容器大小

注意

customArgs中自定义参数不能使用内部保留字段如：type、version、mode、history_id、share_id等，强烈建议开发者采用业务前缀_参数来命名，例如业务前缀abc，则可以这样定义abc_参数，否则有可能影响文档的正常预览。

OfficeType 枚举值

可选项值组件名称
Writer
w
文字
Spreadsheet
s
表格
Presentation
p
演示
Pdf
f
pdf、ofd
Otl
o
智能文档
Dbt
d
多维表格

步骤 4：使用 ​

初始化时，JSSDK 会在配置的节点下挂载一个 iframe 元素，并自动初始化数据和事件。在初始化完成后，函数会返回一个 JSSDK 实例，开发者可通过该实例来进行事件监听和页面定制等操作，也可以通过该实例获取到文档Application实例，您可以查看调用指南了解 API 的更多调用细节。

其它引用方式 ​

文件名模块化规范说明
web-office-sdk-solution.umd.js
UMD
JavaScript 通用模块定义规范
web-office-sdk-solution.cjs.js
CommonJS
CommonJS 规范
web-office-sdk-solution.es.js
ES6
ES6 模块化规范

注意

JSSDK 不包含 Promise Polyfill，所以需要兼容低版本浏览器（例如 IE11）的时候，记得在 JSSDK 引入之前先引入 Promise Polyfill，具体的兼容做法可参考： 兼容性

  1. UMD 规范
html
<script src="web-office-sdk-solution.umd.js"></script>
  1. CommonJS 规范
js
let WebOfficeSDK = require('./web-office-sdk-solution.cjs.js')
  1. AMD 规范
js
define(['./web-office-sdk-solution.umd.js'], function (WebOfficeSDK) {
  // do something...
})
  1. ES6 模块化规范
js
import WebOfficeSDK from './web-office-sdk-solution.es.js'
  1. TypeScript

JSSDK: v1.1.11+ 版本新增

引用了 JSSDK 的项目中如果使用了 TypeScript，需要使用到类型声明文件。

类型声明文件可以依据自身所需版本，到 JSSDK 更新日志 中通过下载后解压缩包获得。

兼容性 ​

在线预览编辑服务兼容浏览器版本如下：

PC 平台支持浏览器版本
Windows
Chrome、IE11
Chrome ≥ 80，IE11（仅预览功能，不保证编辑功能完全兼容）
Mac OSX
Chrome、Safari
Chrome ≥ 80
移动设备支持浏览器版本
iOS
Safari，QQ 内置浏览器，QQ 小程序，微信内置浏览器，微信小程序
iOS ≥ 11
Android
QQ 内置浏览器，QQ 小程序，微信内置浏览器，微信小程序
Android ≥ 7

值得注意的是，在你使用 JSSDK 的时候，如果在低版本浏览器（例如 IE11）中使用 Promise、async...await 等语法，会出现报错。

这边推荐在项目中使用 Webpack + Babel 编译或者直接在 HTML 代码中引用 polyfill：

html
<script src="https://cdn.staticfile.org/babel-core/5.8.35/browser.min.js"></script>
<script src="https://cdn.staticfile.org/babel-core/5.8.35/browser-polyfill.min.js"></script>

<!-- 注意添加 text/babel，否则无法编译 -->
<script type="text/babel">
  // 具体代码
</script>

举个例子：

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"
    />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>兼容低版本浏览器</title>
  </head>

  <body>
    <!-- 引用 babel -->
    <script src="https://cdn.staticfile.org/babel-core/5.8.35/browser.min.js"></script>
    <script src="https://cdn.staticfile.org/babel-core/5.8.35/browser-polyfill.min.js"></script>

    <!-- 引用 JSSDK -->
    <script src="sdk地址"></script>

    <!-- 注意添加 text/babel，否则无法编译 -->
    <script type="text/babel">
      window.onload = function () {
        const jssdk = WebOfficeSDK.init({
          officeType: WebOfficeSDK.OfficeType.Writer,
          appId: 'xxxxx',
          fileId: 'xxxxx'
        })
        const test = async () => {
          await jssdk.ready()
          console.log('api ready')
        }
        jssdk.on('fileOpen', function (data) {
          test()
          console.log('打开成功')
        })
      }
    </script>
  </body>
</html>