API的功能有哪些_多端低代码开发平台魔笔(Mobi)-阿里云帮助中心

魔笔提供了一套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字段表示实体字段。