API参考

魔笔提供了一套API用于支持组件开发。本文介绍API的功能，API完整的定义请参考模板中的src/api/mobiComponentApi.ts。

获取API

• 对于函数组件，可以通过如下方式获取：

  import { useApi } from "../../../api/createApi";
  const Demo = (props: any) => {
   // 获取API
   const api = useApi(props);
   return <div/>;
  }

• 对于类组件，可以通过如下方式获取：

  import { createApiFromProps } from "../../../api/createApi";
  import MobiComponentApi from "../../../api/mobiComponentApi";
  
  class Demo extends React.Component<any> {
   private _api: MobiComponentApi;
  
   constructor(props: any) {
   super(props);
   this._api = createApiFromProps(props);
   }
  }

API说明

• 环境判断API

  用于在组件中判断当前是否是运行时，主要用来区分运行时和设计时。

  export default interface MobiComponentApi {
    /**
     * 判断是否是运行时
     */
    isPreview: (props: object) => boolean;
  }

• 样式计算API

  export default interface MobiComponentApi {
    /**
     * 计算宽度，width和margin在setter进行设置时，保存的数据结构是定制的，所以需要通过此api计算
     * 传入margin是为了在宽度的基础上减去左右margin获得宽度，避免在宽度设置是100%时，组件在页面上产生横向滚动条
     * 容器类或者可能占满全屏的组件建议传入margin。其它组件看情况
     */
    getWidth: (width?: any, margin?: any) => string;
    
    /**
     * 计算高度
     */
    getHeight: (height?: any) => string;
  }

  • getWidth是通过宽度、margin的prop计算设置的宽度。

  • getHeight是通过高度的prop计算设置的高度。

  宽度和高度的setter因为尺寸的表达方式比较多，所以设置的prop是一个对象，需要通过API计算，才能获取正确的值。

  margin不用计算，setter设置的就是"0px 0px 0px 0px" 这种格式。

• 数据字段获取、更新API

  /**
   * prop的字段名 参数
   * 用于获取或者更新某个prop， 对应的value可能是任何数据类型
   */
  export interface KeyArgs {
    /**
     * prop的字段名
     */
    key: string;
  }
  
  /**
   * 数据字段参数
   * 用于指定是数据的哪个字段
   */
  export interface FieldArgs {
    field: any;
  }
  
  /**
   * 数据标识参数
   * 用于指定当前操作的是哪个数据
   */
  export interface DataArgs {
    data: any;
  }
  
  /**
   * 前端组件通过回调之类的方式传回来的值
   * 用于更新动态字段
   */
  export interface UIValueArgs {
    uiValue: any;
  }
  
  type getDCValueByKeyOrField = (props: object, args: KeyArgs | FieldArgs) => any;
  type getDCValueByKeyOrFieldAndData = (
    props: object,
    args: (KeyArgs | FieldArgs) & DataArgs
  ) => any;
  
  type setDCValueByKeyOrField = (
    props: object,
    args: (KeyArgs | FieldArgs) & UIValueArgs
  ) => void;
  type setDCValueByKeyOrFieldAndData = (
    props: object,
    args: (KeyArgs | FieldArgs) & DataArgs & UIValueArgs
  ) => void;
  
  export default interface MobiComponentApi {
    /**
     * 获取字段的值
     */
    getDcValue: getDCValueByKeyOrField & getDCValueByKeyOrFieldAndData;
    /**
     * 更新字段的值
     * value 参数是必须的
     * 其它参数的情况和 getDcValue 一样
     */
    setDcValue: setDCValueByKeyOrField & setDCValueByKeyOrFieldAndData;
    /**
     * 判断字段是否不可编辑，没有或者只读 都是不可编辑
     */
    isDisabled: isDisabledByKeyOrField & isDisabledByKeyOrFieldAndData;
  }

  • getDcValue是获取实体对象字段的值。

  • setDcValue是更新实体对象字段的值。

  • isDisabled是用于判断实体对象字段是否可以编辑。

  getDcValue、setDcValue和isDisabled均有两个参数：props和args，props是最新的组件props，

  args是一个组合参数。

  • key或者field表示是哪个实体字段，key是prop的名称，field是描述字段的数据。如果通过prop配置的实体字段，则field=props[key]，所以传key或者field其中一个就行。

  • data描述获取哪个实体对象的字段，不传则表示当前组件绑定的实体对象。

  • uiValue描述是组件返回的数据，用于更新实体对象字段。

• 事件触发API

  type emitByKeyOrEvent = (
    props: object,
    args: (KeyArgs | EventArgs) & EventExtraArgs
  ) => void | Promise<any>;
  
  type emitByKeyOrEventAndDataDc = (
    props: object,
    args: (KeyArgs | EventArgs) & EventExtraArgs & DataArgs & DCArgs
  ) => void | Promise<any>;
  
  export default interface MobiComponentApi {
    /**
     * 执行prop绑定的事件
     */
    emitDcEvent: emitByKeyOrEvent & emitByKeyOrEventAndDataDc;
  }

  通过emitDcEvent可以触发通过prop配置的事件，包括页面操作（跳转页面）、数据操作（保存、更新数据）、逻辑流操作（触发逻辑流）

  emitDcEvent有两个参数：props和args。props是最新的组件props，args是一个组合参数。

  • key或者action表示是哪个事件，key是prop的名称，action是描述事件的数据。如果通过prop配置的事件，则action=props[key]，所以传key或者action其中一个就行。

  • async表示调用事件作为异步处理，true会返回一个Promise，false不会返回数据。当需要从逻辑流中获取返回的数据时，需要设置为true，默认false。

  • data和dc表示数据，在一些复杂场景会使用，一般不传，表示从当前绑定的数据获取参数。

• 数据源相关API

  export default interface MobiComponentApi {
    /**
     * 加载数据源， 返回透传对象
     */
    processDataSource: (props: object, args: { aggregate: boolean }) => object;
  
    /**
     * 包装children
     */
    createListItemContent: (
      props: object,
      itemComponentOptions: {
        ItemComponent: React.JSXElementConstructor<any>;
        name: string;
      },
      children: any[],
      passParams: any
    ) => any[];
  
    /**
     * 获取数据列表
     */
    getListItems: (props: object) => any[];
  }

  • processDataSource用于加载数据源，返回的对象需要透传给children。

  • createListItemContent用于在List类型的组件中包装ListItem。

  • getListItems用于List-Data类型的组件，获取实体对象列表。

  具体使用请参见模板中的src/Sample/data-container/func。

• 分页、排序、过滤逻辑API

  export default interface MobiComponentApi {
  
    /**
     * 获取数据总数
     */
    getListTotalCount: (props: object) => number;
  
    /**
     * 配置分页
     */
    updateDataFilter: (options: RetrieveParams) => void;
  
    /**
     * 用于在配置分页之后更新数据
     */
    updateData: (props: object, options: { reload: boolean }) => void;
  }

  • getListTotalCount用于获取一共有多少数据。

  • updateDataFilter用于配置分页、排序、过滤条件。

  • updateData用于配置条件后更新数据。

  updateDataFilter的参数如下：

  /**
     * filter: {
     *  type: 'AND' | 'OR',
     *  groups: [
     *    {
     *      type: 'AND' | 'OR',
     *      filters: [ 
     *          {
     *            attrId:
     *            type: ISNULL | NOTNULL | EQ | NEQ | GT | GTE | LT | LTE | CONTAINS | NOTCONTAIN | STARTSWITH | ENDSWITH | BETWEEN
     *            values: []
     *          }    
     *        ]
     *      }
     *    ]
     * }
     * sort: [
     *  {attrId, type}
     * ],
     * page: {
     *  number:,
     *  size:
     * }
     */
  interface Filter {
    field: any;
    type:
    | "ISNULL"
    | "NOTNULL"
    | "EQ"
    | "NEQ"
    | "GT"
    | "GTE"
    | "LT"
    | "LTE"
    | "CONTAINS"
    | "NOTCONTAIN"
    | "STARTSWITH"
    | "ENDSWITH"
    | "BETWEEN";
    values: any[];
  }
  
  interface FilterGroup {
    type: "AND" | "OR";
    filters: Filter[];
  }
  
  export interface FilterParam {
    type: "AND" | "OR";
    groups: FilterGroup[];
  }
  
  export interface SortParam {
    field: any;
    type: "DESC" | "ASC" | "DEFAULT";
  }
  export interface RetrieveParams {
    filter?: FilterParam;
    sort?: SortParam[];
    page?: {
      number: number;
      size: number;
    };
  }

  其中：

  • page用于配置分页条件。

  • sort用于配置排序条件。

  • filter用于配置过滤条件。

    参数中的field字段表示实体字段。