全部产品

基础用法

显示模式

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

[{ userId: 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 时,通过分别配置不同文档对应的功能选项,可以开启和关闭文档中的特定功能和控制文档打开时的状态。

注意

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

通用选项

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

配置项说明:

配置项

说明

isShowTopArea

是否显示顶部区域

isShowHeader

是否显示头部区域

isBrowserViewFullscreen

是否在浏览器区域全屏,为 true 不允许全屏

isIframeViewFullscreen

是否在 iframe 区域内全屏,为 true 不允许全屏

代码演示:

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)

enable

boolean

组件状态切换(默认 true),禁用或者开启组件

动态更新

上面说的配置只是在初始化的时候生效,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

保存失败