初始化配置项

WebOffice 文档在初始化(调用 WebOfficeSDK.init()函数)时，除了 appId、officeType 和 fileId 这三个必须要传的参数之外，还支持传入一些额外的配置项，从类别来划分的话，一共有四种类型，分别是常用配置、事件配置、自定义功能配置和组件状态配置。

总览

配置项	类型	说明	适用组件
mode	string	显示模式	所有
+ cooperUserAttribute	CooperUserAttribute {}	协作用户配置	所有
isCooperUsersAvatarVisible	boolean	协作用户头像显示切换
+ cooperUsersColor	CooperUsersColor []	设置协作用户光标颜色
userId	string	用户 id
color	string	光标颜色色值
onToast	Function	自定义 toast	所有
onHyperLinkOpen	Function	拦截原有外链跳转并获取 link 信息来做处理	所有
getClipboardData	Function	移动端 APP 获取剪切板数据。	表格、文字
commandBars	CommandBars []	commandBars 初始状态配置	所有
+ commonOptions	CommonOptions{}	组件通用选项	所有
isShowTopArea	boolean	是否显示顶部区域
isShowHeader	boolean	是否显示头部区域
isBrowserViewFullscreen	boolean	是否在浏览器区域全屏，为 `true` 不允许全屏
isIframeViewFullscreen	boolean	是否在 iframe 区域内全屏，为 `true` 不允许全屏
acceptVisualViewportResizeEvent	boolean	控制 WebOffice 是否接受外部的 VisualViewport
+ wordOptions	WordOptions{}	文字组件选项	文字
isShowDocMap	boolean	是否开启目录功能，默认开启
isBestScale	boolean	打开文档时，默认以最佳比例显示
isShowBottomStatusBar	boolean	是否展示底部状态栏
+ mobile	MobileWordOptions {}	移动端的特殊配置项
isOpenIntoEdit	boolean	（Mobile）要有编辑权限，移动端打开时是否进入编辑
isShowHoverToolbars	boolean	（Mobile）是否显示文字底部工具栏
isVoiceCommentEnabled	boolean	（Mobile）是否允许插入语音评论
isShowHoverToolbars	boolean	（Mobile）是否显示字体下载提示
+ pptOptions	PPTOptions{}	演示组件选项	演示
isShowBottomStatusBar	boolean	是否展示底部状态栏
isShowRemarkView	boolean	是否显示备注视图
isShowInsertMedia	boolean	是否显示插入音视频入口
isShowComment	boolean	是否显示评论相关入口
+ mobile	MobilePPTOptions{}	移动端的特殊配置项
isOpenIntoEdit	boolean	（Mobile）要有编辑权限，移动端打开时是否进入编辑
showPrevTipWhilePlay	boolean	（Mobile）播放时向上翻页，是否展示 “上一页” 的提示
isShowReviewLogo	boolean	（Mobile）是否显示审阅左上 logo
+ pdfOptions	PDFOptions{}	PDF 组件选项	PDF
isShowComment	boolean	是否显示注解，默认显示
isInSafeMode	boolean	是否处于安全模式（安全模式下不能划选文字，不能复制以及不能通过链接跳转），默认不是安全模式
isBestScale	boolean	默认以最佳显示比例打开
isShowBottomStatusBar	boolean	是否展示底部状态栏
disBackScrollPos	boolean	是否禁用滚动还原
+ otlOptions	OTLOptions{}	智能文档组件选项	智能文档
+ loadOptions	LoadOptionsOTLOptions{}	传参示例
+ workbench	WorkBenchOTLOptions{}	智能文档配置
editor	EditorOTLOptions[]	文本编辑相关功能的开启项
view	ViewOTLOptions[]	文档页面视图相关窗口开启项

常用配置

显示模式

JSSDK 通过初始化配置选项，可以开启不同的显示模式：

const jssdk = WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  mode: 'simple'
})

关于 mode 选项的说明：

选项值	说明	是否默认选项
`nomal`	普通模式，展示所有功能界面	是
`simple`	极简模式，不显示头部和工具栏	否

协作用户配置

可以通过 cooperUserAttribute 选项，控制协作用户头像是否显示以及控制用户光标颜色：

WebOfficeSDK.init({
  // 必填项
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  // 可选项
  cooperUserAttribute: {
    isCooperUsersAvatarVisible: true, // 是否显示协作用户头像
    cooperUsersColor: [
      {
        userId: 'xxx', // 用户 id
        color: '#F65B90' // 用户光标颜色
      }
    ]
  }
})

支持属性

属性	类型	说明
isCooperUsersAvatarVisible	boolean	协作用户头像显示切换
cooperUsersColor	[{ userId: string, color: string }]	设置协作用户光标颜色

动态更新

上面的配置只在初始化的时候生效，JSSDK 还提供了动态更新组件状态接口，目前只提供设置用户光标颜色接口。

await instance.setCooperUserColor([
  {
    userId: 'xxx', // 用户 id
    color: 'red' // 用户光标颜色
  }
])

事件配置

监听剪切板

在移动端 APP 需要从系统剪切板获取数据时，可以使用该接口。

目前仅支持移动端表格以及文字，并且 JSSDK 版本为 v1.1.6

可以通过传入 获取系统剪切板数据函数 在文档粘贴的时候，调用传入函数获取系统剪切板数据，返回一个 Promise 或者 Object：

// 获取系统剪切板数据函数
const getClipboardData = () => {
  // 自身业务处理……

  return Promise.resolve({
    text: 'xxx', // text 格式数据
    html: 'xxx', // html 格式数据，目前仅表格支持
    updateExternal: true // 是否从外部粘贴数据，为 false 则从内部剪切板获取
  })
}

// 配置获取系统剪切板数据函数
WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  getClipboardData
})

监听 Toast

初始化 JSSDK 的时候，可以通过配置自定义 toast 函数，关闭原有 toast 提示并且获取相关自定义 toast 样式。

// 拦截 toast 函数
const onToast = ({
  msg, // 提示信息
  action // 提示动作
}) => {
  // 自身业务处理
}

// 配置 toast 函数
WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  onToast
})

以下是 action 参数说明：

action	说明
success	成功提示
error	错误提示
warn	警告提示
close	关闭 toast

监听外链跳转

可以通过配置自定义函数，来拦截原有外链跳转并获取 link 信息来做处理：

// 拦截外链跳转函数
const onHyperLinkOpen = ({
  linkUrl // 跳转 url
}) => {
  // 自身业务处理
}

// 配置外链跳转函数
WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  onHyperLinkOpen
})

自定义功能配置

初始化 JSSDK 时，通过分别配置不同文档对应的功能选项，可以开启和关闭文档中的特定功能和控制文档打开时的状态。

以下是通用选项的示例：

WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  // 通用选项，所有类型文档适用
  commonOptions: {
    isShowTopArea: false, // 隐藏顶部区域（头部和工具栏）
    isShowHeader: false // 隐藏头部区域
  }
})

提示

所有功能选项只能通过初始化配置控制，不支持热切换。

通用选项

通过配置选项 commonOptions，可以配置页面的通用选项。

配置项说明：

配置项	说明
isShowTopArea	是否显示顶部区域
isShowHeader	是否显示头部区域
isBrowserViewFullscreen	是否在浏览器区域全屏，为 true 不允许全屏
isIframeViewFullscreen	是否在 iframe 区域内全屏，为 true 不允许全屏
acceptVisualViewportResizeEvent	控制 WebOffice 是否接受外部的 VisualViewport

代码演示：

WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  // 通用选项，所有类型文档适用
  commonOptions: {
    isShowTopArea: false, // 隐藏顶部区域（头部和工具栏）
    isShowHeader: false, // 隐藏头部区域
    isBrowserViewFullscreen: false, // 是否在浏览器区域全屏
    isIframeViewFullscreen: false, // 是否在 iframe 区域内全屏
    acceptVisualViewportResizeEvent: true // 控制 WebOffice 是否接受外部的 VisualViewport
  }
})

文字选项

配置项：wordOptions
子项：

配置项	说明
isShowDocMap	是否开启目录功能，默认开启
isBestScale	打开文档时，默认以最佳比例显示
isShowBottomStatusBar	是否展示底部状态栏
isOpenIntoEdit	（Mobile）要有编辑权限，移动端打开时是否进入编辑
isShowHoverToolbars	（Mobile）是否显示文字底部工具栏
isVoiceCommentEnabled	（Mobile）是否允许插入语音评论
showFontDownloadNotice	（Mobile）是否显示字体下载提示

代码演示：

WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  wordOptions: {
    isShowDocMap: false, // 是否开启目录功能，默认开启
    isBestScale: false, // 打开文档时，默认以最佳比例显示
    isShowBottomStatusBar: false, // 是否展示底部状态栏
    mobile: {
      isOpenIntoEdit: false, // （Mobile）要有编辑权限，移动端打开时是否进入编辑
      isShowHoverToolbars: false, // （Mobile）是否显示文字底部工具栏
      isVoiceCommentEnabled: false, // （Mobile）是否允许插入语音评论
      showFontDownloadNotice: false // （Mobile）是否显示字体下载提示
    }
  }
})

演示选项

配置项：pptOptions
子项：

配置项	说明	支持版本
isShowBottomStatusBar	是否展示底部状态栏	WebOffice v1.67.1+ 支持
isShowRemarkView	是否显示备注视图	WebOffice v1.67.1+ 支持
isShowInsertMedia	是否显示插入音视频入口	WebOffice v1.67.1+ 支持
isOpenIntoEdit	（Mobile）要有编辑权限，移动端打开时是否进入编辑	WebOffice v1.67.1+ 支持
showPrevTipWhilePlay	（（Mobile）播放时向上翻页，是否展示 “上一页” 的提示	WebOffice v1.67.1+ 支持
isShowReviewLogo	（Mobile）是否显示审阅左上 logo	WebOffice v1.67.1+ 支持
isShowComment	是否显示评论相关入口	WebOffice v3.1.1+ 支持

代码演示：

WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Presentation,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  pptOptions: {
    isShowBottomStatusBar: false, // 是否展示底部状态栏
    isShowRemarkView: true, // 是否显示备注视图
    isShowInsertMedia: true, // 是否显示插入音视频入口
    isShowComment: true, // 是否显示评论相关入口
    mobile: {
      isOpenIntoEdit: false, // （Mobile）要有编辑权限，移动端打开时是否进入编辑
      showPrevTipWhilePlay: true, // （Mobile）播放时向上翻页，是否展示 “上一页” 的提示
      isShowReviewLogo: false // （Mobile）是否显示审阅左上 logo
    }
  }
})

PDF 选项

配置项：pdfOptions
子项：

配置项	说明
isShowComment	是否显示注解，默认显示
isInSafeMode	是否处于安全模式（安全模式下不能划选文字，不能复制以及不能通过链接跳转），默认不是安全模式
isBestScale	默认以最佳显示比例打开
isShowBottomStatusBar	是否展示底部状态栏
disBackScrollPos	是否禁用滚动还原

代码演示：

WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Presentation,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  pdfOptions: {
    isShowComment: false, // 是否显示注解，默认显示
    isInSafeMode: false, // 是否处于安全模式（安全模式下不能划选文字，不能复制以及不能通过链接跳转），默认不是安全模式
    isBestScale: false, // 默认以最佳显示比例打开
    isShowBottomStatusBar: false, // 是否展示底部状态栏
    disBackScrollPos: true // 是否禁用滚动还原
  }
})

智能文档选项

注意

传参的配置项在上线后，节点类型的配置不能减少只能新增，否则可能导致存量文档出现数据方面 不可修复 的问题！
因为「智能文档」是协同编辑产品，被使用的功能，会记录在【历史版本】【协作记录】上，对相应功能的使用做同步，记录用户的操作数据，方便用户的回退操作等。

举例：
通过 JSSDK，装载了【表情符号】，那么上线后，存量(历史)文档会存有【表情符号】数据，如果通过配置项将【表情符号】功能卸载了，那么老数据操作就全报错了。

这点主要针对涉及数据节点的功能，所以如果区分不了哪些是数据类功能，建议 先开放少有功能，再逐步放开其他功能！！！

配置项：otlOptions
子项：

配置项	说明
editor	文本编辑相关功能的开启选项
view	文档页面视图相关窗口开启选项

关于 editor 子选项的说明：

配置项	功能名	说明
title	文档标题	文档大标题
heading	标题 h1-h6	`节点类型`
fontSize	字号	`文字属性`
bold	加粗	`文字属性`
italic	斜体	`文字属性`
underline	下划线	`文字属性`
deleteLine	删除线	`文字属性`
script	上下标	`文字属性`
colorStyle	字体颜色、字体高亮	`文字属性`
outlineList	有序列表、无序列表、任务列表	`节点类型`
find	查找替换
picture	图片	`节点类型` 支持粘贴、面板插入、拖动插入
link	超链接	`文字属性`
blockquote	引用	`节点类型`
horizonRule	分隔线	`节点类型`
code	代码块	`节点类型`
inlineCode	行内代码块	`文字属性`
emoji	表情	`节点类型`
table	表格	`节点类型`
comment	评论	评论功能
paragraphHandler	段落操作柄、折叠、item 拖拽	段落操作柄，包含菜单、折叠、item 拖拽等功能，悬浮到段落上方显现
history	撤销、重做	包括面板按钮和键盘快捷键
catalog	目录	左上角的目录功能
date	日期	`节点类型`
latex	公式	`节点类型`
highlightBlock	高亮块，依赖项：emoji	`节点类型`
record	协作记录（必选）	协作记录功能和面板
countdown	倒计时	`节点类型`
lockBlock	区域权限	`节点类型` 内容保护区，只有文档作者可以编辑

关于 view 子选项的说明：

配置项	功能名	说明
startTab	文档头部工具栏	决定整个文档顶部工具栏是否开启
mobileMenu	移动端下方菜单
mobileReadMenu	移动端阅读模式菜单
contextMenu	右键菜单

代码演示：

// 配置项
const loadOptions = {
  workbench: {
    //增加编辑配置子项，文档头部工具栏及段落操作柄中才可选择使用该功能。
    editor: [
      'title',
      'heading',
      'fontSize',
      'bold',
      'italic',
      'underline',
      'deleteLine',
      'script',
      'colorStyle',
      'outlineList',
      'indent',
      'align',
      'find',
      'picture',
      'link',
      'blockquote',
      'horizonRule',
      'code',
      'inlineCode',
      'emoji',
      'table',
      'history'
    ],
    view: ['startTab', 'mobileMenu', 'contextMenu', 'mobileReadMenu']
  }
}
WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Otl,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  // 不传otlOptions，将全量加载
  otlOptions: {
    loadOptions: JSON.stringify(loadOptions)
  }
})

提示

传参问题：

若 loadOptions 为空对象（即默认值），「文档」将全量加载
若 loadOptions 不为空，workbench 为空对象，「文档」将不加载提供的所有可配置项
配置项严格要求大小写匹配（基本是小驼峰格式），传错则不会生效

组件状态配置

文档初始化时，可以通过 commandBars 选项，来隐藏、禁用页面的组件或者执行组件命令。

举个例子，我们需要隐藏左上角的按钮：

WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx',
  commandBars: [
    {
      cmbId: 'HeaderLeft', // 组件 ID
      attributes: {
        visible: false, // 隐藏组件
        enable: false // 禁用组件，组件显示但不响应点击事件
      }
    }
  ]
})

支持属性

目前配置中，我们支持的 attributes 配置有两个：

属性	支持	说明
visible	boolean	组件显示切换（默认 true）
enable	boolean	组件状态切换（默认 true），禁用或者开启组件

上面说的配置只是在初始化的时候生效，JSSDK 还提供了动态更新组件状态的接口。

公共

文字

表格

演示

PDF

智能文档

多维表格

枚举

公共

文字

表格

演示

PDF

文档格式转换

PDF/图片转文档

初始化配置项

总览

常用配置

显示模式

协作用户配置

支持属性

动态更新

事件配置

监听剪切板

监听 Toast

监听外链跳转

自定义功能配置

通用选项

文字选项

演示选项

PDF 选项

智能文档选项

组件状态配置

支持属性

初始化配置项 ​

总览 ​

常用配置 ​

显示模式 ​

协作用户配置 ​

支持属性 ​

动态更新 ​

事件配置 ​

监听剪切板 ​

监听 Toast ​

监听外链跳转 ​

自定义功能配置 ​

通用选项 ​

文字选项 ​

演示选项 ​

PDF 选项 ​

智能文档选项 ​

组件状态配置 ​

支持属性 ​

初始化配置项

总览

常用配置

显示模式

协作用户配置

支持属性

动态更新

事件配置

监听剪切板

监听 Toast

监听外链跳转

自定义功能配置

通用选项

文字选项

演示选项

PDF 选项

智能文档选项

组件状态配置

支持属性