本文为您详细介绍嵌入 JS SDK中包含的API接口。
功能配置项
嵌入 JS SDK中包含的功能配置接口主要分为：src、feature、events、action，接口的相关说明如下：
功能配置项 | 描述 | 是否必填 | 场景举例 |
嵌入页面的来源信息，定义嵌入的具体页面及其参数。 | 是 | 指定嵌入的页面为仪表板编辑页。 | |
控制嵌入页面组件的显隐状态，以及修改展示文本等展示类特性的配置。 | 否 | 隐藏嵌入的Quick BI页面的头部。 | |
嵌入页面的行为事件监听器。 | 否 | 监听从仪表板编辑页跳转返回仪表板列表。 | |
宿主系统触发嵌入页面行为的配置。 | 否 | 宿主系统控制Quick BI跳转到新的页面。 |
src
嵌入源信息，用于生成嵌入页面。其类型为 EmbedSrcUnion，包含的参数如下表所示：
参数 | 类型 | 是否必填 | 描述 |
src.page |
| 是 | Quick BI 每个作品页、列表页的每个Tab页都可以视为一个路由，例如：仪表板预览页,、仪表板编辑页、工作台仪表板列表页等。 该项代表需要嵌入页面的路由键，例如：嵌入仪表板预览页时，需要设置page为 |
src.origin |
| 是 | 您访问Quick BI的 |
src.search |
| 否 | 嵌入Quick BI页面的查询参数，一些页面需要传入参数配合使用。例如：工作空间页面需要传入工作空间编号 |
src.pathParams |
| 否 | 嵌入Quick BI页面的路径参数，目前只有少量页面需要传入该参数，例如数据填报编辑页和预览页的作品ID是通过路径参数传入的，因此需要设置传入 |
示例代码
<EmbedComponent
src={
origin: 'xxx', // 访问qbi的host
page: EmbedRouteKey.dashboardEdit, // 仪表板编辑页对应的EmbedRouteKey
// 访问qbi仪表板页面的查询参数
search: {
workspaceId: 'xxx', // 空间ID
id: 'xxx', // 作品ID
}
}
/>feature
嵌入特性（feature）是用于临时控制页面组件的显隐状态， 以及修改展示文本等展示类特性的配置。例如：可以隐藏页面头部等。其类型为 EmbedFeatureIntersect，结构分为三层：路由 > 功能模块 > 特性配置项，其中路由层的key是EmbedRouteKey，表示特性生效的范围，示例代码如下。
feature: {
[路由key]: {
[功能模块]: {
[特性配置项key]: value
}
}
}此外，还有特殊的二层结构的特性，其对应结构为：路由 > 特性配置项，该二层结构的特性用于控制路由对应模块是否展示，示例代码如下。
feature: {
[路由key]: {
[特性配置项key]: value
}
}不同路由下的特性可以同时配置。可传入的路由参数如下表所示：
路由Key | 说明 |
用于控制根页面的特性。 | |
用于控制工作空间页面的特性。 | |
用于控制工作台页面的特性。 | |
用于控制监控告警管理页面的特性。 | |
用于控制仪表板编辑页面的特性。 | |
用于控制电子表格编辑页面的特性。 | |
用于控制数据大屏编辑页面的特性。 | |
用于控制即席分析编辑页面的特性。 | |
用于控制自助取数编辑页面的特性。 | |
用于控制数据填报编辑页面的特性。 | |
用于控制数据准备编辑页面的特性。 | |
用于控制数据集编辑页面的特性。 | |
用于控制电子表格填报审批页面的特性。 | |
用于控制仪表板预览页面的特性。 | |
用于控制仪表板公开页面的特性。 | |
用于控制电子表格公开页、预览页的特性。 | |
用于控制即席分析公开页、预览页的特性。 | |
用于控制自助取数公开页、预览页的特性。 | |
用于控制订阅管理页特性配置。 | |
用于控制订阅任务页面特性配置。 | |
用于控制发送记录页面特性配置。 | |
用于控制组织管理页面特性。 | |
用于控制成员管理页面特性。 | |
用于控制用户组管理页面特性。 | |
用于控制用户标签管理页面特性。 | |
用于控制用户标签页面特性 | |
用于控制标签管理页面特性。 | |
用于控制角色管理页面特性。 | |
用于控制智能小Q页面特性。 | |
用于控制小Q问数页面特性。 | |
用于控制小Q报告页面特性。 | |
用于控制小Q报告编辑页的页面特性。 |
示例代码
<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默认值：
false描述：控制仪表板编辑页面是否禁用切换数据集。
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默认值：
false描述：控制电子表格编辑页面中是否禁用切换数据集。
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默认值：
false描述：控制大屏编辑页面是否禁用切换数据集。
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默认值：
false描述：控制即席分析编辑页面是否禁用切换数据集。
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默认值：
false描述：控制自助取数编辑页面是否禁用切换数据集。
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（查询数据作品的血缘信息）获取，或者通过页面的/api/v2/dashboard接口获取。
EmbedRouteKey.workbookView/EmbedRouteKey.workbookPublicView
电子表格预览页（workbookView）和电子表格公开页（workbookPublicView）的特性配置，属性控制范围如下。
download：电子表格导出功能
download.show
类型：
boolean默认值：
true描述：电子表格导出功能入口是否展示
offlineDownload：电子表格内自助取数功能
offlineDownload.show
类型：
boolean默认值：
true描述：电子表格内自助取数功能入口是否展示
EmbedRouteKey.analysisView/EmbedRouteKey.analysisPublicView
即席分析预览页（analysisView）和即席分析公开页（analysisPublicView）的特性配置，属性控制范围如下。
download：即席分析导出功能
download.show
类型：
boolean默认值：
true描述：即席分析导出功能入口是否展示
EmbedRouteKey.downloadView/EmbedRouteKey.downloadPublicView
自助取数预览页（workbookView）和自助取数公开页（workbookPublicView）的特性配置，属性控制范围如下。
taskListPanel：取数任务列表面板
taskListPanel.show
类型：
boolean默认值：
true描述：取数任务列表面板是否展示
EmbedRouteKey.subscriptionManage
订阅管理页特性配置，属性控制范围如下。
header：订阅管理页头部特性配置。
header.show
类型：
boolean默认值：
true描述：控制订阅管理页头部是否显示，该特性优先级高于EmbedRouteKey.homeRoot.show。
EmbedRouteKey.subscriptionTask
订阅任务页面特性配置，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制订阅任务页面是否显示。
EmbedRouteKey.sendRecord
发送记录页面特性配置，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制发送记录页面是否显示。
EmbedRouteKey.orgAdmin
组织管理页面特性，属性控制范围如下。
header：组织管理页头部特性配置。
header.show
类型：
boolean默认值：
true描述：控制组织管理页头部是否显示，该特性优先级高于EmbedRouteKey.homeRoot.show。
sideNav：组织管理页左侧导航特性配置。
sideNav.show
类型：
boolean默认值：
true描述：控制组织管理页左侧导航是否显示。
EmbedRouteKey.userMemberManage
成员管理页面特性，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制成员管理页面是否显示。
EmbedRouteKey.userGroupManage
用户组管理页面特性，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制用户组管理页面是否显示。
EmbedRouteKey.userTagManage
用户标签管理页面特性，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制用户标签管理页面是否显示。
EmbedRouteKey.userTagDetailManage
用户标签页面特性，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制用户标签页面是否显示。
EmbedRouteKey.tagManage
标签管理页面特性，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制标签管理页面是否显示。
EmbedRouteKey.userRoleManage
角色管理页面特性，具有如下属性。
show
类型：
boolean默认值：
true描述：该特性为二层结构特性，用于控制角色管理页面是否显示。
EmbedRouteKey.copilotPage
智能小Q页面特性，具有如下属性。
header：智能小Q页头部特性配置。
header.show
类型：
boolean默认值：
true描述：控制智能小Q页头部是否显示，该特性优先级高于
EmbedRouteKey.homeRoot.header.show。
sideNav：智能小Q左侧导航特性配置。
sideNav.show
类型：
boolean默认值：
true描述：控制智能小Q页左侧导航是否显示。
theme：智能小Q主题特性配置。
theme.primaryColor
类型：
string默认值：
#2F66FF描述：控制智能小Q页面主题色。
theme.chartColorSeries
类型：
string[]默认值：[
'#4080FF',
'#3DC8DC',
'#A191F2',
'#FFB77A',
'#7C7CA6',
'#33CC99',
'#217CCC',
'#FF80AA',
'#008770',
'#D1876F',
'#4798B3',
'#C896FA']
描述：控制智能小Q页面内图表的色系。
EmbedRouteKey.copilotPageQChat
小Q问数页面特性，具有全部EmbedRouteKey.copilotPage特性，并且优先级更高，此外还具有如下特性属性。
dataInterpretation：小Q问数数据解读功能配置。
dataInterpretaion.show
类型：
boolean默认值：
true描述：控制小Q问数页面是否显示数据解读功能。
EmbedRouteKey.copilotPageQReport
小Q报告页面特性，具有全部EmbedRouteKey.copilotPage特性，并且优先级更高。
EmbedRouteKey.wordAgentEdit
小Q报告编辑页页面特性，具有如下属性。
goBack：小Q报告返回按钮配置。
goBack.show
类型：
boolean默认值：
true描述：控制小Q报告编辑页是否显示返回按钮。
events
用于监听嵌入页面行为事件的配置对象。通过绑定事件，宿主系统可以捕获嵌入页面的动作并做出响应。
目前开放了以下事件：
事件名称 | 说明 |
页面跳转前事件 | 从Quick BI跳转到新开页面前触发，用于监听应用内所有的跳转方法。例如：从仪表板列表页跳转到仪表板编辑页。 |
图表渲染后事件 | 在仪表板预览页、编辑页等页面渲染图表卡片后触发，例如：仪表板预览页中，因为Quick BI从性能考虑对图表进行了懒加载，所以在向下滚动的过程中，出现在视窗的图表会触发图表渲染后事件。 |
before-page-change-event
描述：页面跳转前事件，从Quick BI跳转到新开页面前触发，例如：从仪表板列表页跳转到仪表板编辑页。
该事件回调入参为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;
}
})after-component-rendered-event
描述：图表渲染后的事件，在仪表板预览页、编辑页等页面渲染图表卡片后触发，例如：仪表板预览页中，因为Quick BI从性能考虑对图表进行了懒加载，所以在向下滚动的过程中，出现在视窗的图表会触发图表渲染后事件。
该事件回调入参为EmbedEventAfterComponentRendered。
type EmbedEventAfterComponentRendered = {
type: EmbedEventType['after-component-rendered-event'],
customProps: ComponentProps
}其中customProps包含了图表和页面的相关信息，其接口如下所示。
export interface ComponentProps {
status?: 'success' | 'error';
error?:
| ComponentError
| ComponentConfigError
| ComponentNoPermissionError
| ComponentDataMaskError
| ComponentNoDataError
| ComponentRenderError;
pageConfig?: ComponentPageConfig;
id: string;
data: DataCell[][];
dataConfig: AreaModel[];
viewConfig: ComponentPropsViewConfig;
advancedConfig: object;
globalConfig: ComponentPropsGlobalConfig;
cubeConfig?: ComponentPropsCubeConfig[];
sql?: string[];
}customProps.status
图表组件状态，有错误时会返回
error，正常渲染则返回success。customProps.error
图表组件出错时返回的错误类型，目前分为六类，其中
ComponentError表示未知错误，具体错误分类如下所示。/** 默认为 'ComponentError' 表示未知错误 */ export interface ComponentError<T extends string = 'ComponentError'> { /** 错误名称，用于类型判断 */ name: T; /** 错误信息 */ message?: string; } /** 图表配置错误 */ export type ComponentConfigError = ComponentError<'ComponentConfigError'>; /** 权限错误 */ export type ComponentNoPermissionError = ComponentError<'ComponentNoPermissionError'>; /** 数据脱敏错误 */ export type ComponentDataMaskError = ComponentError<'ComponentDataMaskError'>; /** 数据为空错误 */ export type ComponentNoDataError = ComponentError<'ComponentNoDataError'>; /** 渲染错误 */ export type ComponentRenderError = ComponentError<'ComponentRenderError'>;customProps.pageConfig
组件所处页面的相关信息，其接口信息如下所示。
interface CustomEventPageConfig { /** 页面工作空间 id */ workspaceId: string; /** 页面 id */ id: string; /** 页面模式, 编辑态/预览态/截图态(仅仪表板和电子表格有)/公开态(数据大屏) */ mode: 'preview' | 'edit' | 'snapshot' | 'public'; /** 当前设备 */ device: 'pc' | 'mobile'; /** 当前访问者 id */ userId: string; /** 当前访问者 id */ userName: string; /** 当前访问者 昵称 */ nickName?: string; /** 页面创建者 id */ ownerUserId: string; /** 页面创建者 id */ ownerUserName: string; /** 页面标题 */ title: string; /** 页面类型 */ pageType: 'dashboard' | 'webExcel' | 'screen' | 'offline' | 'analysis'; }customProps.id
id返回的是组件的实例编号。
customProps.data
图表组件的渲染数据，其数据结构是一个二维数组。
interface DataCell { fieldId: string; originValue: string; value: string; geoInfo?: object; }fieldId：数据字段ID，与dataConfig中的ID一一对应。originValue：数据的原始值。value：数据的展示值。geoInfo：维度字段的地理信息。
customProps.dataConfig
图表数据面板的数据字段配置，其接口如下所示。
interface AreaModel { areaType: 'row' | 'column' | 'drill' | 'filter'; fields: FieldModel[]; }areaType：字段类型，可能有以下几种取值。row：维度类型字段。column：度量类型字段。drill：钻取类型字段。filter：过滤器类型字段。
fields：字段数组，同一种字段类型下可能有多个字段。其接口如下所示。interface FieldModel { /** 唯一Id */ fieldId: string; /** 字段名 */ fieldName: string; /** 最终展示别名 */ showName: string; /** 是否计算字段 */ isCalc?: boolean; /** 如：calc */ skin?: string; /** 值的类型 */ valueType?: FieldValueType; /** 字段类型: 维度或度量 */ fieldType: FieldCommonType; /** 聚合方式 */ aggregation?: FieldAggregation | string; /** [QBI特有] 数据渲染形式，目前有imageUrl用于交叉表、排行榜图片渲染 */ displayType?: 'imageUrl' | ''; /** [QBI特有] 数据集格式化配置，如#,##0.00% */ rawFormat?: string; /** [QBI特有] 数据集维度类型, TimeRegionInBackend, 需迁移，防止循环依赖 */ dimGranularity?: any; /** 最终格式化配置（注：qbi目前是放在styleConfig中，该字段并未被使用） */ /** ！！首先得产品层面统一 */ format?: QbiFormatModel | FbiFormatModel; /** 排序 */ order?: FieldOrder; /** 高级计算：同环比等 */ advancedCalculation?: 'year-to-year' | 'month-to-year'; /** 当前图表的过滤条件集合 */ complexFilter: { limitNum: number; filter: any; }; // 真·字段唯一标识 uuid: string; /** 不同图表字段特殊扩展信息 */ extends?: FieldModelExtends; }
customProps.viewConfig
图表样式面板的数据，其接口如下所示。
interface ComponentPropsViewConfig { caption?: string; chartColorSeries?: { key: string; name: string; colors: string[]; }; chartSkin?: { key: 'black' | 'default'; }; title?: { show: boolean; viceName?: string; color?: string; showLink?: boolean; link?: string; linkName?: string; }; fieldSettingMap?: { [fieldId: string]: ComponentPropsFieldSettingConfig }; width?: number; height?: number; [key: string]: any; }caption：组件主标题。title：组件标题配置。title.show：是否显示主标题/备注。title.viceName：主标题备注。title.color：主标题颜色。title.showLink：是否展示链接跳转。title.link：跳转链接地址。title.linkName：跳转链接文案。
chartColorSeries：仪表板主题色系。chartColorSeries.key：主题色系key。chartColorSeries.name：主题色系名称。chartColorSeries.colors：主题色系颜色，共有10种颜色。
chartSkin：仪表板皮肤。
chartSkin.key：仪表板皮肤key。default代表浅色版。black代表深色版。fieldSettingMap字段展示设置，例如字段别名，数据展示格式等配置都存放在其中。其接口为：interface ComponentPropsFieldSettingConfig { aliasName: string; numberFormat: NumberFormat; [key: string]: any; }height：自定义图表高度。width：自定义图表宽度。
customProps.globalConfig
图表全局配置数据，该部分内容正在建设中。
customProps.advancedConfig
图表高级面板配置，该部分内容正在建设中。
customProps.cubeConfig
图表数据集配置，其数据结构是一个二维数组。
interface ComponentPropsCubeConfig { /** 数据集ID */ cubeId: string; /** 数据集名称 */ cubeName: string; }customProps.sql
图表查询SQL，其数据结构是一个字符串二维数组。
action
描述宿主系统与嵌入页面之间交互行为的配置对象。通过 action，宿主可以主动触发嵌入页的行为（例如跳转页面、更新特性等）。目前开放了以下行为。
行为 | 说明 |
路由跳转 | 让嵌入页跳转到指定路由。 |
更新嵌入特性 | 更新嵌入页的嵌入特性配置。 |
滚动页面 | 在仪表板预览公开页，控制嵌入页面滚动到指定的图表组件处。 |
获取导出配置 | 获取当前嵌入页面支持的导出格式列表。 适用于仪表板、电子表格、即席分析、自助取数。 |
触发导出下载 | 触发导出下载。 对于仪表板/电子表格/即席分析为同步下载文件；对于自助取数为创建取数任务（异步）。 |
获取仪表板图表组件树 | 获取仪表板中图表组件的树形结构，用于「Excel 部分内容导出」时让用户选择要导出的图表。 仅适用于仪表板。 |
获取自助取数任务列表 | 获取当前自助取数作品的取数任务列表。 仅适用自助取数页面。 |
触发自助取数任务文件下载 | 下载指定取数任务的文件。 仅适用自助取数页面。 |
enum EmbedActionType {
/** 路由跳转 */
embedNavigate = 'embedNavigate',
/** 更新嵌入特性 */
setEmbedFeature = 'setEmbedFeature',
/** 滚动页面到指定组件 */
scrollToComponentById = 'scrollToComponentById',
/** 获取导出配置 */
getDownloadConfig = 'getDownloadConfig',
/** 触发导出下载 */
triggerDownload = 'triggerDownload',
/** 获取图表组件树 */
getComponentsTree = 'getComponentsTree',
/** 获取自助取数任务列表 */
getFetchTaskList = 'getFetchTaskList',
/** 触发自助取数任务文件下载 */
triggerFetchTaskDownload = 'triggerFetchTaskDownload',
}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
描述：在仪表板预览页、公开页，控制嵌入页面滚动到指定的图表组件处。
payloadpayload.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',
},
});getDownloadConfig
描述：获取当前嵌入页面支持的导出格式列表。适用于仪表板、电子表格、即席分析、自助取数。
返回值说明
formats：当前页面可用的导出格式数组，可能的取值如下：仪表板 'excel'、'image'、'pdf'
电子表格 'excel'、'pdf'
即席分析 'excel'、'image'
自助取数 'excel'、'excelWithFormat'、'csv'、'csvWithFormat'
/** 嵌入行为-获取导出配置 */ type EmbedActionGetDownloadConfig = { type: EmbedActionType.getDownloadConfig; } /** 返回值 */ type GetDownloadConfigResult = { formats: string[]; }示例代码：
const config = await embedClient.dispatch({ type: EmbedActionType.getDownloadConfig }); console.log(config.formats); // ['excel', 'image', 'pdf']
triggerDownload
描述：触发导出下载。对于仪表板/电子表格/即席分析为同步下载文件；对于自助取数为创建取数任务（异步）。
payloadpayload.format：导出格式，必填。具体可选值取决于模块类型（可先通过getDownloadConfig获取）。payload.contentList：仅仪表板 Excel 导出时使用，传入要导出的组件 ID 数组，可通过getComponentsTree获取可选组件。不传则导出全部。payload.taskName：仅自助取数时使用，指定取数任务名称。不传则使用默认名称。
/** 嵌入行为-触发导出下载 */ type EmbedActionTriggerDownload = { type: EmbedActionType.triggerDownload; payload: { /** * 导出格式 * - 仪表板/电子表格/即席分析：'excel' | 'image' | 'pdf' * - 自助取数：'excel' | 'excelWithFormat' | 'csv' | 'csvWithFormat' */ format: 'excel' | 'image' | 'pdf' | 'excelWithFormat' | 'csv' | 'csvWithFormat'; /** 仪表板 Excel 部分内容导出：组件 ID 列表（不传则导出全部） */ contentList?: string[]; /** 自助取数创建取数任务的任务名称（不传则使用默认名称） */ taskName?: string; } } /** 返回值 */ type TriggerDownloadResult = { success: boolean; }示例代码：
// 仪表板 - 导出全部 Excel await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'excel' }, }); // 仪表板 - 导出部分图表的 Excel（需先通过 getComponentsTree 获取组件 ID） await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'excel', contentList: ['component-id-1', 'component-id-2'], }, }); // 仪表板 - 导出图片 await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'image' }, }); // 仪表板 - 导出 PDF await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'pdf' }, }); // 电子表格 - 导出 Excel await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'excel' }, }); // 即席分析 - 导出图片 await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'image' }, }); // 自助取数 - 创建取数任务 await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'excel', taskName: '我的取数任务', }, });
getComponentsTree
描述：获取仪表板中图表组件的树形结构，用于「Excel 部分内容导出」时让用户选择要导出的图表。仅仪表板支持。
返回值说明
components：图表组件树，按仪表板布局排序。type：图表类型标识，可用于在外层过滤只导出特定图表类型（如仅导出明细表detail_table、交叉表cross_table）。TAB 展开的子项不带type。disabled：为true表示该节点为非图表类型（如筛选器、文本等），不可选择导出。
/** 嵌入行为-获取图表组件树 */ type EmbedActionGetComponentsTree = { type: EmbedActionType.getComponentsTree; } /** 返回值 */ type GetComponentsTreeResult = { components: Array<{ /** 组件 ID，传给 triggerDownload.contentList */ id: string; /** 组件标题 */ title: string; /** 图表类型（如 'line'、'bar'、'cross_table'、'detail_table' 等） */ type?: string; /** 子组件（TAB 容器下的图表） */ children?: Array<...>; /** 是否禁用（非图表类型不可选择导出） */ disabled?: boolean; }>; }示例代码：
// 获取图表组件树 const tree = await embedClient.dispatch({ type: EmbedActionType.getComponentsTree, }); console.log(tree.components); // [ // { id: 'chart-1', title: '销售趋势', type: 'line', disabled: false }, // { id: 'chart-2', title: '区域分布', type: 'cross_table', disabled: false }, // { id: 'tab-1', title: 'TAB容器', children: [ // { id: 'chart-3', title: '明细数据', disabled: false }, // ]}, // { id: 'filter-1', title: '日期筛选', disabled: true }, // ] // 配合 triggerDownload 使用：仅导出交叉表和明细表 const tableIds = tree.components .filter(node => !node.disabled && ['cross_table', 'detail_table'].includes(node.type)) .map(node => node.id); await embedClient.dispatch({ type: EmbedActionType.triggerDownload, payload: { format: 'excel', contentList: tableIds }, });
getFetchTaskList
描述：获取当前自助取数作品的取数任务列表。仅自助取数页面支持。
返回值说明
tasks：取数任务列表。status：任务状态枚举，取值如下：status
含义
canDownload
0
取数中
false
1
完成取数
true
2
取数失败
false
3
审批中
false
4
已拒绝
false
5
已下载
true
payload.keyword：可选，按任务名称模糊搜索。示例代码：
// 获取全部任务 const res = await embedClient.dispatch({ type: EmbedActionType.getFetchTaskList, }); console.log(res.tasks); // [ // { downloadId: 'xxx', downloadName: '销售数据', status: 1, gmtCreate: '2025-06-01 10:00', canDownload: true }, // { downloadId: 'yyy', downloadName: '库存报表', status: 0, gmtCreate: '2025-06-01 11:00', canDownload: false }, // ] // 按关键字搜索 const filtered = await embedClient.dispatch({ type: EmbedActionType.getFetchTaskList, payload: { keyword: '销售' }, });
triggerFetchTaskDownload
描述：下载指定取数任务的文件。仅当任务
canDownload为true（状态为「完成取数」或「已下载」）时有效。仅自助取数页面支持。
/** 嵌入行为-触发取数任务文件下载 */
type EmbedActionTriggerFetchTaskDownload = {
type: EmbedActionType.triggerFetchTaskDownload;
payload: {
/** 取数任务 ID，来自 getFetchTaskList 返回的 downloadId */
downloadId: string;
}
}
/** 返回值 */
type TriggerFetchTaskDownloadResult = {
success: boolean;
}
payloadpayload.downloadId：取数任务 ID，必填。来自getFetchTaskList返回结果中的downloadId字段。示例代码
// 下载指定任务 const result = await embedClient.dispatch({ type: EmbedActionType.triggerFetchTaskDownload, payload: { downloadId: 'xxx' }, }); console.log(result.success); // true
开发方式
在不同开发环境下，通过嵌入 JS SDK配置嵌入页面来源、特性等功能的方式不同，例如：在通用JS环境下（即无框架环境）开发者需要使用EmbedClient类创建客户端实例后，进行配置；在React、Vue框架环境下，开发者则需要通过渲染EmbedComponent组件配置嵌入源。
以下将为您分别介绍如何通过EmbedClient类、EmbedComponent组件自定义配置嵌入页面。
EmbedClient
您可以使用以下方式，通过EmbedClient类完成对嵌入页面的个性化开发。
方式 | 说明 |
用于构造一个新的嵌入客户端实例。 | |
用于嵌入客户端实例渲染到指定DOM容器中。 | |
用于嵌入客户端实例销毁嵌入页。 | |
用于触发嵌入行为。 | |
用于注册嵌入事件监听。 | |
用于注销嵌入事件监听。 |
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 |
| 否 | 嵌入组件的类名。 |
props.style |
| 否 | 嵌入组件的样式。 |
props.src |
| 是 | 嵌入的Quick BI页面源信息，具体说明请参见src。 |
props.feature |
| 否 | 嵌入初始特性配置，具体说明请参见feature。 |
props.events |
| 否 | 嵌入初始事件监听，具体说明请参见events。 |
参考文档
您可以通过具体的开发示例，来更进一步理解嵌入SDK的使用方式。