Skip to content
本页内容

初始化配置项

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

总览

配置项类型说明适用组件
string
显示模式
所有
+
CooperUserAttribute {}
协作用户配置
所有
Function
自定义 toast
所有
Function
拦截原有外链跳转并获取 link 信息来做处理
所有
Function
移动端 APP 获取剪切板数据。
表格、文字
CommandBars []
commandBars 初始状态配置
所有
+
CommonOptions{}
组件通用选项
所有
+
WordOptions{}
文字组件选项
文字
+
PPTOptions{}
演示组件选项
演示
+
PDFOptions{}
PDF 组件选项
PDF
+
OTLOptions{}
智能文档组件选项
智能文档

常用配置

显示模式

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

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

关于 mode 选项的说明:

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

协作用户配置

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

js
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 还提供了动态更新组件状态接口,目前只提供设置用户光标颜色接口。

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

事件配置

监听剪切板

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

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

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

js
// 获取系统剪切板数据函数
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 样式。

js
// 拦截 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 信息来做处理:

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

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

自定义功能配置

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

以下是通用选项的示例:

js
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

代码演示:

js
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)是否显示字体下载提示

代码演示:

js
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+ 支持

代码演示:

js
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
是否禁用滚动还原

代码演示:

js
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
右键菜单

代码演示:

js
// 配置项
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)
  }
})

传参问题

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

组件状态配置

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

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

js
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 还提供了动态更新组件状态的接口。