跳到主要内容

# material - 物料 API

> @types IPublicApiMaterial
> @since v1.0.0

## 模块简介​

负责物料相关的 API，包括资产包、设计器辅助层、物料元数据和物料元数据管道函数。

## 变量​

### componentsMap​

获取组件 map 结构

    /**
      * 获取组件 map 结构
      * get map of components
      */
    get componentsMap(): { [key: string]: IPublicTypeNpmInfo | ComponentType<any> | object } ;

相关类型：IPublicTypeNpmInfo

## 方法​

### 资产包​

#### setAssets​

设置「资产包」结构

    /**
     * 设置「资产包」结构
     * set data for Assets
     * @returns void
     */
    setAssets(assets: IPublicTypeAssetsJson): void;

相关类型：IPublicTypeAssetsJson

示例 直接在项目中引用 npm 包

    import { material } from '@alilc/lowcode-engine';
    import assets from '@alilc/mc-assets-<siteId>/assets.json';

    material.setAssets(assets);

通过接口动态引入资产包

    import { material, plugins } from '@alilc/lowcode-engine';
    import { IPublicModelPluginContext } from '@alilc/lowcode-types';

    // 动态加载 assets
    plugins.register((ctx: IPublicModelPluginContext) => {
      return {
        name: 'ext-assets',
        async init() {
          try {
            // 将下述链接替换为您的物料描述地址即可。
            const res = await window.fetch('https://fusion.alicdn.com/assets/default@0.1.95/assets.json');
            const assets = await res.text();
            material.setAssets(assets);
          } catch (err) {
            console.error(err);
          };
        },
      };
    }).catch(err => console.error(err));

#### getAssets​

获取「资产包」结构

    /**
     * 获取「资产包」结构
     * get AssetsJson data
     * @returns IPublicTypeAssetsJson
     */
    getAssets(): IPublicTypeAssetsJson;

相关类型：IPublicTypeAssetsJson

示例

    import { material } from '@alilc/lowcode-engine';

    material.getAssets();

#### loadIncrementalAssets​

加载增量的「资产包」结构，该增量包会与原有的合并

    /**
     * 加载增量的「资产包」结构，该增量包会与原有的合并
     * load Assets incrementally, and will merge this with exiting assets
     * @param incrementalAssets
     * @returns
     */
    loadIncrementalAssets(incrementalAssets: IPublicTypeAssetsJson): Promise<void>;

相关类型：IPublicTypeAssetsJson

示例

    import { material } from '@alilc/lowcode-engine';
    import assets1 from '@alilc/mc-assets-<siteId>/assets.json';
    import assets2 from '@alilc/mc-assets-<siteId>/assets.json';

    material.setAssets(assets1);
    material.loadIncrementalAssets(assets2);

更新特定物料的描述文件

    import { material } from '@alilc/lowcode-engine';
    material.loadIncrementalAssets({
      version: '',
      components: [
          {
              "componentName": 'Button',
              "props": [{ name: 'new', title: 'new', propType: 'string' }]
          }
      ],
    })

### 设计器辅助层​

#### addBuiltinComponentAction​

在设计器辅助层增加一个扩展 action

    /**
     * 在设计器辅助层增加一个扩展 action
     * add an action button in canvas context menu area
     * @param action
     */
    addBuiltinComponentAction(action: IPublicTypeComponentAction): void;

相关类型：IPublicTypeComponentAction

示例 新增设计扩展位，并绑定事件

    import { material } from '@alilc/lowcode-engine';

    material.addBuiltinComponentAction({
      name: 'myIconName',
      content: {
          icon: () => 'x',
          title: 'hover title',
          action(node) {
              console.log('myIconName 扩展位被点击');
          }
      },
      important: true,
      condition: true,
    });

#### removeBuiltinComponentAction​

移除设计器辅助层的指定 action

    /**
     * 移除设计器辅助层的指定 action
     * remove a builtin action button from canvas context menu area
     * @param name
     */
    removeBuiltinComponentAction(name: string): void;

##### 内置设计器辅助 name​

- remove：删除
- hide：隐藏
- copy：复制
- lock：锁定，不可编辑
- unlock：解锁，可编辑

示例

    import { material } from '@alilc/lowcode-engine';

    material.removeBuiltinComponentAction('myIconName');

#### modifyBuiltinComponentAction​

修改已有的设计器辅助层的指定 action

    /**
     * 修改已有的设计器辅助层的指定 action
     * modify a builtin action button in canvas context menu area
     * @param actionName
     * @param handle
     */
    modifyBuiltinComponentAction(
        actionName: string,
        handle: (action: IPublicTypeComponentAction) => void,
      ): void;

相关类型：IPublicTypeComponentAction

##### 内置设计器辅助 name​

- remove：删除
- hide：隐藏
- copy：复制
- lock：锁定，不可编辑
- unlock：解锁，可编辑

示例 给原始的 remove 扩展时间添加执行前后的日志

    import { material } from '@alilc/lowcode-engine';

    material.modifyBuiltinComponentAction('remove', (action) => {
      const originAction = action.content.action;
      action.content.action = (node) => {
        console.log('before reomve!');
        originAction(node);
        console.log('after remove!');
      }
    });

### 右键菜单项​

#### addContextMenuOption​

添加右键菜单项

    /**
     * 添加右键菜单项
     * @param action
     */
    addContextMenuOption(action: IPublicTypeContextMenuAction): void;

示例

    import { IPublicEnumContextMenuType } from '@alilc/lowcode-types';

    material.addContextMenuOption({
      name: 'parentItem',
      title: 'Parent Item',
      condition: (nodes) => true,
      items: [
        {
          name: 'childItem1',
          title: 'Child Item 1',
          action: (nodes) => console.log('Child Item 1 clicked', nodes),
          condition: (nodes) => true
        },
        // 分割线
        {
          type: IPublicEnumContextMenuType.SEPARATOR
          name: 'separator.1'
        }
        // 更多子菜单项...
      ]
    });

#### removeContextMenuOption​

删除特定右键菜单项

    /**
     * 删除特定右键菜单项
     * @param name
     */
    removeContextMenuOption(name: string): void;

#### adjustContextMenuLayout​

调整右键菜单项布局，每次调用都会覆盖之前注册的调整函数，只有最后注册的函数会被应用。

    /**
     * 调整右键菜单项布局
     * @param actions
     */
    adjustContextMenuLayout(fn: (actions: IPublicTypeContextMenuItem[]) => IPublicTypeContextMenuItem[]): void;

示例

通过 adjustContextMenuLayout 补充分割线

    material.adjustContextMenuLayout((actions: IPublicTypeContextMenuAction) => {
      const names = ['a', 'b'];
      const newActions = [];
      actions.forEach(d => {
        newActions.push(d);
        if (names.include(d.name)) {
          newActions.push({ type: 'separator' })
        }
      });
      return newActions
    })

### 物料元数据​

#### getComponentMeta​

获取指定名称的物料元数据

    /**
     * 获取指定名称的物料元数据
     * get component meta by component name
     * @param componentName
     * @returns
     */
    getComponentMeta(componentName: string): IPublicModelComponentMeta | null;

相关类型：IPublicModelComponentMeta

示例

    import { material } from '@alilc/lowcode-engine';

    material.getComponentMeta('Input');

#### getComponentMetasMap​

获取所有已注册的物料元数据

      /**
       * 获取所有已注册的物料元数据
       * get map of all component metas
       * @returns
       */
      getComponentMetasMap(): Map<string, IPublicModelComponentMeta>;

相关类型：IPublicModelComponentMeta

示例

    import { material } from '@alilc/lowcode-engine';

    material.getComponentMetasMap();

#### refreshComponentMetasMap​

刷新 componentMetasMap，可触发模拟器里的 components 重新构建

@since v1.1.7

      refreshComponentMetasMap(): void;

### 物料元数据管道函数​

#### registerMetadataTransducer​

注册物料元数据管道函数，在物料信息初始化时执行。

    /**
     * 注册物料元数据管道函数，在物料信息初始化时执行。
     * register transducer to process component meta, which will be
     * excuted during component meta`s initialization
     * @param transducer
     * @param level
     * @param id
     */
    registerMetadataTransducer(
      transducer: IPublicTypeMetadataTransducer,
      level?: number,
      id?: string | undefined
    ): void;

示例 给每一个组件的配置添加高级配置面板，其中有一个是否渲染配置项

    import { material } from '@alilc/lowcode-engine'

    function addonCombine(metadata: TransformedComponentMetadata) {
      const { componentName, configure = {} } = metadata;
      const advanceGroup = [];
      const combined: FieldConfig[] = [];

      advanceGroup.push({
        name: getConvertedExtraKey('condition'),
        title: { type: 'i18n', 'zh-CN': '是否渲染', 'en-US': 'Condition' },
        defaultValue: true,
        setter: [
          {
            componentName: 'BoolSetter',
          },
          {
            componentName: 'VariableSetter',
          },
        ],
        extraProps: {
          display: 'block',
        },
      });

      combined.push({
        name: '#advanced',
        title: { type: 'i18n', 'zh-CN': '高级', 'en-US': 'Advanced' },
        items: advanceGroup,
      });

      return {
        ...metadata,
        configure: {
          ...configure,
          combined,
        },
      };
    }

    material.registerMetadataTransducer(addonCombine, 1, 'parse-func');

删除高级 Tab

    import { material } from '@alilc/lowcode-engine';
    import { IPublicTypeFieldConfig } from '@alilc/lowcode-types';

    material.registerMetadataTransducer((transducer) => {
      const combined: IPublicTypeFieldConfig[] = [];

      transducer.configure.combined?.forEach(d => {
        if (d.name !== '#advanced') {
          combined.push(d);
        }
      });

      return {
        ...transducer,
        configure: {
          ...transducer.configure,
          combined,
        }
      };
    }, 111, 'parse-func');

#### getRegisteredMetadataTransducers​

获取所有物料元数据管道函数

    /**
     * 获取所有物料元数据管道函数
     * get all registered metadata transducers
     * @returns {IPublicTypeMetadataTransducer[]}
     */
    getRegisteredMetadataTransducers(): IPublicTypeMetadataTransducer[];

示例

    import { material } from '@alilc/lowcode-engine'

    material.getRegisteredMetadataTransducers();

## 事件​

### onChangeAssets​

监听 assets 变化的事件

    /**
     * 监听 assets 变化的事件
     * add callback for assets changed event
     * @param fn
     */
    onChangeAssets(fn: () => void): IPublicTypeDisposable;

相关类型：IPublicTypeDisposable

示例

    import { material } from '@alilc/lowcode-engine';

    material.onChangeAssets(() => {
      console.log('asset changed');
    });