常见问题

问题一：部分页面没有返回按钮

问题描述

在使用嵌入SDK的Quick BI过程中，总是在当前页进行跳转，跳转到新页面时，可能没有返回按钮，导致无法回退到之前的Quick BI页面。

例如：在列表页点击新窗口查看，当前页面跳转进入预览页，但是预览页没有返回按钮，导致使用链路中断，需要重新打开才能回到列表页。

可能的原因

Quick BI各个页面设计过程中，会考虑是当前页跳转还是新窗口打开，如果是新窗口打开的页面，并不会设计返回按钮。在使用JS SDK嵌入的过程中，可以阻塞Quick BI的跳转，自定义Quick BI跳转的页面地址。如果设置的始终是当前页跳转，就有可能遇到使用链路中断的问题。

解决方案

方案一：监听页面跳转事件的回调内根据target决定打开页面方式

before-page-change-event监听事件，会传入Quick BI原本要跳转的路由信息src和跳转方式target。根据target参数，控制SDK页面是新窗口打开，还是当前页跳转。

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


events={{
  [EmbedEventType['before-page-change-event']]: async (message: ChangeEventMessage) => {
    const newSrc = message.payload.src
    if (message?.payload?.target === '_blank') {
      // 新窗口打开 可以在宿主系统中新增一个嵌入SDK新窗口路由，该路由仍然渲染EmbedComponent组件，组件的src信息由此处newSrc传入
      window.open('xxx/sdk/new');
    } else if (message?.payload?.target === '_blank') {
      // 重新渲染当前组件
      setSrc(newSrc);
    }
    // 阻塞Quick BI的默认跳转      
    return false;
  },
}}

方案二：宿主环境发起页面跳转Action，控制嵌入Quick BI页面

嵌入SDK支持在宿主环境发起行为Action控制Quick BI页面的跳转。可以在宿主环境增加一个按钮，用来控制嵌入组件EmbedComponent返回跳转指定页面的按钮

const client = useRef<EmbedClient>(null);

/** 嵌入组件绑定ref */
<EmbedComponent ref={client} ...... />

<Button
  onClick={async () => {
    await client.current?.dispatch({
      type: EmbedActionType.embedNavigate,
      payload: {
        src: {
          origin: "xxx",
          /** 嵌入工作空间页面的路由键 */
          page: EmbedRouteKey.workspace,
          /** 嵌入页面的查询参数 */
          search: {
            workspaceId: "xxx",
          },
        },
      },
    });
  }
>
  跳转Quick BI工作空间页面
</Button>

问题二：打开分享链接或者直接访问Quick BI域名链接

问题描述

通过分享或者协同链接直接访问Quick BI域名链接，进入了Quick BI页面，脱离了宿主环境。

解决方案

首先需要配置安全设置配置，通过域名管控，限制非超级管理员用户直接访问Quick BI系统，配置重定向链接，可以重定向到宿主环境的地址，注意配置来源URL占位符${originUrl}，后续用于解析来源地址。

此时非管理员用户之间访问Quick BI系统会重定向到嵌入承接页，在承接页中解析来源地址，将其解析为嵌入源对象进行嵌入展示，例如：

const urlParams = new URLSearchParams(window.location.search)
const encodedLink = urlParams.get('link')
const href = encodedLink ? decodeURIComponent(encodedLink) : ''
/** 将链接解析成嵌入对象 */
const src = parsePath(href)
if (src && src.page) {
  /** 替换当前页面的嵌入源信息 */
  this.$set(this, 'embedSrc', src)
}

问题三：页面提示“离开此网站”，点击取消后通信中断

问题描述

Quick BI在各个数据作品的编辑页面绑定了浏览器的beforeunload页面，当编辑数据未保存后离开该页面时出触发浏览器的页面提示“离开此网站”。在SDK嵌入仪表板编辑页时，通常会绑定路由跳转事件，获取跳转信息后，控制SDK嵌入的src更改，保证跳转后的页面仍在嵌入环境内，但是该过程中修改了底层iframe的src，触发了浏览器的beforeunload事件，弹出如下提示，此时点击取消，当前页面仍然保留，但是嵌入的页面已经改动，导致两者通信中断。

解决方案

路由跳转事件回调更新组件src时，更新整个<EmbedComponent />组件，而不仅仅是iframe的src。例如在React环境下，给该组件增加一个key，当key改动时，更新整个<EmbedComponent />组件，示例代码如下，在Vue开发环境内同理。

<EmbedComponent
  src={src}
  key={src.page}
  ......
/>