基本概念_智能商业分析 Quick BI(Quick BI)-阿里云帮助中心

在将Quick BI页面嵌入到自有系统的过程中，涉及以下三个主体：

宿主页：宿主页是指用户自有的应用程序或网站页面，即开发者要将Quick BI页面嵌入到的载体页面。
嵌入客户端实例：嵌入客户端实例是嵌入SDK中的核心对象，负责管理嵌入页面的嵌入源、特性、与宿主页面的交互以及触发各种行为等。
Quick BI页：Quick BI页是指由Quick BI提供的功能页面，它们可以通过嵌入SDK嵌入到宿主页面中。

宿主页通过嵌入客户端实例来渲染嵌入页、调用嵌入页行为方法和监听嵌入页事件。下文将为您介绍嵌入客户端实例的创建方式及其构成参数。

创建方式

嵌入客户端实例在不同开发环境下的创建方式不同，具体说明如下。

通用JavaScript环境（无框架）

在无框架环境下，开发者可以通过嵌入SDK中的EmbedClient类创建实例，示例代码如下。

import { EmbedClient } from '@quickbi/bi-embed-client';

const embedClient = new EmbedClient({})

创建完嵌入客户端实例后，不会立即渲染嵌入页，需要使用 render方法挂载到一个宿主页的 dom节点上。

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

通过destroy方法可以销毁嵌入页。

embedClient.destroy();

说明

当嵌入源的链接改变时，需要先销毁旧嵌入页，然后重新生成新的嵌入客户端实例并重新渲染。

import { EmbedClient, EmbedSrcUnion, compilePath } from '@quickbi/bi-embed-client';
const lastSrc:EmbedSrcUnion = {};
let embedClient = new EmbedClient({ src: lastSrc });
embedClient.render(containerDom)
const newSrc:EmbedSrcUnion = {};
if (compilePath(lastSrc) !== compilePath(newSrc)) { // 嵌入源改变
  embedClient.destroy(); // 销毁嵌入页
  embedClient = new EmbedClient({ src: newSrc }); // 重新生成实例
  embedClient.render(containerDom) // 重新渲染
}

React 框架环境（推荐）

在React环境下的嵌入SDK中，EmbedComponent组件内部默认实现了创建嵌入客户端实例和自动重新渲染的逻辑，可以通过useRef来获取嵌入客户端实例。

import { EmbedClient, EmbedComponent } from '@quickbi/bi-embed-client-react';

const Demo: React.FC = () => {
  const embedClient = React.useRef<EmbedClient>();
  return (
    <EmbedComponent
      ref={embedClient}
      src={{
        // ...
      }}
    />
  )
}

Vue2框架环境

在Vue2环境下，可以直接引入EmbedComponent组件，该组件内部默认实现了创建嵌入客户端实例和响应式渲染的逻辑，可以通过this.$refs来获取嵌入客户端实例。

<template>
  <embed-component
    ref="child"
    :src="embedSrc"
  />
</template>
<script lang="ts">
import { EmbedComponent } from '@quickbi/bi-embed-client-vue2',
export default Vue.extend({
  name: 'SDK',
  components: {
    EmbedComponent
  },
  data() {
    return {
      embedSrc: {
       // ...
      },
    }
  }
  mounted(){
    /** 获取嵌入客户端实例 */
    const embedClient = this.$refs.child.embedClient;
    // 或者通过子组件的方法
    const embedClient = this.$refs.child.getEmbedClient();
  }
}),
</script>

构成参数

在嵌入客户端实例中，您可以配置嵌入源（src）、嵌入行为（action）、嵌入特性（feature）以及嵌入事件（events）。

嵌入源

嵌入源src是指描述需要嵌入页面的相关信息的对象。它定义了嵌入的目标页面及其参数，在创建客户端实例阶段就要传入，包含了以下属性。

origin: 嵌入源，例如 https://bi.aliyun.com。
page: QuickBI 每个作品页，列表页的每个Tab页都可以视为一个路由，例如仪表板预览页、仪表板编辑页、工作台仪表板列表页等。每个路由都有一个路由键，详细的路由键信息请参见路由键一览表。
说明
为了保证嵌入的正常使用，请在任何时候都使用路由枚举EmbedRouteKey，避免使用纯字符串。

search：需要传给嵌入页的URL参数。

import { EmbedRouteKey } from '@quickbi/bi-embed-client';

const embedClient = new EmbedClient({
  src: {
    origin: 'https://bi.aliyun.com',
    page: EmbedRouteKey.dashboardEdit,
    search: {},
  },
});

通过嵌入SDK提供的工具函数，可以快速地将URL解析为嵌入源，或将嵌入源解析为URL。

import { parsePath, compilePath, EmbedRouteKey } from '@quickbi/bi-embed-client';

// url => src
parsePath('https://bi.aliyun.com/workspace/dashboard?workspaceId=xxx'); // { page: 'dashboardList': {}, origin: 'https://bi.aliyun.com', search: { workspaceId: 'xx' } }

// src => url
compilePath({
  page: EmbedRouteKey.dashboardList,
  origin: 'https://bi.aliyun.com',
  search: { workspaceId: 'xx' },
}); // https://bi.aliyun.com/workspace/dashboard?workspaceId=xxx

嵌入行为

嵌入行为 action 是描述嵌入页提供给宿主调用的对象。宿主可以调用嵌入客户端实例的 dispatch(action)方法来触发嵌入行为，action包含以下信息。

type：行为类型key，例如跳转到指定页面等。类型是 EmbedActionType，具体请参见action。
说明
为了保证嵌入行为的正常使用，请在任何时候都使用枚举EmbedActionType，避免使用纯字符串。

payload：嵌入行为的具体参数，不同的行为类型有不同的参数，具体请参见action。

/** 跳转到指定页面 */
embedClient.dispatch({
  type: EmbedActionType.embedNavigate,
  payload: {
    src: newSrc,
  }
})

嵌入特性

嵌入特性feature是用于临时控制页面组件显示隐藏，或者修改展示文本等展示类特性的配置，例如可以隐藏页面头部等。其结构分为三层：路由key > 功能模块 > 特性配置项，具体的特性配置请参见feature。

feature: {
  [路由key]: {
    [功能模块]: {
      [特性配置项key]: value
    }
  }
}

嵌入特性的作用范围只在配置的路由范围中生效，且路由key与嵌入源的page相呼应，例如：

{
  src: {
    page: EmbedRouteKey.screenEdit,
  },
  feature: {
    [EmbedRouteKey.dashboardEdit]: { // 与上面的 page 不一致
      goBack: { // 配置失效, page 和路由范围不一致
        show: false,
      },
    },
  },
};

{
  src: {
    page: EmbedRouteKey.screenEdit,
  },
  feature: {
    [EmbedRouteKey.screenEdit]: {
      goBack: { // 配置生效
        show: false,
      },
    },
  },
};

宿主可以调用嵌入客户端实例的setEmbedFeature行为，来更新嵌入特性。

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

React

在 React 框架SDK中, EmbedComponent组件的 props.feature变更会自动触发特性更新。

import { EmbedComponent } from '@quickbi/bi-embed-client-react';

const Demo: React.FC = () => {
  return (
    <EmbedComponent
      feature={{
        // 自动更新特性
      }}
    />
  )
}

在Vue2框架SDK中，EmbedComponent组件的 props.feature通过动态绑定自动触发特性更新。

<template>
  <embed-component
    :feature="embedFeature"
  />
</template>
<script lang="ts">
import { EmbedComponent } from '@quickbi/bi-embed-client-vue2',
export default Vue.extend({
  name: 'SDK',
  components: {
    EmbedComponent
  },
  data() {
    return {
    embedFeature: {
       // 自动更新特性
      },
    }
  }
  
}),
</script>

嵌入事件

嵌入页在执行某些动作时，会向宿主发送嵌入事件，宿主可以通过嵌入客户端实例的on(eventType, handler)方法来注册事件回调。在离开页面时，可以通过off(eventType, handler) 来解绑事件。

eventType：事件名称。
说明
为了保证嵌入事件的正常使用，请在任何时候都使用枚举EmbedEventType，避免使用纯字符串。

handler：宿主处理事件的回调，不同事件传入回调函数的参数都不一样，具体请参见events。

async handler function(payload) {}

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

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

在React框架环境的嵌入SDK中，EmbedComponent组件的props.events变更会自动重新绑定事件，在卸载组件时也会自动解绑事件。

import { EmbedComponent, EmbedEventType } from '@quickbi/bi-embed-client-react';

const Demo: React.FC = () => {
  const handler = useCallback(() => {}, []);
  return (
    <EmbedComponent
      events={{
        EmbedEventType['before-page-change-event']: handler // handler 自动更新
      }}
    />
  )
}

在Vue框架环境的嵌入SDK中，EmbedComponent组件的props.events变更会自动重新绑定事件，在卸载组件时也会自动解绑事件。

<template>
  <embed-component
    :events="embedEvents"
  />
</template>
<script lang="ts">
import { EmbedComponent, EmbedEventType } from '@quickbi/bi-embed-client-vue2',
export default Vue.extend({
  name: 'SDK',
  components: {
    EmbedComponent
  },
  data() {
    return {
    embedEvents: {
      EmbedEventType['before-page-change-event']: handler // handler 自动更新
      },
    }
  }
}),
</script>