本文通过多个实际使用场景，帮助您进一步掌握嵌入JS SDK的使用方式。
设置嵌入权限
通过嵌入JS SDK进行页面集成，需要开发者在自己的系统内打通Quick BI的登录态，否则嵌入的页面首先会跳转到Quick BI的登录页。打通Quick BI登录态，可以获得更好的使用体验，您可以完成阿里云与自有系统的账户对接认证，打通方式参见文档阿里云SSO。
如果需要嵌入免登页面，请参见报表嵌入的基础方案。
React框架
以下为React框架环境下的开发示例。
示例一：嵌入工作空间
在宿主系统中嵌入Quick BI的工作空间页面，只需要在渲染EmbedComponent组件时，传入工作空间对应的源信息即可。
例如：在您访问某个工作空间的链接为https://xxx.com/workspace?workspaceId=yyy，则传入的源src如下所示。
import { EmbedComponent, EmbedRouteKey} from "@quickbi/bi-embed-client-react";
export const MyPage: React.FC = () => {
const src = {
origin: 'https://xxx.com',
page: EmbedRouteKey.workspace,
search: { workspaceId: 'yyy' }
};
return <EmbedComponent src={src} />
}得到的嵌入效果如下图所示：
示例二：设置头部隐藏
用户使用SDK嵌入时，需要对Quick BI页面进行多样化的定制需求，例如在嵌入场景下，通常用户自身系统就有一个头部，这时候就需要隐藏嵌入的Quick BI页面的头部，通过设置特性可以实现这个效果，代码如下所示。
export const SdkDemo: React.FC = () => {
return (
<EmbedComponent
src={src}
feature={{
[EmbedRouteKey.homeRoot]: {
header: {
show: false, // 具体参考 api
},
}}
/>
);上述代码实现的效果如下图所示，对比嵌入工作空间的案例，已经成功隐藏了头部导航栏。
示例三：调整按钮位置
有时候，用户需要自定义仪表板编辑页的按钮位置，例如想要隐藏发布、下线、分享按钮，同时把另存为按钮挪到保存按钮后，并作为主按钮，可以通过配置以下特性实现。
export const SdkDemo: React.FC = () => {
return (
<EmbedComponent
src={src}
feature={{
[EmbedRouteKey.dashboardEdit]: {
/** 发布按钮 */
publish: {
show: false
},
/** 下线按钮 */
offline: {
show: false
},
/** 分享按钮 */
share: {
show: false
},
/** 另存为按钮 */
saveAs: {
group: 'state',
order: 3,
type: 'primary'
}
}
}}
/>
);上述代码实现的效果如下图所示，仪表板编辑页头部的按钮从上方自定义成下方的样式。
示例四：注入路由跳转事件
目前已经通过嵌入了Quick BI的工作空间页面，并通过特性设置定制了该页面的头部隐藏效果。但是在这个页面内点击仪表板进行编辑时，会新开一个仪表板编辑页，这脱离了客户的宿主环境。因此还需要通过events参数注入路由跳转事件。
当Quick BI进行路由跳转时，监听到Quick BI跳转的目标，更新EmbedComponent组件的src参数，重新在当前页渲染EmbedComponent组件，保证新开的Quick BI页面也在客户的宿主环境中，具体代码如下所示。其中事件的返回值false是阻止Quick BI默认跳转逻辑，避免跳出客户的宿主环境。
export const SingleSdk: React.FC = () => {
return (
<EmbedComponent
src={src}
feature={{ ... }}
events={{
[EmbedEventType["before-page-change-event"]]: async (message: any) => {
/** 更新EmbedComponent的src属性，重新渲染跳转后的嵌入页面 */
setSrc(message.payload.src);
/** 阻止Quick BI的默认路由跳转逻辑 */
return false;
},
}}
/>
);
};
完整示例
下面是一个在React框架内，利用SDK进行嵌入集成的完整案例，示例代码可以参见如下codesandbox链接：codesandbox SDK DEMO
Vue框架
以下为Vue框架环境下的开发示例。
示例一：嵌入页面
以嵌入Quick BI 仪表板编辑页为例，导入相关npm包@quickbi/bi-embed-client-vue2后，传入仪表板编辑页对应的源信息，即可渲染导出的EmbedComponent组件：
<template>
<embed-component
:src="embedSrc"
:feature="embedFeature"
:events="embedEvents"
class="my-embed"
/>
</template>
<script lang="ts">
interface EmbedComponent {
/** 容器类名 */
className?: string;
/** 容器样式 */
style?: CSSProperties;
/** 嵌入源信息 */
src: EmbedSrcUnion;
/** 嵌入初始配置 */
feature?: EmbedFeatureIntersect;
/** 嵌入初始事件监听 */
events?: EmbedEventListenerUnion;
/** 客户端选项 */
option?: Partial<PostMessengerParam>;
}
export default Vue.extend({
name: 'SDK',
components: {
EmbedComponent
},
data(): EmbedComponent {
return {
embedSrc: {
origin: "https://xxx",
page: EmbedRouteKey.dashboardEdit,
search: {
workspaceId: '**-****-*****-********'，
id:"*************"
}
},
}
},
})
</script>
嵌入源信息参数说明见API章节；得到的嵌入效果如下图所示：
示例二：嵌入特性设置
在使用SDK嵌入Quick BI页面时，如果需要对嵌入页面进行多样化的定制，可以通过设置对应特性来实现，例如期望隐藏发布按钮和下线按钮，并调整另存为按钮的顺序和样式，则可以配置对应特性开关：
<script lang="ts">
export default Vue.extend({
data(): EmbedComponent {
return {
embedFeature: {
[EmbedRouteKey.dashboardEdit]: {
publish: {
show: false
},
//具体参考API 特性介绍部分
...
},
}
</script>
具体的特性设置参数说明请参见嵌入JS SDK API中的说明；得到的嵌入效果如下图所示：
示例三：嵌入事件监听
为了避免在嵌入环境中打开新页面跳出宿主环境，SDK暴露了一个路由跳转监听事件，可以对应用内所有的跳转方法进行监听，当进行路由跳转时，可以监听到目标页面的地址和打开行为，更新EmbedComponent组件的src参数，重新在当前页渲染EmbedComponent组件，保证新开的页面也在客户的宿主环境中，具体代码如下所示。其中事件的返回值false是中止Quick BI默认跳转逻辑；
<script lang="ts">
export default Vue.extend({
data(): EmbedComponent {
return {
embedEvents: {
[EmbedEventType['before-page-change-event']]: async ({ payload }) => {
/** 更新EmbedComponent的src属性，重新渲染跳转后的嵌入页面 */
this.$set(this, 'embedSrc', {
...payload.src
})
/** 阻止Quick BI的默认路由跳转逻辑 */
return false
}
}
}
</script>
完整示例
完整的示例代码可以参见如下codesandbox链接：codesandbox SDK VUE2 DEMO