基础用法

本文介绍文档在线协作如何通过初始化配置,开启不同的显示模式、配置时间监听和组件状态等。

显示模式

JS-SDK通过初始化配置选项,可以开启不同的显示模式。

  • 示例

    const instance= aliyun.config({
      mode: 'normal',
    });
  • 参数

    属性

    描述

    mode

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

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

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

协作用户配置

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

  • 示例

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

    属性

    类型

    描述

    isCooperUsersAvatarVisible

    Boolean

    协作用户头像显示切换。

    cooperUsersColor

    Array

    设置协作用户光标颜色。

    以JSON格式的数组表示,包括如下内容:

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

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

  • 动态更新

    以上配置只在初始化时生效,JS-SDK还提供了动态更新组件状态接口,目前只提供设置用户光标颜色接口,示例如下:

    await instance.cooperUserAttribute([
      {
        isCooperUsersAvatarVisible: true, //是否显示协作用户头像
        cooperUsersColor: [{
          userId: 'xxx', //用户ID
          color: 'red', //用户光标颜色
        }],
      },
    ]);

事件监听配置

监听剪切板

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

注意

目前仅支持移动端表格以及文字。

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

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

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

//配置获取系统剪切板数据函数
aliyun.config({
  getClipboardData,
  //...
});

监听 Toast

初始化JS-SDK时,可以通过配置自定义toast函数,关闭原有toast提示并且获取相关自定义toast样式。

  • 示例

    //拦截toast函数
    const onToast = ({
      msg, //提示信息
      action, //提示动作
    }) => {
      //自身业务处理
    };
    
    //配置toast函数
    aliyun.config({ 
      onToast,
      //...
    });
  • action参数说明

    action

    描述

    success

    成功。

    error

    错误。

    warn

    警告。

    close

    关闭toast。

监听外链跳转

通过配置自定义函数,可以拦截原有外链跳转并获取link信息来做处理,示例如下:

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

//配置外链跳转函数
aliyun.config({ 
  onHyperLinkOpen,
  //...
});

自定义功能

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

注意

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

通用选项

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

  • 配置项说明

    配置项

    描述

    isShowTopArea

    是否显示顶部区域。

    isShowHeader

    是否显示头部区域。

    isBrowserViewFullscreen

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

    • true:不允许全屏。

    • false(默认):允许全屏。

    isIframeViewFullscreen

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

    • true:不允许全屏。

    • false(默认):允许全屏。

  • 示例

    aliyun.config({
      //通用选项,所有类型文档适用
      commonOptions: {
        isShowTopArea: false, //隐藏顶部区域(头部和工具栏)
        isShowHeader: false, //隐藏头部区域
        isBrowserViewFullscreen: false, //是否在浏览器区域全屏
        isIframeViewFullscreen: false, //是否在iframe区域内全屏
      },
    });

文字选项

  • 配置项:wordOptions

  • 子项:

    配置项

    描述

    isShowDocMap

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

    isBestScale

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

    isShowBottomStatusBar

    是否展示底部状态栏。

    isOpenIntoEdit

    (Mobile)要有编辑权限,移动端打开时是否进入编辑。

    isShowHoverToolbars

    (Mobile)是否显示文字底部工具栏。

    isVoiceCommentEnabled

    (Mobile)是否允许插入语音评论。

  • 示例

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

演示选项

  • 配置项:pptOptions

  • 子项:

    配置项

    描述

    isShowBottomStatusBar

    是否展示底部状态栏。

    isShowRemarkView

    是否显示备注视图。

    isShowInsertMedia

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

    isOpenIntoEdit

    (Mobile)要有编辑权限,移动端打开时是否进入编辑。

    showPrevTipWhilePlay

    (Mobile)播放时向上翻页,是否展示上一页的提示。

    isShowReviewLogo

    (Mobile)是否显示审阅左上logo。

  • 示例

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

PDF 选项

  • 配置项:pdfOptions

  • 子项:

    配置项

    描述

    isShowComment

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

    isInSafeMode

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

    isBestScale

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

    isShowBottomStatusBar

    是否展示底部状态栏。

  • 示例

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

组件状态设置

初始化状态设置

通过配置选项commandBars,可以隐藏、禁用页面的组件或者执行组件命令。

  • 示例(隐藏左上角的按钮)

    aliyun.config({
      commandBars: [
        {
          cmbId: 'HeaderLeft', //组件ID
          attributes: {
            visible: false, //隐藏组件
            enable: false, //禁用组件,组件显示但不响应点击事件
          },
        },
      ],
    });
  • 支持属性

    目前配置中,支持的attributes属性如下表所示:

    属性

    数据类型

    描述

    visible

    Boolean

    组件显示切换。取值范围如下:

    • true(默认):显示组件。

    • false:隐藏组件。

    enable

    Boolean

    组件状态切换。

    • true(默认):开启组件。

    • false:禁用组件。

  • 动态更新

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

    const instance= aliyun.config({
      //详细配置
    });
    
    instance.setCommandBars([
      //可以配置多个组件
      {
        cmbId: '组件ID',
        attributes: {
          visible: false, //隐藏组件
          enable: false, //禁用组件,组件显示但不响应点击事件
        },
      },
    ]);

组件ID列表

下面列出目前可用的组件列表。

  • 公共

    组件ID

    描述

    HeaderLeft

    (PC)头部左侧,头部一共分左、中、右三块区域。

    HeaderRight

    (PC)头部右侧,头部一共分左、中、右三块区域。

    FloatQuickHelp

    右下角帮助。

    CooperationPanelOwnerInfo

    (Mobile)协作列表中当前文档所有者信息。

    Logo

    (Mobile)状态栏Logo。

    Cooperation

    (Mobile)状态栏协作头像。

    More

    (Mobile)状态栏更多按钮。

    HistoryVersion

    (PC)顶部状态栏>历史记录菜单>历史版本。

    HistoryRecord

    (PC)顶部状态栏>历史记录菜单>协作记录。

    HistoryVersionDivider

    (PC)表格>右键菜单>历史版本/协作记录分割线。

    SendButton

    (Mobile)顶部工具栏>分享按钮。

    CooperHistoryMenuItem

    (Mobile)顶部工具栏>协作记录菜单。

    TabPrintPreview

    (PC)顶部工具栏打印按钮。

    MenuPrintPreview

    (PC)顶部工具栏打印按钮。

注意

如果需要隐藏整个头部以及工具栏,可以在config中设置{ mode: 'simple' }切换到极简模式。

  • 文字

    组件ID

    描述

    ReviewTrackChanges

    编辑、修订状态按钮。

    TrackChanges

    编辑、修订状态下拉选项。

    ContextMenuConvene

    文字右键召唤在线协助者。

    WriterHoverToolbars

    (Mobile)文字>底部工具栏。

    ReadSetting

    (Mobile)文字>状态栏>阅读设置。

  • 表格

    组件ID

    描述

    CheckCellHistory

    (PC)单元格最近的改动。

  • 演示

    组件ID

    描述

    WPPMobileMarkButton

    (Mobile)浮动备注按钮。

    PlayComponentToolbar

    全屏播放时Toolbar。

    WPPPcCommentButton

    (PC)底部工具栏>评论按钮。

    WPPMobileCommentButton

    (Mobile)底部工具栏>评论按钮。

  • PDF

    组件ID

    描述

    PDFMobilePageBar

    (Mobile)页码。

组件命令执行

通过调用方法可以执行组件命令。

执行方法如下所示:

window.onload = async function() {
  const instance= aliyun.config({
    //详细配置
  });

  //注意:执行命令的时候需要等待组件加载完毕
  await instance.ready();

  //通过调用方法执行组件命令
  instance.executeCommandBar('TabPrintPreview');
};

更多可用组件ID如下:

  • 公共:

    组件ID

    描述

    TabPrintPreview

    顶部工具栏打印按钮。

  • 文字

    组件ID

    描述

    BookMark

    顶部工具栏书签按钮。

主动保存

可以在适当的时机主动触发保存接口,用来辅助用户保存文件。

  • 使用方式

    await instance.ready();
    
    let result = await instance.save();
  • 返回参数

    {
      result: 'nochange', //保存状态
      size: 15302, //文件大小,单位Byte
      version: 16, //版本
    }
  • 状态说明

    保存状态

    描述

    ok

    版本保存成功,可在历史版本中查看。

    nochange

    文档无更新,无需保存版本。

    SavedEmptyFile

    暂不支持保存空文件。触发场景:内核保存完后文件为空。

    SpaceFull

    空间已满。

    QueneFull

    保存中请勿频繁操作。触发场景:服务端处理保存队列已满,正在排队。

    fail

    保存失败。

阿里云首页 智能媒体管理 相关技术圈