@itshixun/quc-adapter

QST前端项目对接用户中心工具库

该工具库提取业务端与QUC的常用交互方法，供业务端使用，简化业务端相关逻辑。同时，当QUC的相关逻辑进行迭代升级时，业务端通过更新该工具，可以快速同步对接QUC的相关变更。

Installation

npm install @itshixun/quc-adapter

Usage

业务端与QUC用户中心侧的交互主要分为两种场景：

1. 跳转用户中心进行登录/退出/账号设置/同步登录态等
2. 用户中心页面作为iframe嵌入业务端，业务端通过postMessage方法与用户中心子页面进行通信，来同步登录态。

下面分别介绍这两种场景的使用说明和示例：

1. 跳转用户中心

跳转用户中心有两个方法：generateQucRedirectUrl(option: QucRedirectorOption) 和 redirectToQuc(option: QucRedirectorOption)。这两个方法的传参相同，唯一的区别是前者返回用户中心的URL对象，后者直接跳转到用户中心。下面以redirectToQuc()为例，介绍跳转用户中心的使用方法。

这两个方法的传参类型QucRedirectorOption包含三个字段：

• redirectType: 跳转类型，取值：login/logout/profile/syncLoginState 等，指定跳转用户中心的目的，用于判断跳转到用户中心的哪个页面
• qucOrigin: 用户中心地址根路径，通常从appconfig获取，比如: https://uc.qstcloud.net
• params: 跳转用户中心的url参数，比如theme/layout/redirect_uri等

具体使用方法，请看下面的使用示例以及类型定义：

使用示例：

import { redirectToQuc } from '@itshixun/quc-adapter'

/**
 * 跳转用户中心登录
 */
const toLogin = () => {
  redirectToQuc({
    /**
     * 跳转类型 'login'登录 / 'logout'退出 / 'profile'账号设置 / 'sync'同步登录态...
     */
    redirectType: 'login',
    /**
     * quc根路径 通常从appconfig获取
     */
    qucOrigin: 'https://uc.qstcloud.net',
    /**
     * 跳转用户中心的url所需要携带的参数，详见下方QucUrlParams类型定义
     */
    params: {
      /** 登录成功后跳转的url，用户中心登录完成后，会带上ticket参数回跳到该url */
      redirect_uri: `https://tev.qstcloud.net/authorize?redirect=${location.href}`,
      /** 布局参数，详见下方LayoutQueryData类型定义 */
      layout: {...},
      /** 主题皮肤，目前QUC仅支持三种：athena/local/oppo，不传默认athena */
      theme: 'athena',
      // fallback参数仅在通过跳转用户中心同步登录态时(redirectType === 'sync'时)传入
      fallback: `${location.href}`
    }
  }).href
}

类型定义:

QucRedirectorOption

generateQucRedirectUrl方法的参数类型定义

export interface QucRedirectorOption {
  /**
   * 要跳转的用户中心地址orgin，要求是http或https开头的完整域名，比如https://uc.eduplust.net
   */
  qucOrigin: string;
  /**
   * 跳转类型，默认为sync，详见QucRedirectType类型定义
   * - sync 跳转quc同步登录状态
   * - login 跳转quc登录页面
   * - profile 跳转quc个人中心
   * - logout 跳转quc退出登录
   * - iframe 通过iframe嵌入quc页面同步登录态时，生成对应iframe的src地址, .e.g: 'https://uc.qstcloud.net/iframeLogin'
   */
  redirectType: QucRedirectType;
  /**
   * 跳转quc的url查询参数
   * - theme QUC主题皮肤
   * - fallback 通过跳转QUC同步登录态的回跳地址
   * - redirect_uri 跳转quc登录后的回跳地址
   * - layout 控制用户中心页面布局细节的参数，详见LayoutQueryData类型定义
   */
  params?: QucUrlParams;
}

QucUrlParams

跳转QUC地址的url参数类型定义：

/**
 * 跳转quc的url参数
 */
export interface QucUrlParams {
  /**
   * 指定用户中心主题，可选，不指定默认使用athean主题
   */
  theme?: QucTheme;
  /**
   * 跳转用户中心判断登录态时，带fallback参数，在quc拦截器中判断完登录态后
   * - 如果用户中心已登录，fallback地址会添加一个tickect参数(即登录的sessionId)。同时如果fallback地址内带有自己
   * 的redirect_uri参数,则用户中心会在内层redirect_uri地址中添加一个quc_tickect参数传入sessionId，传给最终跳转的前端页面使用。
   * - 如果用户中心未登录，跳回fallback地址
   */
  fallback?: string;
  /**
   * 登录后的跳转地址，在用户中心登录成功后，会在redirect_uri地址会添加一个tickect参数(即登录的sessionId)。同时如果redirect_uri地址内带有自己
   * 的redirect_uri参数,则用户中心会在内层redirect_uri地址中添加一个quc_tickect参数传入sessionId，传给最终跳转的前端页面使用。
   */
  redirect_uri?: string;
  /**
   * 控制用户中心页面布局细节的参数
   */
  layout?: LayoutQueryData;
}

LayoutQueryData

控制用户中心页面布局细节的参数

/**
 * 控制用户中心页面布局细节的数据结构
 */
export interface LayoutQueryData {
  /**
   * 页面logo图片地址
   */
  logoSrc?: string;
  /**
   * 点击logo的跳转链接
   */
  logoLink?: string;
  /**
   * 页面标题
   */
  pageTitle?: string;
  /**
   * 页面标签页favicon
   */
  pageIcon?: string;
  /**
   * layout类型，目前仅针对企业端登录页 传'enterprise'，其他值显示默认登页
   */
  layoutType?: '' | 'default' | 'enterprise';
  /**
   * SAAS默认皮肤(athean)中，如果layout参数为空，默认显示企业入口按钮
   * 在传layout参数的情况下，默认不显示企业入口按钮，
   * 如果需要显示，需要设置此字段为true
   * */
  showEnterpriseBtn?: boolean;
  /**
   * 是否隐藏登录页的《用户协议》《隐私政策》
   */
  hideAgreement?: boolean;
  /**
   * 常规登录页，[企业入口]的完整URL跳转地址，不传则默认跳转saas版企业首页
   */
  enterpriseLink?: string;
  /**
   * 企业登录页面 [学生入口]的完整URL跳转地址，不传则默认跳转saas版U+平台首页
   */
  studentLink?: string;
  /**
   * 注册跳转的完整URL地址，不传则默认在企业登录页时跳转SAAS企业注册页面，常规SAAS登录页跳转到常规SAAS注册页面
   */
  registerLink?: string;
}

2. handleQucMessage方法

在用户中心iframe嵌入业务页面来进行登录态同步时，可以使用该方法来简化处理用户中心iframe发送过来的消息。该方法通过传入onGetToken和onNoToken两个回调函数，简化处理用户中心iframe发送过来的消息。

使用示例

import { onMounted } from 'vue';
import { handleQucMessage } from '@qstcloud/quc-utils';

onMounted(() => {
  window.addEventListener('message', (e: MessageEvent<string>) => {
    handleQucMessage({
      e,
      iframeUrl: 'https://uc.qstcloud.net/iframeLogin',
      onGetToken: (token: string) => {
        // 拿到用户中心的token(即sessionId),处理登录逻辑
      },
      onNoToken: (messageData?: string) => {
        // 处理未取得用户中心的登录态时的相关逻辑
      },
    });
  });
});

类型定义

handleQucMessage方法的参数类型定义如下：

/**
 * 处理从用户中心iframe传递过来的postMessage消息
 */
export interface QucMessageHandlerOption {
  /**
   * 消息事件主体
   */
  e: MessageEvent<string>;
  /**
   * 用户中心iframe的url, 用来判断当前消息是否由用户中心iframe发送
   */
  iframeUrl: string;
  /**
   * 当前消息从用户中心iframe发送，但是并未返回数据，或者返回的数据为'nosession'，或者返回的消息解析失败
   * 如果返回的是'nosession'，通常说明当前用户中心并未登录
   * 如果返回空数据，可能是说明当前浏览器不支持跨域的用户中心iframe同步顶层窗口用户中心的登录状态
   * @returns void
   */
  onNoToken: (messageData?: string) => void;
  /**
   * 获取到了用户中心iframe发送的数据，并正确解析获得了sessionId
   * @param session
   * @returns
   */
  onGetToken: (session: string) => void;
}

关于版本同步

本工具的版本与用户中心的版本保持一致，请使用对应的版本（从3.0.x开始）。比如某本地化项目使用了3.0.x版本的用户中心，则业务端也需要使用3.0.x版本的本工具与用户中心进行交互。

--- EOF ---