@x-group/portal-jssdk v1.0.6

海众主站 SDK

背景

海众主站提供 SDK 能力，便于接入海众主站的第三方应用（微应用、iFrame）获取当前用户的一些通用能力、信息，包括当前用户登入登出、用户/租户信息、租户的资源权限等等。

流程设计

主站登陆后，将用户/租户信息、资源权限等存放在 localStorage 中，对于微应用接入方，调用 sdk 方法，sdk 直接读取 localStorage 信息返回即可；对于 iframe 接入方，通过 postMessge 在主站及接入方之间通信。以获取用户信息为例：

使用须知

以微应用接入的，直接使用 sdk 下的 api 接口：

import sdk from '@x-group/portal-jssdk';

const getUserInfo = () => sdk.api.getUserInfo();

以 iframe 接入的，使用 sdk 下的 iframeApi 接口，注意结果均为异步返回：

import sdk from '@x-group/portal-jssdk';

const getUserInfo = async () => {
  const info = await sdk.iframeApi.getUserInfo();
  console.log(info);
};

功能模块 API 设计

用户登入

跳转到登陆页

import sdk from '@x-group/portal-jssdk';

sdk.api.login();

用户登出

登出当前用户，跳转到登陆页

import sdk from '@x-group/portal-jssdk';

sdk.api.logout();

获取用户信息

import sdk from '@x-group/portal-jssdk';

sdk.api.getUserInfo();

获取登陆 Token（该方法返回包含token和租户tenant的对象）

import sdk from '@x-group/portal-jssdk';

const token = sdk.api.getToken().token;
const tenant = sdk.api.getToken().tenant;

获取当前租户 code

import sdk from '@x-group/portal-jssdk';

const tenantCode = sdk.api.getTenant();

获取用户资源列表

import sdk from '@x-group/portal-jssdk';

const resources = sdk.api.getUserResources();

通过 code 获取资源

import sdk from '@x-group/portal-jssdk';

const resource = sdk.api.getResource('MA_KQGL_KHQZ');

资源权限判断

import sdk from '@x-group/portal-jssdk';

const auth = sdk.api.hasAuth('MA_KQGL_KHQZ');

打开新的窗口

子应用通过iFrame嵌套在主应用的情况下，iFrame子应用可能无法调用window.open方法来打开新窗口，因此提供sdk.iframeApi.open接口来通知宿主打开新窗口。

import sdk from '@x-group/portal-jssdk';

sdk.iframeApi.openWindow("https://www.xxx.com", "_blank");

获取系统主题

获取系统主题，返回值类型为antd theme.getDesignToken(): AliasToken

import sdk from '@x-group/portal-jssdk';

const designToken = sdk.api.getDesignToken();

使用History进行页面跳转

iframe子应用通知父页面进行页面跳转, 目前支持push、replace、back等方法。

import sdk from '@x-group/portal-jssdk';

sdk.iframeApi.historyAction({
  // 'push' || 'replace' || 'back'
  action: 'push',
  // 应用名称（push，replace时必填）
  appName: 'cms'
  // 跳转路径（push，replace时必填）
  to: '/path' });

iframe自行使用postMessage和父页面交互参考

建议iframe子应用通过jssdk.iframeApi和父页面进行交互，如果iframe子应用不使用sdk，而是自行发送postMessge通知父页面进行相应操作，那么使用postMessage发送需要参考如下代码示例：

// 生成调用父页面方法的函数
const callParentFrame = <T>(funcName: string, ...args: any[]): Promise<T> => {
  return new Promise<T>((resolve, reject) => {
    // 生成唯一标识， 避免子frame连续调用时回调监听不匹配
    const uuid = v4();
    // iframe请求postMessage消息体结构
    const requestData = {
      // 固定值
      type: 'request',
      // 要调用的方法，具体支持的方法参考本文档的api功能列表
      method: funcName,
      // 固定值
      isHm: true,
      // 调用对应方法传入的参数
      args,
      // uuid
      uuid,
    };

    // 发送消息到父页面
    window.parent.postMessage(requestData, '*');

    // 定义监听函数
    const listener = function (event: any) {
      const { data } = event;
      // 检查消息是否是父页面返回的
      if (data && data.type === 'response' && data.isHm && data.method === funcName && data.uuid === uuid) {
        if (data.code === 'success') {
          // 调用回调函数，传入结果
          resolve(data.result);
        } else {
          reject(data);
        }
        // 移除当次监听，避免重复调用
        window.removeEventListener('message', listener);
      }
    };

    // 监听来自父页面的消息
    window.addEventListener('message', listener, false);
  });
};

// 调用父页面history跳转功能
callParentFrame('historyAction', {
  action: 'push',
  appName: 'cms',
  to: '/a/b/c',
}).then(result => {
  console.log(result);
});

子iframe请求postMessge消息体

子iframe需要使用如下消息体结构，发送给父页面

// iframe请求postMessage消息体结构
const requestData = {
  // 固定值
  type: 'request',
  // 要调用的方法，具体支持的方法参考本文档的api功能列表
  method: funcName,
  // 固定值
  isHm: true,
  // 调用对应方法传入的参数
  args,
  // uuid
  uuid,
};

父页面postMessge返回的消息体

父页面监听到子frame的调用请求时，返回的postMessge消息体结构如下，子frame在回调监听里自行解析

const responseData = {
  // 固定值
  type: 'response',
  // 子frame调用的方法名
  method: 'getUserInfo | getToken',
  // success || error
  code: 'success',
  // 调用结果
  result: { token: 'eyJhbGciOiJIUzI1NiJ9', taneat: 'ZAHZ' },
  // 固定值
  isHm: true,
  // 子frame调用时传入的uuid
  uuid: ''
};