嵌入JS SDK API_智能商业分析 Quick BI(Quick BI)-阿里云帮助中心

本文为您详细介绍嵌入 JS SDK中包含的API接口。

功能配置项

嵌入 JS SDK中包含的功能配置接口主要分为：src、feature、events、action，接口的相关说明如下：

功能配置项	描述	是否必填	场景举例
src	嵌入页面的来源信息，定义嵌入的具体页面及其参数。	是	指定嵌入的页面为仪表板编辑页。
feature	控制嵌入页面组件的显隐状态，以及修改展示文本等展示类特性的配置。	否	隐藏嵌入的Quick BI页面的头部。
events	嵌入页面的行为事件监听器。目前开放了页面跳转前事件，监听应用内所有的跳转方法。	否	监听从仪表板编辑页跳转返回仪表板列表。
action	宿主系统触发嵌入页面行为的配置。目前开放了路由跳转、更新嵌入特性和滚动页面的行为。	否	宿主系统控制Quick BI跳转到新的页面。

src

嵌入源信息，用于生成嵌入页面。其类型为 EmbedSrcUnion，包含的参数如下表所示：

参数	类型	是否必填	描述
src.page	`EmbedRouteKey`	是	QuickBI 每个作品页、列表页的每个Tab页都可以视为一个路由，例如：仪表板预览页,、仪表板编辑页、工作台仪表板列表页等。该项代表需要嵌入页面的路由键，例如：嵌入仪表板预览页时，需要设置page为`EmbedRouteKey.dashboardView`，常见的路由键信息请参见路由键一览表。
src.origin	`string`	是	您访问Quick BI的`origin`，例如：`https://bi.aliyun.com`。
src.search	`Record<string, string>`	否	嵌入Quick BI页面的查询参数，一些页面需要传入参数配合使用。例如：工作空间页面需要传入工作空间编号`{workspaceId: 'your workspace id'}`，常见页面的search参数请参见路由键一览表。
src.pathParams	`Record<string, string>`	否	嵌入Quick BI页面的路径参数，目前只有少量页面需要传入该参数，例如数据填报编辑页和预览页的作品id是通过路径参数传入的，因此需要设置传入`pathParams: {id: 'your works id'}`。

示例代码

<EmbedComponent
      src={
        origin: 'xxx',  // 访问qbi的host
        page: EmbedRouteKey.dashboardEdit,  // 仪表板编辑页对应的EmbedRouteKey
        // 访问qbi仪表板页面的查询参数
        search: {
          workspaceId: 'xxx',  // 空间ID
          id: 'xxx',  // 作品ID
        }
      }
    />

feature

嵌入特性（feature）是用于临时控制页面组件的显隐状态，以及修改展示文本等展示类特性的配置。例如：可以隐藏页面头部等。其类型为 EmbedFeatureIntersect，结构分为三层：路由 > 功能模块 > 特性配置项，其中路由层的key是EmbedRouteKey，表示特性的生效的路由范围，不同路由下的特性可以同时配置。可传入的参数如下表所示：

参数	说明
EmbedRouteKey.homeRoot	用于控制根页面的特性。
EmbedRouteKey.workspace	用于控制工作空间页面的特性。
EmbedRouteKey.workPlatform	用于控制工作台页面的特性。
EmbedRouteKey.monitorManage	用于控制监控告警管理页面的特性。
EmbedRouteKey.dashboardEdit	用于控制仪表板编辑页面的特性。
EmbedRouteKey.workbookEdit	用于控制电子表格编辑页面的特性。
EmbedRouteKey.screenEdit	用于控制数据大屏编辑页面的特性。
EmbedRouteKey.analysisEdit	用于控制即席分析编辑页面的特性。
EmbedRouteKey.downloadEdit	用于控制自助取数编辑页面的特性。
EmbedRouteKey.formEdit	用于控制数据填报编辑页面的特性。
EmbedRouteKey.etlEdit	用于控制数据准备编辑页面的特性。
EmbedRouteKey.datasetEdit	用于控制数据集编辑页面的特性。
EmbedRouteKey.workbookFormTask	用于控制电子表格填报审批页面的特性。
EmbedRouteKey.dashboardView	用于控制仪表板预览页面的特性。
EmbedRouteKey.dashboardPublicView	用于控制仪表板公开页面的特性。

示例代码

<EmbedComponent 
  feature={{
    [EmbedRouteKey.homeRoot]: {
      // 工作台...
    },
    [EmbedRouteKey.dashboardEdit]: {
      // 仪表板编辑页...
    },
    // ...
  }} 
/>

EmbedRouteKey.homeRoot

homeRoot是Home的根页面，其特性配置对下属的所有页面都生效，例如配置homeRoot页面的header隐藏，那么workPlatform工作台、workspace工作空间、templateRoot模板市场、view我的看板、subscriptionManage订阅管理、monitorManage监控告警等页面都会生效，这些页面的头部都会隐藏。属性控制范围如下。

header：Home页面头部特性配置
header.show
- 类型：boolean
- 默认值：true
- 描述：控制Home页面头部导航是否展示

EmbedRouteKey.workspace

工作空间特性配置，各个属性控制范围如下。

header：工作空间头部特性配置
header.show
- 类型：boolean
- 默认值：true
- 描述：控制工作空间头部是否显示
goBack：工作空间返回工作台特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回工作台是否显示
goBack.text
- 类型：string
- 默认值：'返回工作台'
- 描述：自定义返回工作台文字
switchWorkspace：切换工作空间特性配置。
switchWorkspace.show
- 类型：boolean
- 默认值：true
- 描述：控制切换工作空间是否显示
breadcrumb：工作空间面包屑特性配置。
breadcrumb.show
- 类型：boolean
- 默认值：true
- 描述：控制面包屑是否显示
workspaceManageNavLabel：工作空间页空间管理目录特性配置。
workspaceManageNavLabel.text
- 类型：string
- 默认值：'空间管理'
- 描述：自定义空间管理目录文字
sideNav：工作空间左侧导航特性配置。
sideNav.show
- 类型：boolean
- 默认值：true
- 描述：控制左侧导航是否显示

EmbedRouteKey.workPlatform

工作台特性配置，各个属性控制范围如下。

userInfo：工作台页用户信息特性配置
userInfo.show
- 类型：boolean
- 默认值：true
- 描述：控制用户信息是否显示
myWorkSpace：工作台页我的工作空间特性配置
myWorkSpace.text
- 类型：string
- 默认值：'我的工作空间'
- 描述：自定义我的工作空间文字

EmbedRouteKey.monitorManage

监控告警管理页特性配置，属性控制范围如下。

gotoDashboard：监控告警管理页前往仪表板特性配置。
gotoDashboard.show
- 类型：boolean
- 默认值：true
- 描述：控制前往仪表板是否显示

EmbedRouteKey.dashboardEdit

仪表板编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
publish：发布按钮特性配置
publish.show
- 类型：boolean
- 默认值：true
- 描述：控制发布按钮是否显示
saveAs：另存为按钮特性配置
saveAs.group
- 类型：'state' | 'menu'
- 默认值：'menu'
- 描述：控制另存为按钮所属组别，'menu'表示位于更多菜单内，'state'表示位于保存发布状态区
saveAs.order
- 类型：number
- 默认值：-1
- 描述：控制另存为按钮在按钮组内的顺序
saveAs.type
- 类型：'default' | 'primary'
- 默认值：'default'
- 描述：控制另存为按钮的样式，仅属于'state'组时生效
share：分享按钮特性配置
share.show
- 类型：boolean
- 默认值：true
- 描述：控制分享按钮是否显示
offline：下线按钮特性配置
offline.show
- 类型：boolean
- 默认值：true
- 描述：控制下线按钮是否显示
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示
switchDataset：切换数据集配置
switchDataset.disabled
- 类型：boolean
- 默认值：true
- 描述：控制仪表板编辑页面中是否能切换数据集。

EmbedRouteKey.workbookEdit

电子表格编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
publish：发布按钮特性配置
publish.show
- 类型：boolean
- 默认值：true
- 描述：控制发布按钮是否显示
saveAs：另存为按钮特性配置
saveAs.group
- 类型：'state' | 'menu'
- 默认值：'menu'
- 描述：控制另存为按钮所属组别，'menu'表示位于更多菜单内，'state'表示位于保存发布状态区
saveAs.order
- 类型：number
- 默认值：-1
- 描述：控制另存为按钮在按钮组内的顺序
saveAs.type
- 类型：'default' | 'primary'
- 默认值：'default'
- 描述：控制另存为按钮的样式，仅属于'state'组时生效
offline：下线按钮特性配置
offline.show
- 类型：boolean
- 默认值：true
- 描述：控制下线按钮是否显示
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示
switchDataset：切换数据集配置
switchDataset.disabled
- 类型：boolean
- 默认值：true
- 描述：控制电子表格编辑页面中是否能切换数据集。

EmbedRouteKey.screenEdit

数据大屏编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
publish：发布按钮特性配置
publish.show
- 类型：boolean
- 默认值：true
- 描述：控制发布按钮是否显示
saveAs：另存为按钮特性配置
saveAs.group
- 类型：'state' | 'menu'
- 默认值：'menu'
- 描述：控制另存为按钮所属组别，'menu'表示位于更多菜单内，'state'表示位于保存发布状态区
saveAs.order
- 类型：number
- 默认值：-1
- 描述：控制另存为按钮在按钮组内的顺序
saveAs.type
- 类型：'default' | 'primary'
- 默认值：'default'
- 描述：控制另存为按钮的样式，仅属于'state'组时生效
share：分享按钮特性配置
share.show
- 类型：boolean
- 默认值：true
- 描述：控制分享按钮是否显示
offline：下线按钮特性配置
offline.show
- 类型：boolean
- 默认值：true
- 描述：控制下线按钮是否显示
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示
switchDataset：切换数据集配置
switchDataset.disabled
- 类型：boolean
- 默认值：true
- 描述：控制数据大屏编辑页面中是否能切换数据集。

EmbedRouteKey.analysisEdit

即席分析编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
publish：发布按钮特性配置
publish.show
- 类型：boolean
- 默认值：true
- 描述：控制发布按钮是否显示
saveAs：另存为按钮特性配置
saveAs.group
- 类型：'state' | 'menu'
- 默认值：'menu'
- 描述：控制另存为按钮所属组别，'menu'表示位于更多菜单内，'state'表示位于保存发布状态区
saveAs.order
- 类型：number
- 默认值：-1
- 描述：控制另存为按钮在按钮组内的顺序
saveAs.type
- 类型：'default' | 'primary'
- 默认值：'default'
- 描述：控制另存为按钮的样式，仅属于'state'组时生效
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示
switchDataset：切换数据集配置
switchDataset.disabled
- 类型：boolean
- 默认值：true
- 描述：控制即席分析编辑页面中是否能切换数据集。

EmbedRouteKey.downloadEdit

自助取数编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
saveAs：另存为按钮特性配置
saveAs.group
- 类型：'state' | 'menu'
- 默认值：'menu'
- 描述：控制另存为按钮所属组别，'menu'表示位于更多菜单内，'state'表示位于保存发布状态区
saveAs.order
- 类型：number
- 默认值：-1
- 描述：控制另存为按钮在按钮组内的顺序
saveAs.type
- 类型：'default' | 'primary'
- 默认值：'default'
- 描述：控制另存为按钮的样式，仅属于'state'组时生效
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示
switchDataset：切换数据集配置
switchDataset.disabled
- 类型：boolean
- 默认值：true
- 描述：控制自助取数编辑页面中是否能切换数据集。

EmbedRouteKey.formEdit

数据填报编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示

EmbedRouteKey.etlEdit

数据准备编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
publish：发布按钮特性配置
publish.show
- 类型：boolean
- 默认值：true
- 描述：控制发布按钮是否显示
offline：下线按钮特性配置
offline.show
- 类型：boolean
- 默认值：true
- 描述：控制下线按钮是否显示
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示

EmbedRouteKey.datasetEdit

数据集编辑页特性配置，属性控制范围如下。

goBack：返回按钮特性配置
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示
saveAs：另存为按钮特性配置
saveAs.group
- 类型：'state' | 'menu'
- 默认值：'menu'
- 描述：控制另存为按钮所属组别，'menu'表示位于更多菜单内，'state'表示位于保存发布状态区
saveAs.order
- 类型：number
- 默认值：-1
- 描述：控制另存为按钮在按钮组内的顺序
saveAs.type
- 类型：'default' | 'primary'
- 默认值：'default'
- 描述：控制另存为按钮的样式，仅属于'state'组时生效
save：保存按钮特性配置。
save.show
- 类型：boolean
- 默认值：true
- 描述：保存按钮是否显示

EmbedRouteKey.workbookFormTask

电子表格填报审批页面特性配置，属性控制范围如下。

header：电子表格填报审批页面头部特性配置
header.show
- 类型：boolean
- 默认值：true
- 描述：控制页面头部导航是否展示
goBack：返回按钮特性配置。
goBack.show
- 类型：boolean
- 默认值：true
- 描述：控制返回按钮是否显示

EmbedRouteKey.dashboardView/EmbedRouteKey.dashboardPublicView

仪表板预览页（dashboardView）和仪表板公开页（dashboardPublicView）的特性配置，属性控制范围如下。

title：仪表板标题特性配置
title.show
- 类型: boolean
- 默认值: false
- 描述：仪表板标题是否显示，嵌入使用时默认不显示标题，可以通过该特性让标题显示。
miniMenu：仪表板的迷你菜单特性配置
miniMenu.show
- 类型: boolean
- 默认值: true
- 描述：仪表板的迷你菜单是否显示
cardMenu：图表卡片菜单的特性配置
cardMenu.show
- 类型: boolean
- 默认值: true
- 描述：仪表板的图表卡片菜单是否显示
highlight：高亮卡片特性配置
highlight.componentIds
- 类型: string[]
- 描述：需要高亮的卡片id
  说明
  componentIds可以通过开放API（QueryWorksBloodRelationship - 查询数据作品的血缘信息）获取，或者通过页面的/api/v2/dashboard接口获取。

events

用于监听嵌入页面行为事件的配置对象。通过绑定事件，宿主系统可以捕获嵌入页面的动作并做出响应。目前开放了页面前跳转事件before-page-change-event，从QuickBI跳转到新开页面前触发，例如：从仪表板列表页跳转到仪表板编辑页。

event 事件回调入参为EmbedEventBeforePageChange

type EmbedEventBeforePageChange = {
  type: EmbedEventType['before-page-change-event'],
  payload: {
    src: EmbedSrcUnion,
    target: '_blank' | '_self'
  }
}

event.payload.src: 即将要跳转的页面的源信息，具体说明请参见src。
event.payload.target: 即将要打开页面的方式,_blank 将在新窗口打开,_self 将在当前页打开。

return 当事件回调函数返回false时，会阻止Quick BI的默认跳转逻辑，示例代码如下。

embedClient.on(EmbedEventType['before-page-change-event'], async (event: EmbedEventBeforePageChange) => {
  // 阻值跳转新页面
  if (event.payload.target === '_blank') {
    return false;
  }
})

action

描述宿主系统与嵌入页面之间交互行为的配置对象。通过 action，宿主可以主动触发嵌入页的行为（例如跳转页面、更新特性等）。

目前开放了路由跳转（embedNavigate）、更新嵌入特性（setEmbedFeature）和滚动页面（scrollToComponentById）行为。

enum EmbedActionType {
  /** 路由跳转 */
  embedNavigate = 'embedNavigate',
  /** 更新嵌入特性 */
  setEmbedFeature = 'setEmbedFeature',
}

/** 嵌入行为-主动触发路由跳转 */
type EmbedActionNavigate = {
  type: EmbedActionType.embedNavigate;
  payload: {
    src: EmbedSrcUnion;
  }
}

/** 嵌入行为-主动触发更新特性 */
type EmbedActionSetFeature = {
  type: EmbedActionType.setEmbedFeature;
  payload: EmbedFeatureIntersect;
}

embedNavigate

描述：让嵌入页跳转到指定路由。

payload.src：要跳转的路由源信息，具体说明请参见src。

type EmbedActionNavigate = {
  type: EmbedActionType.embedNavigate;
  payload: {
    src: EmbedSrcUnion;
  }
}

示例代码

// 跳转到仪表板编辑页
embedClient.dispatch({
  type: EmbedActionType.embedNavigate,
  payload: {
    src: {
      origin: 'https://bi.aliyun.com',
      page: EmbedRouteKey.dashboardEdit,
      search: {
        workspaceId: 'xx',
        id: 'xx'
      },
    },
  },
});

setEmbedFeature

描述：更新嵌入页的嵌入特性配置。

payload：各个页面的嵌入特性配置，具体说明请参见feature。

type EmbedActionSetFeature = {
  type: EmbedActionType.setEmbedFeature;
  payload: EmbedFeatureIntersect;
}

示例代码

embedClient.dispatch({
  type: EmbedActionType.setEmbedFeature,
  payload: {
    // 隐藏仪表板编辑页的返回按钮
    [EmbedRouteKey.dashboardEdit]: {
      goBack: {
        show: goBack,
      },
    },
  },
});

scrollToComponentById

描述：在仪表板预览页，公开页，控制嵌入页面滚动到指定的图表组件处。
payload
- payload.id需要滚动到的卡片的位置
- payload.position该卡片位置

type EmbedActionScrollToComponentById = {
  type: EmbedActionType.scrollToComponentById,
  payload: {
    id: string;
    position: 'start' | 'center' | 'end' | 'nearest'
  }
}

示例：

embedClient.dispatch({
  type: EmbedActionType.scrollToComponentById,
  payload: {
    // 滚动仪表板预览页到该组件id处
    id: 'scroll to this component id',
    // 滚动后该卡片位于屏幕中间
    position: 'center',
  },
});

开发方式

在不同开发环境下，通过嵌入 JS SDK配置嵌入页面来源、特性等功能的方式不同，例如：在通用JS环境下（即无框架环境）开发者需要使用EmbedClient类创建客户端实例后，进行配置；在React、Vue框架环境下，开发者则需要通过渲染EmbedComponent组件配置嵌入源。

以下将为您分别介绍如何通过EmbedClient类、EmbedComponent组件自定义配置嵌入页面。

EmbedClient

您可以使用以下方式，通过EmbedClient类完成对嵌入页面的个性化开发。

方式	说明
constructor	用于构造一个新的嵌入客户端实例。
render	用于嵌入客户端实例渲染到指定DOM容器中。
destroy	用于嵌入客户端实例销毁嵌入页。
dispatch	用于触发嵌入行为。
on	用于注册嵌入事件监听。
off	用于注销嵌入事件监听。

constructor

用于构造一个新的嵌入客户端实例。

类型：(src: EmbedSrcUnion, option?: Partial<PostMessengerParam>) => void
参数
- src：嵌入源信息，描述要嵌入的页面，具体说明请参见src。
- option：客户端选项配置
  - option.connectTimeout：客户端链接超时时间。
  - option.messageTimeout：消息超时时长。

示例代码

const embedClient = new EmbedClient({
  src: {
    origin: 'https://bi.aliyun.com',
    page: EmbedRouterKey.dashboardView,
  },
  option: { connectTimeout: 5000 }
});

render

用于嵌入客户端实例渲染到指定DOM容器中。

类型：(container: HTMLIframeElement) => HTMLIFrameElement
参数
- container ：用于渲染嵌入页的DOM元素。

示例代码

embedClient.render(document.getElementById('embed-container'));

destroy

用于嵌入客户端实例销毁嵌入页。

类型：() => void
示例代码
```
embedClient.destroy();
```

dispatch

用于触发嵌入行为。

类型：(action: EmbedAction) => Promise<T>
参数
- action：嵌入行为类型, 具体说明请参见action。

示例代码

// 隐藏仪表板编辑页的返回按钮
embedClient.dispatch({
  type: EmbedActionType.setEmbedFeature,
  payload: {
    [EmbedRouteKey.dashboardEdit]: {
      goBack: {
        show: goBack,
      },
    },
  },
});

on

用于注册嵌入事件监听。

类型：on(eventType: EmbedEventType, listener: (event: T) => Promise<T>)
参数
- eventType：事件类型 EmbedEventType。
- listener：事件回调，支持异步函数，不同事件接收的入参和返回值不同，具体说明请参见events。

示例代码

// 页面跳转前事件
async handler(event: EmbedEventBeforePageChange) => {
  return false;
}

// 绑定事件
embedClient.on(EmbedEventType['before-page-change-event'], handler);

off

用于注销嵌入事件监听。

类型：on(eventType: EmbedEventType, listener)。
参数
- eventType：事件类型 EmbedEventType。
- listener：事件回调，支持异步函数，不同事件接收的入参和返回值不同，具体说明请参见events。

示例代码

async handler function(payload) {}

// 解绑事件
embedClient.off(EmbedEventType['before-page-change-event'], handler);

EmbedComponent

在React或Vue框架下，通过渲染组件EmbedComponent进行页面嵌入。该组件属性props类型如下所示，更新该组件的属性，会自动触发组件更新，渲染最新的页面。

interface EmbedComponentCommonProps {
  /** 容器类名 */
  className?: string;
  /** 容器样式 */
  style?: CSSProperties;
  /** 嵌入源信息 */
  src: EmbedSrcUnion;
  /** 嵌入初始特性配置 */
  feature?: EmbedFeatureIntersect;
  /** 嵌入初始事件监听 */
  events?: EmbedEventListenerUnion;
}

其参数说明如下。

参数	类型	是否必填	描述
props.className	`string`	否	嵌入组件的类名。
props.style	`CSSProperties`	否	嵌入组件的样式。
props.src	`EmbedSrcUnion`	是	嵌入的Quick BI页面源信息，具体说明请参见src。
props.feature	`EmbedFeatureIntersect`	否	嵌入初始特性配置，具体说明请参见feature。
props.events	`EmbedEventListenerUnion`	否	嵌入初始事件监听，具体说明请参见events。

参考文档

您可以通过具体的开发示例，来更进一步理解嵌入SDK的使用方式。