配置参数

配置参数使用方法

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

配置参数列表

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

显示模式

通过配置参数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')

协作用户配置

通过配置参数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参数说明：

监听外链跳转

通过配置参数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, // 是否禁用滚动还原。
    },
  })