SDK使用说明

使用须知

文档中台前端sdk（后文简称OpenSDK）是文档中台向网页开发者提供的网页开发工具包，是整合了WebOffice SDK和原预览SDK而成的，网页开发者可以通过OpenSDK实现页面的预览和编辑能力，同时可以直接使用高级API来操作文档。

OPENSDK版本号定义：

遵循 0.0.1 这种 X.Y.Z 格式，分别代表：

X：主版本号。当 API 的兼容性变化时，X 会变化。
Y：次版本号。当增加功能时，Y 会变化。
Z：修订号。当 Bug 修复时，Z 会变化。

SDK下载

在使用之前，请先下载最新版本的OpenSDK代码。见SDK下载

SDK引用

OpenSDK提供了支持非模块化以及AMD、CommonJS、ES6多种模块化规范的包，下面以非模块化方式引用为例，讲解OpenSDK的快速上手。

注意：暂不支持在同一个页面中使用该"sdk"加载多个预览编辑链接，如果有此需求，请在该页面创建多个iframe，在每个iframe内部使用"sdk"加载一个预览编辑链接，以此实现window层的隔离

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>OpenSDK</title>
  </head>
  <body>
    <div
      id="office"
      style="display: block; margin-top: 15px; width: 100%; height: 600px"
    ></div>
    <script src="./open-jssdk-v0.0.3.umd.js"></script>

    <script>
      console.log("引入后可以开始使用 OpenSDK 了！");
      console.log(OpenSDK);
    </script>
  </body>
</html>

在上面示例代码中，我们在HTML代码中引用了OpenSDK：

html

<script src="./open-jssdk-v0.0.3.umd.js"></script>

初始化

引用之后，就可以通过初始化配置，让OpenSDK在配置的挂载节点下创建一个iframe，并自动初始化相关数据和事件

挂载节点指OpenSDK插入iframe时挂载的节点

javascript

window.onload = function () {
    const instance = OpenSDK.config({
      url: "在线文档预览地址",
      mount: document.querySelector("#office"),
    });
    console.log("instance:", instance);
};

由于 iframe 限制，所以需要给挂载的节点指定具体宽高

token鉴权

使用OpenSDK传递token进行鉴权与初始化操作基本一致，只是在“在线文档预览地址的url”参数中设置 _w_tokentype=1（注意，这个参数也是需要参与签名的）

javascript

window.onload = function () {
    const instance = OpenSDK.config({
      url: "在线文档预览地址" + "&_w_tokentype=1",
      mount: document.querySelector("#office"),
    });
    // 设置 token
    instance.setToken({
        token: "d00e9d236f221bbb642cf2261550c992", // 根据自身的业务需求，通过异步请求或者模板输出的方式，取得 token
        timeout: 10 * 60 * 1000, // token 超时时间，可配合 refreshToken 配置函数使用，在超时前自动调用 refreshToken 重新刷新 token
    });
};

WebofficeSDK实例

如果预览链接是weboffice的四大组件格式（文字，表格，演示，PDF）,可以通过获取到的实例（instance对象）直接调用WebofficeSDK的api

javascript

await instance.ready();
const app = instance.Application;
// 获取总页数
const totalPages = await app.ActiveDocument.Range.Information(
    app.Enum.WdInformation.wdNumberOfPagesInDocument
);
console.log("总页数为：", totalPages);

前端对接OpenSDK api说明

初始化获取jssdk实例（获取jssdk实例后可调用wo jssdk的api，见https://solution.wps.cn/docs/web/quick-start.html）

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});

打印功能

打印功能仅支持文档中台组件版≥v7.1.2304.20230419 & OpenSDK≥0.0.7

1. web-office-sdk打印与极速预览打印

打印范围:

预览类型为四大组件(word,ppt,pdf,excel)预览,或者为极速预览附: （缓存预览不支持打印）

javascript

await jssdk.ready();
const app = jssdk.Application;
// 执行打印指令1
await app.CommandBars("TabPrintPreview").Execute();
// 执行打印指令2
// await outJssdk.executeCommandBar("TabPrintPreview");

2. 非四大组件与兼容层链接打印

打印范围:

非四大组件预览: 图片,代码,邮件,markdown等,与兼容层链接(即预览链接开头是micsweb,但是展示的是四大组件预览的链接)

javascript

jssdk.print()

下载功能

非四大组件与兼容层链接下载

下载范围:

非四大组件预览: 图片,代码,邮件,markdown等,与兼容层链接(即预览链接开头是micsweb,但是展示的是四大组件预览的链接)

javascript

jssdk.download()

OpenSDK-0.1.0 使用说明

为了统一外部使用 api 的方式，对使用者提供标准规范，OpenSDK-0.1.0版本新增了标准对外的一些API，抹平标准规范与三方业务 api 差异。后续三方格式预览均按该方式来对接、适配。

1. OpenSDK实例

javascript

this.instance = {
      setToken: this.setToken.bind(this),
      print: this.openDocPrint.bind(this),
      download: this.openDocDownload.bind(this),
      ApiEvent: {
        AddApiEventListener: this.addApiEventListener.bind(this),
        RemoveApiEventListener: this.removeApiEventListener.bind(this),
      },
      ready: () => {}, // todo await instance.ready();
      tabs: {
        getTabs: () => {}, // todo const tabs = await instance.tabs.getTabs()
        switchTab: () => {}, // todo await instance.tabs.switchTab({ tabKey: 'InsertTab' }) // 切换到【插入】Tab
      },
      save: () => {}, // todo const result = await instance.save()
      destroy: () => {}, // todo instance.destroy()
      iframe: iframe,

     };

2. API说明

1. ready （初始化）

openSdk： v0.1.0+

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()

2. print （非四大组件及兼容层链接打印）

openSdk： v0.1.0+

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()
// 打印
jssdk.print()

3.download （非四大组件及兼容层链接下载、导出）

openSdk： v0.1.0+ 目前仅processon流程图、脑图预览、编辑链接支持download方法

参数	参数类型	是否必填	说明
type	string	否	要导出的文件类型注：目前只有processon类型的预览、编辑支持传入type，可将po流程图、脑图转换为不同类型的文件。type具体值可见下表：

文档类型	导出文件类型(type)	备注
流程图	png	单页（导出当前画布为png）
	jpg	单页（导出当前画布为jpg）
	svg	单页（导出当前画布为svg）
	visio	单页（导出当前画布为visio vsdx格式）
	visioall	多页（导出全部画布为visio vsdx格式）
	pdf	单页（导出当前画布为pdf格式）
	pdfall	多页（导出所有画布为pdf格式）
思维导图	png	单页（导出当前画布为png）
	jpg	单页（导出当前画布为jpg）
	svg	单页（导出当前画布为svg）
	pdf	单页（导出当前画布为pdf格式）
	pdfall	多页（导出全部画布为pdf格式）

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()
// 将流程图、脑图导出为PDF文件
jssdk.download({type: "pdf"})

4. ApiEvent事件监听

openSdk： v0.1.0+ 目前仅processon流程图、脑图预览、编辑链接支持

API说明

API	说明
AddApiEventListener	添加时间监听
RemoveApiEventListener	移除事件监听

事件类型说明

事件名	说明	回调信息
fileOpen	监听文件打开，获取文件类型	// 成功响应 { duration: 812, fileInfo: { createTime: 1606461829, id: "94749723688", modifyTime: 1606461829, name: "example.doc", officeType: "s", }, stageTime: 1614, success: true, time: 1614, ts: 1607858260164, }
fileStatus	监听文件状态	{ status: 0, // 文档无更新 status: 1, // 版本保存成功, 触发场景：手动保存、定时保存、关闭网页 status: 2, // 暂不支持保存空文件, 触发场景：内核保存完后文件为空 status: 3, // 空间已满 status: 4, // 保存中请勿频繁操作，触发场景：服务端处理保存队列已满，正在排队 status: 5, // 保存失败 status: 6, // 文件更新保存中，触发场景：修改文档内容触发的保存 status: 7, // 保存成功，触发场景：文档内容修改保存成功 }
OnUserListInit	监听协作成员初始化	以上三个协作者事件的返回值：协作成员返回参数注：id和real_userid拼接规则（_w_appid + ":" + user_id）头像显示用户方需要支持两种方式：base64、url
OnUserJoin	监听协作成员加入
OnUserQuit	监听协作成员退出

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()
// 添加事件监听
jssdk.ApiEvent.AddApiEventListener('fileOpen', data => {
    console.log('文件信息', data)
})
// 移除事件监听
jssdk.ApiEvent.RemoveApiEventListener('fileOpen', () => {
    // 其他操作
})

5. Tab操作

openSdk： v0.1.0+ 目前仅processon流程图、脑图预览、编辑链接支持

API	入参	返回值说明	备注
getTabs	无	[ { tabKey: 'StartTab', text: '开始' }, { tabKey: 'InsertTab', text: '插入' }, { tabKey: 'ReviewTab', text: '审阅', commandBarId: 'TabReviewWord' }, { tabKey: 'PageTab', text: '页面' }, ]
switchTab		无	入参tabKey必须取自getTabs函数的返回值

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()
// 获取Tabs列表
const tabs = await jssdk.getTabs()
// 切换到某个tab
await switchTab({tabKey: "StartTab"})

6. save （保存文件）

openSdk： v0.1.0+ 目前仅processon流程图、脑图预览、编辑链接支持

返回值

属性	数据类型	说明
result	string	保存状态
size	number	文件大小，单位byte
version	number	版本

保存状态说明

保存状态	说明
ok	版本保存成功，可在历史版本中查看
nochange	文档无更新，无需保存版本
SavedEmptyFile	暂不支持保存空文件触发场景：内核保存完后文件为空
SpaceFull	空间已满
QueneFull	保存中请勿频繁操作触发场景：服务端处理保存队列已满，正在排队
fail	保存失败

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()
const result = await jssdk.save()

7. destory （销毁iframe和sdk实例）

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()
jssdk.destory()

8. iframe （获取iframe实例）

javascript

const jssdk = OpenSDK.config({
  url,
  mount: document.querySelector("#preview"), // 挂载 iframe 节点
  refreshToken: refreshToken, // 配置超时获取 token 函数
  ...
});
// 等待sdk初始化完成
await jssdk.ready()
// 获取iframe实例
const iframe = jssdk.iframe

SDK使用说明 ​

使用须知 ​

SDK下载 ​

SDK引用 ​

初始化 ​

token鉴权 ​

WebofficeSDK实例 ​

前端对接OpenSDK api说明 ​

打印功能 ​

下载功能 ​

OpenSDK-0.1.0 使用说明 ​

1. OpenSDK实例 ​

2. API说明 ​

1. ready （初始化） ​

2. print （非四大组件及兼容层链接打印） ​

3.download （非四大组件及兼容层链接下载、导出） ​

4. ApiEvent事件监听 ​

5. Tab操作 ​

6. save （保存文件） ​

7. destory （销毁iframe和sdk实例） ​

8. iframe （获取iframe实例） ​

SDK使用说明

使用须知

SDK下载

SDK引用

初始化

token鉴权

WebofficeSDK实例

前端对接OpenSDK api说明

打印功能

下载功能

OpenSDK-0.1.0 使用说明

1. OpenSDK实例

2. API说明

1. ready （初始化）

2. print （非四大组件及兼容层链接打印）

3.download （非四大组件及兼容层链接下载、导出）

4. ApiEvent事件监听

5. Tab操作

6. save （保存文件）

7. destory （销毁iframe和sdk实例）

8. iframe （获取iframe实例）