API

获取方式

通过代码模块导入获取。

示例：

import api from './api';

if(api.isPreview()) {
  // 
} else {
  // 
}

isPreview

判断当前运行环境。

定义：

interface ComponentApi
  isPreview: () => boolean;
}

返回值：boolean，true表示是运行时（搭建的应用在实际运行），false表示是设计时（平台用户正在搭建应用，组件渲染是为了预览效果）。

getTopNavItems

获取一级导航菜单。

定义：

interface ComponentApi
  getTopNavItems: () => NavItem[];
}

返回值：一级导航项列表。

NavItem定义参见NavItem。

getCurrentNavItem

获取当前页面对应的导航项。

定义：

interface ComponentApi
  getCurrentNavItem: () => NavItem;
}

返回值：当前导航项对象。

NavItem定义参见NavItem。

getNavPathTo

根据导航项获取从一级导航到此导航路径上的所有导航项。

定义：

interface ComponentApi
  getNavPathTo: (navItem: NavItem) => NavItem[];
}

参数：

返回值：一级导航到当前导航的导航项列表。

NavItem定义参见NavItem。

onNavChange

设计时注册监听导航菜单更新的回调函数。

定义：

interface ComponentApi
  onNavChange: (fn: () => void) => void;
}

参数：

返回值：无。

offNavChange

设计时移除监听导航菜单更新的回调函数。

定义：

interface ComponentApi
  offNavChange: (fn: () => void) => void;
}

参数：

返回值：无。

openPage

打开指定页面。

定义：

interface ComponentApi
  openPage: (
    page?: Page,
    params?: {
      contextData?: EntityObject;
      closeCallback?: (params?: any) => void;
    },
  ) => void;
}

参数：

返回值：无。

EntityObject定义请参见EntityObject。

closePage

关闭当前页面。

定义：

interface ComponentApi
  closePage: (options?: { callbackParams?: any }) => void;
}

参数：

返回值：无。

uploadFile

文件上传API。

定义：

interface ComponentApi
  uploadFile: (
    file: File,
    option?: {
      onProgress: (progress: number) => void;
      type: FILE_VALUE_TYPE;
    },
  ) => Promise<FileValue>;
}

参数：

返回值：上传的文件对象。

FileValue定义请参见FileValue。

createFileValue

通过文件信息创建文件对象。

定义：

interface ComponentApi
  createFileValue: (options: { url: string; name: string; type: FILE_VALUE_TYPE }) => FileValue;
}

参数：

返回值：文件对象。

FileValue定义请参见FileValue。

hasPermission

判断当前用户是否有权限访问页面。

定义：

interface ComponentApi
  hasPermission: (page: Page) => boolean;
}

参数：

返回值：boolean类型，true为有权限，false为没有权限。

onSchemaChange

设计时注册监听页面搭建变更的回调函数。

定义：

interface ComponentApi
  onSchemaChange: (fn: () => void) => void;
}

参数：

返回值：无。

offSchemaChange

设计时移除监听页面搭建变更的回调函数。

定义：

interface ComponentApi
  offSchemaChange: (fn: () => void) => void;
}

参数：

返回值：无。

getSelected

设计时获取当前选中的组件节点对象。

定义：

interface ComponentApi
  getSelected: () => Node;
}

返回值：组件节点对象。

Node定义请参见Node。

select

设计时选中某个组件节点。

定义：

interface ComponentApi
  select: (node: Node | undefined) => void;
}

参数：

返回值：无。

Node定义请参见Node。

getNodeById

设计时根据组件节点ID获取组件节点对象。

定义：

interface ComponentApi
  getNodeById: (id: string) => Node | undefined;
}

参数：

返回值：无。

Node定义请参见Node。

getNodeId

设计时根据React节点对象获取组件节点ID。

定义：

interface ComponentApi
  getNodeId: (reactNode: any) => string | undefined;
}

参数：

返回值：string，组件节点ID。

isFileValue

判断属性值是否为文件类型。

定义：

interface ComponentApi
  isFileValue: (value: any) => value is FileValue;
}

参数：

返回值：boolean，true为是；false为否。

FileValue定义请参见FileValue。

isEnumValue

判断属性值是否为枚举类型。

定义：

interface ComponentApi
  isEnumValue: (value: any) => value is EnumValue;
}

参数：

返回值：boolean，true为是；false为否。

EnumValue定义请参见EnumValue。

isValue

判断属性值是否为VALUE类型；

定义：

interface ComponentApi
  isValue: (value: any) => value is VALUE;
}

参数：

返回值：boolean，true为是；false为否。

VALUE定义请VALUE。

isAttrMeta

判断属性值是否为字段。

定义：

interface ComponentApi
  isAttrMeta: (value: any) => value is AttrMeta;
}

参数：

返回值：boolean，true为是；false为否。

AttrMeta定义请参见AttrMeta。

isTemplateMeta

判断属性值是否为模板字符串。

定义：

interface ComponentApi
  isTemplateMeta: (value: any) => value is TemplateMeta;
}

参数：

返回值：boolean，true为是；false为否。

TemplateMeta定义请参见TemplateMeta。

isContextDataMeta

判断属性值是否使用了上下文数据。

定义：

interface ComponentApi
  isContextDataMeta: (value: any) => value is contextDataMeta;
}

参数：

返回值：boolean，true为是；false为否。

contextDataMeta定义请参见contextDataMeta。

convertDataSourceMeta

将数据源模型数据转换为数据源属性对象。

定义：

interface ComponentApi
  convertDataSourceMeta: (schemaData: DataSourceSchemaData) => DataSourceMeta | undefined;
}

参数：

返回值：DataSourceMeta，数据源属性对象。

DataSourceMeta定义请参见DataSourceMeta。

convertActionMeta

将事件模型数据转换为事件属性对象。

定义：

interface ComponentApi
  convertActionMeta: (schemaData: PageEventSchemaData) => ActionMeta;
}

参数：

返回值：ActionMeta，事件属性对象。

ActionMeta定义请参见ActionMeta。

convertAttrMeta

将字段模型数据转换为字段对象。

定义：

interface ComponentApi
  convertAttrMeta: ((schemaData: EntityAttrSchemaData) => AttrMeta | undefined) &
    ((attrId: string, entityId: string) => AttrMeta | undefined);
}

参数：

返回值：AttrMeta，字段对象。

AttrMeta定义请参见AttrMeta。

convertMultiAttrMeta

将字段模型数组转换为字段数组；允许包装字段。

定义：

interface ComponentApi
  convertMultiAttrMeta: <PackKey extends string, Config>(
    propValue: PackMultiAttrSchemaDataWith<PackKey, Config> | MultiAttrSchemaDataWith<Config>,
  ) => MultiAttrMetaWith<Config> | PackMultiAttrMetaWith<PackKey, Config>;
}

参数：

返回值：MultiAttrMetaWith<Config> | PackMultiAttrMetaWith<PackKey, Config>，包装后的字段数组；

MultiAttrMetaWith定义请参见MultiAttrMetaWith；

PackMultiAttrMetaWith定义请参见PackMultiAttrMetaWith；

convertValue

将静态模型数据转换为值对象。

定义：

interface ComponentApi
  convertValue: (propValue: StaticValueSchemaData) => VALUE;
}

参数：

返回值：VALUE，值对象。

VALUE定义请参见VALUE。

convertTemplate

将模板字符串模型数据转换为模板对象。

定义：

interface ComponentApi
  convertTemplate: (propValue: TemplateSchemaData) => TemplateMeta;
}

参数：

返回值：TemplateMeta，模板对象。

TemplateMeta定义请参见TemplateMeta。

convertAssociationMeta

将关联ID转换为关联对象。

定义：

interface ComponentApi
  convertAssociationMeta: (associationId: string) => AssociationMeta;
}

参数：

返回值：AssociationMeta，关联对象。

AssociationMeta定义请参见AssociationMeta。

convertSize

将尺寸模型数据转换为大小对象。

定义：

interface ComponentApi
  convertSize: (propValue: SizeSchemaData) => Size;
}

参数：

返回值：Size，样式大小对象。

Size定义请参见Size。

convertFileValue

将文件模型数据转换为文件对象。

定义：

interface ComponentApi
  convertFileValue: (propValue: ResourceFileSchemaData) => FileValue;
}

参数：

返回值：FileValue，属性文件对象。

FileValue定义请参见FileValue。

convertIcon

将图标模型数据转换为图标对象。

定义：

interface ComponentApi
  convertIcon: (propValue: IconSchemaData) => IconMeta;
}

参数：

返回值：IconMeta，属性图标对象。

IconMeta定义请参见IconMeta。

createMobiComponent

将React组件转换为魔笔组件。内部组件使用，用于接收数据上下文，注入PageContext API，实现数据驱动。

定义：

interface ComponentApi
  createMobiComponent<T extends IReactComponent>(name: string, component: T): T;
}

参数：

返回值：IReactComponent，React组件；参见IReactComponent。

getEnumsById

根据枚举类型ID获取枚举列表。

定义：

interface ComponentApi
  getEnumsById: (enumTypeId: string) => EnumValue[];
}

参数：

返回值：EnumValue[]，枚举列表。

EnumValue定义请参见EnumValue。

isChildrenEmpty

判断当前组件是否没有子元素。

定义：

interface ComponentApi
  isChildrenEmpty: (props: { children?: React.ReactNode | undefined }) => boolean;
}

参数：

返回值：boolean，true为没有，false为有。

isEqual

对比两个值是否一样。

定义：

interface ComponentApi
  isEqual: (left: VALUE | AttrMeta, right: VALUE | AttrMeta) => boolean;
}

参数：

返回值：boolean，true为一样；false为不一样。

VALUE定义请参见VALUE。

AttrMeta定义请参见AttrMeta。

formatForDesignTips

给展示的数据添加统一占位符。

定义：

interface ComponentApi
  formatForDesignTips: (value: any) => string;
}

参数：

返回值：string，包装后的内容。

formatValue

格式化值，主要目的是把时间对象、枚举对象和文件对象, 转化为使用的字符串、数字、布尔；

定义：

interface ComponentApi
  formatValue: (value: VALUE, label?: boolean) => string | number | boolean;
}

参数：

返回值：string | number | boolean，格式化后的内容；

VALUE定义请参见VALUE。

formatDate

格式化 DATETIME 类型的数据，方便不同的组件的展示形式保持一致。

格式为 YYYY-MM-DD HH:mm:ss。

定义：

interface ComponentApi
  formatDate: (date: Date) => string;
}

参数：

返回值： string 日期格式化后的字符串。

获取方式

由平台向组件的 Props 内注入，通过 Props pageContext 参数获取。

示例：

import { PropsWithPageContext } from "@mobi/material-api";
import React from "react";


interface Props {}

const ComponentA = (props: PropsWithPageContext<Props>) => {
    
    // 通过props获取pageContext
    props.pageContext;

    return <div>Component A</div>;
}

type PropsWithPageContext<P = {}> = P & {
  pageContext?: PageContext;
};

import React from 'react';
import { PageContext, PropsWithPageContext } from './api';

interface PropsA {}
const ComponentA = (props: PropsWithPageContext<PropsA>) => {
  return <div>component a</div>;
};

interface PropsB {
  pageContext?: PageContext;
}

const ComponentB = (props: PropsB) => {
  return <div>component b</div>;
};

changeChildContextData

改变子组件的上下文数据；调用此方法的场景有2个：

1. 数据容器修改自己children的数据上下文。

   1.1 一种是不传递data，把数据容器加载数据产生的数据上下文向下传递， 比如Data数据容器。

   1.2 另一种是传递data，把数据容器加载的数据，进行拆分，作为新的数据上下文向下传递，比如List Gallery。

2. 传递数据上下文给内部定义的组件（组件内部定义了子组件，并通过createMobiComponent包装为平台组件）。

请参考7. 数据加载了解数据容器和数据上下文相关内容。

定义：

interface PageContext
  changeChildContextData: (
    child: any,
    data?: EntityObject | EntityObject[],
  ) => React.ReactElement | React.ReactElement[];
}

参数：

返回值：React.ReactElement | React.ReactElement[]，React组件元素。

getData

获取当前数据容器加载的实体对象数据（非数据容器组件，则获取最近一层数据容器加载的数据）。

定义：

interface PageContext
  getData: <T extends EntityObject | Array<EntityObject>>() => T | undefined;
}

返回值：EntityObject | Array<EntityObject>，实体对象或实体对象数组。

EntityObject定义请参见EntityObject。

getParentData

获取上层数据容器组件加载的实体对象数据，对于非数据容器来说，和 getData 返回值一样。

定义：

interface PageContext
  getParentData: <T extends EntityObject | Array<EntityObject>>() => T | undefined;
}

返回值：EntityObject | Array<EntityObject>，实体对象或实体数组。

EntityObject定义请参见EntityObject。

isReadonly

判断字段或者实体对象是否只读。

定义：

interface PageContext
  isReadonly: (attrMeta?: AttrMeta | VALUE | contextDataMeta) => boolean;
}

参数：

返回值：boolean，true为只读；false为可读写。

AttrMeta定义请参见AttrMeta。

VALUE定义请参见VALUE。

contextDataMeta请参见contextDataMeta。

getDataSource

获取数据源API接口。

定义：

interface PageContext
  getDataSource: () => DataSource;
}

返回值：DataSource，数据源API接口。

DataSource定义请参见DataSource。

getAttrValue

获取字段数据的API接口。

定义：

interface PageContext
  getAttrValue: <T extends VALUE>(
    meta: AttrMeta | TemplateMeta | VALUE,
    entityObject?: EntityObject,
  ) => AttrValue<T>;
}

参数：

返回值 AttrValue，字段数据的API接口。

interface AttrValue<T extends VALUE> {
  get: () => T | undefined;
  set: (value: T) => void;
}

executeAction

执行事件。

定义：

interface PageContext {
  executeAction: <
    T extends void | VALUE | Array<VALUE> | object | object[] | EntityObject | EntityObject[]
  >(
    meta: ActionMeta,
    options?: {
      eventParams?: Array<VALUE | Array<VALUE> | object | object[] | EntityObject | EntityObject[]>;
    },
  ) => Promise<T>;
}

参数：

返回值：Promise<T>， 不同的事件可能返回值可能不同。

getDataById

根据实体对象ID获取实体对象。

定义：

interface PageContext
  getDataById: (dataId: string) => EntityObject;
}

参数：

返回值：EntityObject，实体对象。

EntityObject定义请参见EntityObject。

getDataByDbId

根据数据库ID获取实体对象。

定义：

interface PageContext
  getDataByDbId: (entityId: string, dbId: string) => EntityObject;
}

参数：

返回值：EntityObject，实体对象。

EntityObject定义请参见EntityObject。

getDataByContextData

根据数据上下文ID获取实体对象。

定义：

interface PageContext
  getDataByContextData: (contextData: string) => EntityObject;
}

参数：

返回值：EntityObject，实体对象。

EntityObject定义请参见EntityObject。

createEntityObject

根据实体ID或实体定义创建实体对象。

定义：

interface PageContext
  createEntityObject: (metaOrId: EntityMeta | string) => EntityObject;
}

参数：

返回值：EntityObject，实体对象。

EntityObject定义请参见EntityObject。

executeExpression

计算表达式或者模板字符串。

定义：

interface PageContext
  executeExpression: (
    expression: string | TemplateMeta,
    options?: { currentObject?: EntityObject },
  ) => VALUE | Array<VALUE>;
}

参数：

返回值：VALUE，数据值对象或数组。

EntityObject定义请参见EntityObject。

VALUE定义请参见VALUE。

getCurrentWebPageType

获取组件所在页面的类型

定义：

interface PageContext
  getCurrentWebPageType: () => 'PC_WEB' | 'H5_WEB';
}

返回值：PC_WEB，桌面Web页面；H5_WEB，移动端H5页面。

获取方式

通过PageContext的 getDataSource API获取。

processDataSource

加载数据源。

定义：

interface DataSource
  processDataSource: (options?: {
    onLoadingStart?: () => void;
    onLoadingFinish?: () => void;
  }) => void;
}

参数：

configDataFilter

配置数据源的过滤、排序、分页参数。

定义：

configDataFilter: (params: RetrieveParams) => void;

export interface Filter {
  field: AttrMeta;
  type:
    | 'ISNULL'
    | 'NOTNULL'
    | 'EQ'
    | 'NEQ'
    | 'GT'
    | 'GTE'
    | 'LT'
    | 'LTE'
    | 'CONTAINS'
    | 'NOTCONTAIN'
    | 'STARTSWITH'
    | 'ENDSWITH'
    | 'BETWEEN';
  values: Array<BOOLEAN | TEXT | CHAR | INTEGER | LONG | DECIMAL | DATETIME | EnumValue>;
}

// 多个字段条件的 与 或 组件
export interface FilterGroup {
  type: 'AND' | 'OR';
  filters: Filter[];
}

// 多个组合的组合，用于支持 与 中有 或， 或者 或 中有 与
export interface FilterParam {
  type: 'AND' | 'OR';
  groups: FilterGroup[];
}

export interface SortParam {
  field: AttrMeta;
  type: 'DESC' | 'ASC' | 'DEFAULT';
}

export interface RetrieveParams {
  filter?: FilterParam;
  sort?: SortParam[];
  page?: {
    // 请求页面，从1开始
    number: number;
    // 每页大小
    size: number;
  };
}

refreshData

刷新数据源。

定义：

interface DataSource
  refreshData: (options?: {
    reload?: boolean;
    onLoadingStart?: () => void;
    onLoadingFinish?: () => void;
  }) => void;
}

参数：

setReadOnly

设置数据源是否只读。

定义：

interface DataSource
  setReadOnly: (readOnly: boolean) => void;
}

参数：

getTotalCount

获取数据总个数。

定义：

interface DataSource
  getTotalCount: () => number;
}

getCurrentPageNumber

获取当前数据源分页页码。

定义：

interface DataSource
  getCurrentPageNumber: () => number;
}

enableCustomPagination

开启自定义逻辑流分页。

定义：

interface DataSource
  enableCustomPagination: (options: { pageSize: number }) => void;
}

参数：

enableCustomSearch

开启自定义逻辑流搜索。

定义：

interface DataSource
  enableCustomSearch: () => void;
}

registerListener

注册数据加载的监听器，每次数据变化时，触发回调。

定义：

interface DataSource
  registerListener: (options: { loadListener?: () => void }) => void;
}

参数：

id

实体对象ID。

dbId

实体对象在数据库中的ID。如果还未提交数据，此字段为空。

get

获取实体对象对应字段的值。

set

更新实体对象对应字段的值。

addAssociation

给实体对象添加关联。

removeAssociation

给实体对象移除关联。

setAssociation

给实体对象设置关联。会把原有的关联移除。

getAssociatedObject

获取关联对象。

返回值，如果是对一关联，应该是实体对象；如果是对多关联，应该是实体对象列表。

meta

获取实体对应的实体定义。

DataSourceSchemaData

数据源模型定义。

EntityAttrSchemaData

实体字段模型定义。

PageEventSchemaData

页面事件模型。定义：

type PageEventSchemaData = string | MobiEvent;

// 事件类型
enum EventType {
  none = 'none',
  insideJump = 'inside_jump',
  outsideJump = 'outside_jump',
  submit = 'submit',
  cancel = 'cancel',
  delete = 'delete',
  callFrontflow = 'call_frontflow',
  callBackendflow = 'call_backendflow',
  callWorkflow = 'call_workflow',
  completeWorkflow = 'complete_workflow',
  openUserTaskpage = 'open_user_taskpage',
  close = 'close',
}

// web外部链接跳转方式
enum WebJumpType {
  blank = 'blank',
  self = 'self',
}

// 小程序跳转方式
enum MiniJumpType {
  redirectTo = 'redirectTo',
  navigateTo = 'navigateTo',
  switchTab = 'switchTab',
}

interface MobiEventOptions {
  targetPage?: string; // 内部跳转,外部跳转
  target?: WebJumpType; // web外部链接跳转方式
  miniJumpType?: MiniJumpType; //小程序跳转方式
  ifCancel?: boolean; // 关闭页面
  onlyInMemory?: boolean; // 删除数据
  flowId?: string; // 调用逻辑流,调用工作流
  flowParams?: string[]; // 调用逻辑流,调用工作流
  userTaskNode?: string; // 完成用户任务
  taskResultNode?: string; // 完成用户任务
  contextData?: string | null; // 内部跳转携带的参数
}

interface MobiEvent {
  type: EventType;
  options?: MobiEventOptions;
}

ResourceFileSchemaData

静态资源文件模型定义。

SizeSchemaData

用于样式的尺寸模型定义。

NavItemSchemaData

导航项模型定义。

TemplateSchemaData

模板字符串模型定义。

StaticValueSchemaData

静态数据的模型数据，联合类型。

定义：

type StaticValueSchemaData =
  | ResourceFileSchemaData
  | BooleanSchemaData
  | CharTextSchemaData
  | IntegerLongDecimalSchemaData;

MultiAttrSchemaDataWith PackMultiAttrSchemaDataWith

字段数组模型数据，包括扩展的参数。

定义：

type AttrSchemaDataWith<Config> = Config & {
  field: EntityAttrSchemaData;
};

type EditNameConfig = {
  name: string;
};

type SearchTypeConfig = {
  searchType: string | boolean;
};

type MultiAttrSchemaDataWith<Config> = Array<AttrSchemaDataWith<Config>> | undefined;

type PackMultiAttrSchemaDataWith<PackKey extends string, Config> = {
  [key in PackKey]?: MultiAttrSchemaDataWith<Config>;
};