文档

配置参数

更新时间:

在初始化文档应用时,支持传入一些参数项对文档进行一些基本设置,本文介绍WebOffice文档配置参数的使用方法。

配置参数使用方法

aliyun.config({
  url: '文档在线预览或编辑地址',
  // 其他配置项参数。
})

配置参数列表

支持的配置参数如下表所示。

配置参数

类型

是否必填

描述

url

string

文档在线预览或编辑地址。

mount

HTMLElement

挂载节点。

refreshToken

function

token 刷新函数

mode

string

显示模式。

commandBars

array

页面定制。

cooperUserAttribute

object

协作用户配置。

getClipboardData

function

监听剪切板。

onToast

function

监听Toast弹窗提示。

onHyperLinkOpen

function

监听外链跳转。

commonOptions

object

组件通用配置。

wordOptions

object

文字文档自定义配置。

excelOptions

object

表格文档自定义配置。

pptOptions

object

演示文档自定义配置。

pdfOptions

object

PDF文档自定义配置。

显示模式

通过配置参数mode,可以设置不同的界面显示模式。

  • 示例

    aliyun.config({
      mode: 'normal',
    });
  • 说明

    参数

    描述

    mode

    界面显示模式。取值范围如下:

    • normal(默认):普通模式,展示所有功能界面。

    • simple:极简模式,不显示头部和工具栏。

页面定制

通过配置参数commandBars,可以设置隐藏或显示页面的组件、禁用或执行组件。

  • 示例

    如下示例代码以隐藏页面左上角的按钮为例。

    aliyun.config({
      // 可以批量配置多个组件的状态。
      commandBars: [
        {
          cmbId: 'HeaderLeft', // 组件ID。
          attributes: {
            visible: false, // 隐藏组件。
            enable: false, // 禁用组件(组件显示但不响应单击事件)。
          },
        },
      ],
    })
  • 说明

    • 参数cmbId表示组件ID。关于组件ID的更多信息,请参见可定制列表

    • 参数attributes用于设置组件状态,相关说明如下表所示。

      参数

      类型

      描述

      visible

      boolean

      是否显示组件。取值范围如下:

      • true:是,显示组件。

      • false:否,隐藏组件。

      enable

      boolean

      是否执行组件。取值范围如下:

      • true:是,执行组件。

      • false:否,禁用组件,组件显示但不响应单击事件。

动态更新组件状态

以上配置只在初始化时生效,JS-SDK还提供了动态更新组件状态的接口,示例代码如下。

const instance = aliyun.config({
  // ...
})

instance.setCommandBars([
  {
    cmbId: '组件ID',
    attributes: { visible: false, enable: false },
  },
])

执行组件命令

通过调用executeCommandBar方法可以执行组件命令,示例代码如下。

const instance = aliyun.config({
  // ...
})

// 执行命令时需要等待组件加载完毕。
await instance.ready()

// 执行顶部工具栏书签按钮,自动打开书签面板
instance.executeCommandBar('BookMark')

协作用户配置

重要

目前仅文字文档和表格文档支持该配置项,演示文档和PDF文档暂不支持。

通过配置参数cooperUserAttribute,可以设置显示或隐藏协作用户头像、用户光标颜色。

  • 示例

    const instance = aliyun.config({
      cooperUserAttribute: {
        isCooperUsersAvatarVisible: true, // 显示协作用户头像。
        cooperUsersColor: [{
          userId: 'testuid', // 用户ID。
          color: '#F65B90' // 用户光标颜色。
        }],
      },
    });
  • 参数

    属性

    类型

    描述

    isCooperUsersAvatarVisible

    boolean

    是否显示协作用户头像。取值范围如下:

    • true:是,显示头像。

    • false:否,隐藏头像。

    cooperUsersColor

    array

    设置协作用户光标颜色。以JSON格式的数组表示,包括如下内容:

    • userId:用户ID,类型为string。

    • color:用户光标颜色,类型为string。

动态设置光标颜色

以上配置只在初始化时生效,JS-SDK还提供了动态设置协作用户的光标颜色的接口,示例代码如下。

await instance.ready()
instance.setCooperUserColor([
  { userId: 'testuid1', color: '#333333' },
  { userId: 'testuid2', color: '#666666' },
])

监听剪切板

通过配置参数getClipboardData,可以在移动端App从系统剪切板获取数据。

粘贴文档时,可以通过传入getClipboardData参数,调用传入函数获取系统剪切板数据,返回一个Promise或者Object。示例代码如下。

aliyun.config({
  // 获取系统剪切板数据函数。
  getClipboardData: () => {
    // 自身业务处理。

    return Promise.resolve({
      text: 'test-text', // TEXT格式的数据。
      html: 'test-html', // HTML格式的数据,目前仅支持表格文档。
      updateExternal: true, // 是否从外部粘贴数据。取值为true表示从外部剪切板粘贴数据;取值为false表示从内部剪切板粘贴数据。
    })
  },
})

监听Toast弹窗提示

通过配置参数onToast,可以关闭原有Toast弹窗提示,并且获取相关自定义Toast弹窗样式。示例代码如下:

// 配置Toast拦截函数。
aliyun.config({
  onToast: ({ msg, action }) => {
    // 自身业务处理。
    console.log('msg: ', msg) // 提示信息。
    console.log('action: ', action) // 提示动作。
  },
})

action参数说明:

action

描述

success

成功提示。

error

错误提示。

warn

警告提示。

close

关闭Toast。

监听外链跳转

通过配置参数onHyperLinkOpen,可以拦截原有外链跳转并获取link信息来做处理。示例代码如下。

// 配置外链跳转拦截函数。
aliyun.config({
  onHyperLinkOpen: ({ linkUrl }) => {
    // 自身业务处理。
    console.log('linkUrl: ', linkUrl) // 跳转URL。
  },
})

组件通用配置

通过配置参数commonOptions,可以对不同类型的文档设置开启或关闭文档中的特定功能、控制文档打开时的状态。

重要

相关配置项只能在初始化时进行配置控制,不支持热切换。

  • 支持的配置项

    配置项

    描述

    isShowTopArea

    是否显示顶部区域。取值范围如下:

    • true:是,显示顶部区域。

    • false:否,隐藏顶部区域(头部和工具栏)。

    isShowHeader

    是否显示头部区域。取值范围如下:

    • true:是,显示头部区域。

    • false:否,隐藏头部区域。

    isBrowserViewFullscreen

    是否在浏览器区域全屏,取值范围如下:

    • true:不允许全屏。

    • false:允许全屏。

    isIframeViewFullscreen

    是否在iframe区域内全屏,取值范围如下:

    • true:不允许全屏。

    • false:允许全屏。

    acceptVisualViewportResizeEvent

    控制WebOffice是否接受外部的VisualViewport事件。

  • 示例

    aliyun.config({
      // 通用选项,所有类型文档适用。
      commonOptions: {
        isShowTopArea: false, // 隐藏顶部区域(头部和工具栏)。
        isShowHeader: false, // 隐藏头部区域。
        isBrowserViewFullscreen: false, // 允许在浏览器区域全屏。
        isIframeViewFullscreen: false, // 允许在iframe区域内全屏。
        acceptVisualViewportResizeEvent: true, // 控制WebOffice是否接受外部的VisualViewport事件。
      },
    })

文字自定义配置

通过配置参数wordOptions,可以对文字文档(Word)进行相关配置。

  • 支持的配置项

    配置项

    描述

    isShowDocMap

    是否开启目录功能,默认开启。

    isBestScale

    打开文档时,默认以最佳比例显示。

    isShowBottomStatusBar

    是否展示底部状态栏。

    isOpenIntoEdit

    移动端打开时是否进入编辑。

    说明

    需要有编辑权限。

    isShowHoverToolbars

    移动端是否显示文字底部工具栏。

    isVoiceCommentEnabled

    移动端是否允许插入语音评论。

    showFontDownloadNotice

    移动端是否显示字体下载提示。

  • 示例

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

表格自定义配置

暂无可配置项。

演示自定义配置

通过配置参数pptOptions,可以对演示文档(PPT)进行相关配置。

  • 支持的配置项

    配置项

    描述

    isShowBottomStatusBar

    是否展示底部状态栏。

    isShowRemarkView

    是否显示备注视图。

    isShowInsertMedia

    是否显示插入音视频入口。

    isOpenIntoEdit

    移动端打开时是否进入编辑。

    说明

    需要有编辑权限。

    showPrevTipWhilePlay

    移动端播放时向上翻页,是否显示上一页的提示。

    isShowReviewLogo

    移动端是否显示审阅左上logo。

    isShowComment

    是否显示评论相关入口。

  • 示例

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

PDF自定义配置

通过配置参数pdfOptions,可以对PDF文档进行相关配置。

  • 支持的配置项|

    配置项

    描述

    isShowComment

    是否显示注解,默认显示。

    isInSafeMode

    是否处于安全模式(安全模式下不能划选文字,不能复制以及不能通过链接跳转),默认不是安全模式。

    isBestScale

    默认以最佳显示比例打开。

    isShowBottomStatusBar

    是否展示底部状态栏。

    disBackScrollPos

    是否禁用滚动还原。

  • 示例

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

  • 本页导读 (1)