本文为您详细介绍嵌入 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 | 说明 |
用于控制根页面的特性。 | |
用于控制工作空间页面的特性。 | |
用于控制工作台页面的特性。 | |
用于控制监控告警管理页面的特性。 | |
用于控制仪表板编辑页面的特性。 | |
用于控制电子表格编辑页面的特性。 | |
用于控制数据大屏编辑页面的特性。 | |
用于控制即席分析编辑页面的特性。 | |
用于控制自助取数编辑页面的特性。 | |
用于控制数据填报编辑页面的特性。 | |
用于控制数据准备编辑页面的特性。 | |
用于控制数据集编辑页面的特性。 | |
用于控制电子表格填报审批页面的特性。 | |
用于控制仪表板预览页面的特性。 | |
用于控制仪表板公开页面的特性。 | |
用于控制订阅管理页特性配置。 | |
用于控制订阅任务页面特性配置。 | |
用于控制发送记录页面特性配置。 | |
用于控制组织管理页面特性。 | |
用于控制成员管理页面特性。 | |
用于控制用户组管理页面特性。 | |
用于控制用户标签管理页面特性。 | |
用于控制用户标签页面特性 | |
用于控制标签管理页面特性。 | |
用于控制角色管理页面特性。 |
示例代码
<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.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描述：该特性为二层结构特性，用于控制角色管理页面是否显示。
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'],
payload: ComponentProps
}其中payload包含了图表和页面的相关信息，其接口如下所示。
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[];
}status
图表组件状态，有错误时会返回
error，正常渲染则返回success。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'>;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'; }id
id返回的是组件的实例编号。
data
图表组件的渲染数据，其数据结构是一个二维数组。
interface DataCell { fieldId: string; originValue: string; value: string; geoInfo?: object; }fieldId：数据字段ID，与dataConfig中的ID一一对应。originValue：数据的原始值。value：数据的展示值。geoInfo：维度字段的地理信息。
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; }
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：自定义图表宽度。
globalConfig
图表全局配置数据，该部分内容正在建设中。
advancedConfig
图表高级面板配置，该部分内容正在建设中。
cubeConfig
图表数据集配置，其数据结构是一个二维数组。
interface ComponentPropsCubeConfig { /** 数据集ID */ cubeId: string; /** 数据集名称 */ cubeName: string; }sql
图表查询SQL，其数据结构是一个字符串二维数组。
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
描述：在仪表板预览页，公开页，控制嵌入页面滚动到指定的图表组件处。
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',
},
});开发方式
在不同开发环境下，通过嵌入 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的使用方式。