行为事件API

CustomEventMeta

行为事件的元信息是一个事件的对象，其接口为：

interface CustomEventMeta {
  listenr: EventListener;
}

示例

const delay = time => new Promise(res => setTimeout(res, time));

const eventMeta = {
  listener: async props => {
    // delay 1ms and go on
    await delay(1);
    
    return true
  }
}

Listener

listener是一个事件监听回调函数，通过返回值来决定是否发起默认的事件，其接口为：

type EventListener = (props: CustomEventProps) => Promise<boolean>;

返回值

• true: 触发默认的事件

• false: 阻断默认的事件

CustomEventProps

CustomEventProps描述的是监听回调函数的传入参数。包含了type、pageConfig、dispatch和utils四个属性，其接口为：

interface CustomEventProps {
  /** 事件类型 */
  type: CustomEventType;
  /** 页面信息 */
  pageConfig: CustomEventPageConfig;
  /** 操作 */
  dispatch?: CustomEventPropsDispatch;
  /** 工具方法 */
  utils?: CommonUtils;
}

CustomEventProps.type

CustomEventType定义了发起该回调函数的事件类型，目前支持两种事件类型，具体如下：

enum CustomEventType {
  /** 自定义事件-导出前 */
  beforeDownLoadEvent = 'before-download-event',
  /** 自定义事件-页面加载前 */
  beforePageLoadedEvent = 'before-page-loaded-event',
}

CustomEventProps.pageConfig

CustomEventPageConfig定义了该行为事件被调用时的各项页面信息，其接口如下：

interface CustomEventPageConfig {
  /** 页面工作空间 id */
  workspaceId: string;
  /** 页面 id */
  id: string;
  /** 页面模式, 编辑态/预览态/截图态(仅仪表板和电子表格有) */
  mode: 'preview' | 'edit' | 'snapshot';
  /** 当前设备 */
  device: 'pc' | 'mobile';
  /** 当前访问者 id */
  userId: string;
  /** 当前访问者 id */
  userName: string;
  /** 页面创建者 id */
  ownerUserId: string;
  /** 页面创建者 id */
  ownerUserName: string;
  /** 页面标题 */
  title: string;
  /** 页面类型 */
  pageType: 'dashboard' | 'webExcel' | 'screen' | 'offline';
}

CustomEventProps.dispatch

定义了行为事件支持的一些操作，包括打开弹窗、关闭弹窗、显示提示的功能，其接口如下

/**
 * 自定义事件 dispatch 属性
 */
type CustomEventPropsDispatch = (
  param: CommonOpenModalAction | CommonCloseModalAction | CommonShowMessageAction,
) => void;

CommonOpenModalAction

唤起弹窗的具体接口如下：

/**
 * 唤起弹窗
 */
interface CommonOpenModalAction<T = CommonModalPayload> {
  type: 'openModal';
  payload: T;
}

/** 通用的弹窗唤起方法 */
interface CommonModalPayload {
  /** PC端弹窗宽度 */
  width?: string | number;
  /** PC端和移动端点击取消按钮时的回调 */
  onCancel?: (...args: any[]) => any;
  /** 弹窗关闭 icon */
  closeIcon?: React.ReactNode;
  /** 内容 */
  content?: React.ReactNode;
  /** 标题 */
  title?: string;
  /** PC端点击确定回调，返回 promise 可以延迟关闭。 */
  onOk?: (...args: any[]) => any;
  /** PC端确认按钮文字 */
  okText?: React.ReactNode;
  /** PC端取消按钮文字 */
  cancelText?: React.ReactNode;
  /** PC端确认按钮属性 */
  okButtonProps?: {
    style?: React.CSSProperties;
    disabled?: boolean | undefined;
  };
  /** PC端取消按属性 */
  cancelButtonProps?: {
    style?: React.CSSProperties;
    disabled?: boolean | undefined;
  };
  /** body 样式 */
  bodyStyle?: React.CSSProperties;
  /** 点击浮层关闭弹窗 */
  maskClosable?: boolean;
  /** 底部按钮 */
  footer?: {
    text?: string;
    onClick?: React.MouseEventHandler<HTMLElement>;
    type?: 'default' | 'primary';
  }[];
}

示例：唤起一个简单的弹窗

import React from 'react';

const eventMeta = {
  listener: async props => {

    props.dispatch({
      type: 'openModal',
      payload: {
        title: '简单弹窗',
        content: <div>弹窗内容</div>,
        type: 'info',
      }
    })
    
    return false;
  }
}

export default eventMeta;

CommonCloseModalAction

关闭弹窗与唤起弹窗配合使用，具体接口如下：

interface CommonCloseModalAction {
  type: 'closeModal';
}

示例：弹窗内增加关闭按钮

import React from 'react';

const eventMeta = {
  listener: async props => {

    props.dispatch({
      type: 'openModal',
      payload: {
        title: '简单弹窗',
        content:
          <div>
            <div>弹窗内容</div>
            <button onClick={() => props.dispatch({
              type: 'closeModal',
            })}>点击关闭</button>
          </div>,
        type: 'info',
      }
    })

    return false;
  }
}

export default eventMeta;

CommonShowMessageAction

显示提示的具体接口如下：

/**
 * 唤起 message 提示
 */
interface CommonShowMessageAction {
  type: 'showMessage';
  payload: CommonMessagePayload;
}

/** 通用的 message 传参 */
interface CommonMessagePayload {
  /** 内容 */
  content?: React.ReactNode;
  /** 类型 */
  type: 'info' | 'success' | 'error' | 'warn';
}

示例：给一个简单提示

const eventMeta = {
  listener: async props => {

    props.dispatch({
      type: 'showMessage',
      payload: {
        content: '简单message',
        type: 'info',
      }
    })

    return false;
  }
};

export default eventMeta;

CustomEventProps.utils

utils是包含通用工具方法的对象，其接口如下：

/**
 * 通用的工具方法
 */
export interface CommonUtils {
  /** 获取 cookie */
  getCookie: (key: string) => string;
}

getCookie

目前qbi行为事件内支持获取cookie内容，通过key获取对应的value值。

示例：获取当前语言情况

const eventMeta = {
  listener: async props => {

    props.dispatch({
      type: 'showMessage',
      payload: {
        content: props.utils.getCookie('qbi_locale'),
        type: 'info',
      }
    })

    return false;
  }
};

export default eventMeta;