快速开始

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

注意

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

前提条件

已通过 WebOffice 控制台创建好 WebOffice 应用。
已按照要求实现回调服务的相关接口，并且在 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等，建议可以采用`业务前缀_参数`来命名，比如业务前缀abc，则可以这样定义`abc_type`
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时不自动修改容器大小

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，具体的兼容做法可参考：兼容性

UMD 规范

html

<script src="web-office-sdk-solution.umd.js"></script>

CommonJS 规范

let WebOfficeSDK = require('./web-office-sdk-solution.cjs.js')

AMD 规范

define(['./web-office-sdk-solution.umd.js'], function (WebOfficeSDK) {
  // do something...
})

ES6 模块化规范

import WebOfficeSDK from './web-office-sdk-solution.es.js'

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>

快速开始 #

前提条件 #

步骤 1：下载 #

步骤 2：引用 #

步骤 3：初始化 #

初始化参数 #

步骤 4：使用 #

其它引用方式 #

兼容性 #

快速开始

前提条件

步骤 1：下载

步骤 2：引用

步骤 3：初始化

初始化参数

步骤 4：使用

其它引用方式

兼容性