物料扩展

物料简述

物料是页面搭建的原料，按照粒度可分为组件、区块和模板：

  1. 组件：组件是页面搭建最小的可复用单元，其只对外暴露配置项，用户无需感知其内部实现；
  2. 区块：区块是一小段符合低代码协议的 schema，其内部会包含一个或多个组件，用户向设计器中拖入一个区块后可以随意修改其内部内容；
  3. 模板：模板和区块类似，也是一段符合低代码协议的 schema，不过其根节点的 componentName 需固定为 Page，它常常用于初始化一个页面；

低代码编辑器中的物料需要进行一定的配置和处理，才能让用户在低代码平台使用起来。这个过程中，需要一份一份配置文件，也就是资产包。资产包文件中，针对每个物料定义了它们在低代码编辑器中的使用描述。

资产包配置

什么是低代码资产包

物料扩展 - 图1

在低代码 Demo 中，我们可以看到，组件面板不只提供一个组件，组件是以集合的形式提供给低代码平台的，而低代码资产包正是这些组件构成集合的形式。

它背后的接口，在引擎中的定义摘抄如下：

  1. export interface Assets {
  2.   version: string; // 资产包协议版本号
  3.   packages?: Array<Package>; // 大包列表，external与package的概念相似，融合在一起
  4.   components: Array<ComponentDescription> | Array<RemoteComponentDescription>; // 所有组件的描述协议列表
  5.   sort: ComponentSort; // 新增字段，用于描述组件面板中的 tab 和 category
  6. }
  8. export interface ComponentSort {
  9.   groupList?: String[]; // 用于描述组件面板的 tab 项及其排序，例如：["精选组件", "原子组件"]
  10.   categoryList?: String[]; // 组件面板中同一个 tab 下的不同区间用 category 区分，category 的排序依照 categoryList 顺序排列；
  11. }
  13. export interface RemoteComponentDescription {
  14.   exportName: string; // 组件描述导出名字，可以通过 window[exportName] 获取到组件描述的 Object 内容；
  15.   url: string; // 组件描述的资源链接；
  16.   package: { // 组件(库)的 npm 信息；
  17.     npm: string;
  18.   }
  19. }

资产包协议 TS 描述

Demo 中的资产包

在 Demo 项目中，自带了一份默认的资产包：https://github.com/alibaba/lowcode-demo/blob/main/src/universal/assets.json。这份资产包里的物料是我们内部沉淀出的，用户可以通过这套资产包体验引擎提供的搭建、配置能力。

在 Demo 中，调用了如下代码来注册了资产包：

  1. import { material } from '@alilc/lowcode-engine'
  2. // 以任何方式引入 assets
  3. material.setAssets(assets)

注：Demo 中的实际调用，套了一层 injectAssets，这是为了辅助本地调试开发所用的 API。

手工配置资产包

参考 Demo 中的基础 Fusion Assets 定义，如果我们修改 assets.json，我们就能做到配置资产包：

  • packages 对象：我们需要在其中定义这个包的获取方式，如果不定义，就不会被低代码引擎动态加载并对应上组件实例。定义方式是 UMD 的包，低代码引擎会尝试在 window 上寻找对应 library 的实例；
  • components 对象：我们需要在其中定义物料描述，物料描述我们将在下一节继续讲解。

注：此外，我们设计了物料中心链路来集中化存储资产包，托管了资产包依赖的更新等内容。但这部分还未上线，敬请期待。相关文档可在最后一节找到。

物料描述配置

什么是物料描述

在低代码平台中，用户是不同的，有可能是开发、测试、运营、设计，也有可能是销售、行政、HR 等等各种角色。他们大多数不具备专业的前端开发知识，对于低代码平台来说，我们使用组件的流程如下：

  1. 用户通过拖拽/选择组件，在画布中看到组件；
  2. 选中组件，出现组件的配置项；
  3. 修改组件配置项；
  4. 画布更新生效。

当我们选中一个组件，我们可以看到面板右侧会显示组件的配置项。

物料扩展 - 图2

它包含以下内容：

  1. 基础信息：描述组件的基础信息，通常包含包信息、组件名称、标题、描述等。
  2. 组件属性信息：描述组件属性信息，通常包含参数、说明、类型、默认值 4 项内容。
  3. 能力配置/体验增强：推荐用于优化搭建产品编辑体验，定制编辑能力的配置信息。

因此，我们设计了《中后台低代码组件描述协议》来描述一个低代码编辑器中可被配置的内容。

Demo 中的物料描述

我们可以从 Demo 中的 assets.json 找到如下三个物料描述：

  • @alifd/pro-layout：布局组件，放在window.AlifdProLayoutMeta，meta 文件地址；
  • @alifd/fusion-ui：精选组件，放在window.AlifdFusionUiMeta，meta 文件地址；
  • @alilc/lowcode-materials：原子组件，放在 window.AlilcLowcodeMaterialsMeta，meta 文件地址；

引擎中，会尝试调用对应 meta 文件，并注入到全局：

  1. const src = 'https://alifd.alicdn.com/npm/@alifd/pro-layout@1.0.1-beta.5/build/lowcode/meta.js'
  2. const script = document.createElement('script')
  3. script.src = src
  4. document.head.appendChild(script)

然后在 window 上就能拿到对应的物料描述内容了：

物料扩展 - 图3

手工配置物料描述时，可以用这样的方式参考一下 Demo 中的物料描述是如何实现的。

手工配置物料描述

详见：“物料描述详解”章节。

物料的低代码开发

您可以通过本节内容，完成一个组件在低代码编辑器中的配置和调试。

新开发组件

组件项目初始化

  1. npm init @alilc/element your-material-name

选择组件类型

组件 -> <组件组织方式>

物料扩展 - 图4

这里我们选择 react-组件库，之后便生出我们的组件库项目，目录结构如下：

  1. my-materials
  2. ├── README.md
  3. ├── components  (业务组件目录）
  4. │   ├── ExampleComponent              // 业务组件1
  5. │   │   ├── build                     // 【编译生成】【必选】
  6. │   │   │   └── index.html                        // 【编译生成】【必选】可直接预览文件
  7. │   │   ├── lib                       // 【编译生成】【必选】
  8. │   │   │   ├── index.js              // 【编译生成】【必选】js 入口文件
  9. │   │   │   ├── index.scss            // 【编译生成】【必选】css 入口文件
  10. │   │   │   └── style.js                            // 【编译生成】【必选】js 版本 css 入口文件，方便去重
  11. │   │   ├── demo                      // 【必选】组件文档，用于生成组件开发预览，以及生成组件文档
  12. │   │   │   └── basic.md
  13. │   │   ├── src                       // 【必选】组件源码
  14. │   │   │   ├── index.js              // 【必选】，组件出口文件
  15. │   │   │   └── main.scss             // 【必选】，仅包含组件自身样式的源码文件
  16. │   │   ├── README.md                 // 【必选】，组件说明及API            
  17. │   │   └── package.json              // 【必选】
  18. └── └── ExampleComponent2             // 业务组件2

组件开发与调试

  1. # 启动 lowcode 环境进行调试预览
  2. npm run lowcode:dev
  4. # 构建低代码产物
  5. npm run lowcode:build

执行上述命令后会在组件(库)根目录生成一个 lowcode 文件夹，里面会包含每个组件的低代码描述：

物料扩展 - 图5

在 src/components 目录新增一个组件并在 src/index.tsx 中导出，然后再执行 npm run lowcode:dev 时，低代码插件会在 lowcode/<component-name> 目录自动生成新增组件的低代码描述（meta.ts）。

用户可以直接修改低代码描述来修改组件的配置：

1）设置组件的 setter；（上一个章节介绍的设置器，也可以定制设置器用到物料中）

2）新增组件配置项

3）更改当前配置项；

配置示例

隐藏一个 prop

  1. {
  2.   name: 'dataSource',
  3.   condition: () => false,
  4. }

展示样式

  1. {
  2.   name: 'dataSource',
  3.   display: 'accordion' | 'inline' | 'block' | 'plain' | 'popup' | 'entry' // 常用的是 inline(默认), block、entry
  4. }

发布组件

  1. # 在组件根目录下，执行
  2. $ npm publish

组件低代码化

组件低代码化是指，在引入低代码平台之前，我们大多数都是使用源码开发的组件，也就是 ProCode 组件。

在引入低代码平台之后，原来的源码组件是需要转化为低代码物料，这样才能在低代码平台进行消费。

所以接下来会说明，对于已有的源码组件，我们如何把它低代码化。

配置低代码开发环境

在您的组件开发环境中，安装 build-scripts 和它的低代码开发插件：

  1. npm install -D @alifd/build-plugin-lowcode @alib/build-scripts --save-dev

新增 build-scripts 配置文件：build.lowcode.js

  1. module.exports = {
  2.   alias: {
  3.     '@': './src',
  4.   },
  5.   plugins: [
  6.     [
  7.       "@alifd/build-plugin-lowcode",
  8.       {
  9.         engineScope: '@alilc',
  10.       }
  11.     ]
  12.   ],
  13. };

在 package.json 中定义低代码开发相关命令

  1. "lowcode:dev": "build-scripts start --config ./build.lowcode.js",
  2. "lowcode:build": "build-scripts build --config ./build.lowcode.js",

物料扩展 - 图6

开发调试

  1. # 启动低代码开发调试环境
  2. npm run lowcode:dev

组件开发形式还和原来的保持一致，但是新增了一份组件的配置文件，其中配置方式和低代码物料的配置是一样的。

构建

  1. # 构建低代码产物
  2. npm run lowcode:build

发布组件

  1. # 在组件根目录下，执行
  2. npm publish

【未上线】借助物料中心引入低代码物料

本节内容暂未完成上线，仅作功能预告：

对于平台或者用户来说，可能所需要的组件集合是不同的。如果需要自定义组件集合，就需要定制资产包，定制的资产包是配置了一系列组件的，将这份资产包用于引擎即可在引擎中使用自定义的组件集合。

用户可把自己开发的组件和上面默认资产包的组件进行搭配组合，在 Fusion 站点的物料管理平台发布定制资产包：

Step1: 勾选业务组件(可选)

物料扩展 - 图7

Step2: 勾选默认基础组件(可选)

物料扩展 - 图8

step3: 发布资产包

如果勾选了业务组件，发布资产包后，平台提供了资产包预览页面，可在搭建平台 demo 中预览和试用资产包中的物料；

物料扩展 - 图9

方式一：直接在项目中引用 npm 包

用户可在物料站点管理并发布资产包 (npm package)，可以在低代码引擎中直接引用：

  1. import { ILowCodePluginContext, material, plugins } from '@alilc/lowcode-engine'
  2. import assets from '@alife/mc-assets-<siteId>/assets.json'
  4. material.setAssets(assets)

方式二：通过物料中心接口动态引入资产包

  1. import { ILowCodePluginContext, material, plugins } from '@alilc/lowcode-engine'
  3. // 动态加载 assets
  4. plugins.register((ctx: ILowCodePluginContext) => {
  5.   return {
  6.     name: 'ext-assets',
  7.     async init() {
  8.       try {
  9.         // 将下述链接替换为您的物料即可。无论是通过 utils 从物料中心引入，还是通过其他途径如直接引入物料描述
  10.         const res = await window.fetch('https://fusion.alicdn.com/assets/default@0.1.95/assets.json')
  11.         const assets = await res.text()
  12.         material.setAssets(assets)
  13.       } catch (err) {
  14.         console.error(err)
  15.       }
  16.     },
  17.   }
  18. }).catch(err => console.error(err))

默认资产包

为了方便用户通过低代码引擎快速构建一个可用的搭建平台，我们提供了一套默认资产包，这份资产包里的物料是我们内部精细打磨沉淀出来的，用户可以通过这套资产包体验引擎提供的搭建、配置能力，也可以直接用于生产环境。

资产包url：https://fusion.alicdn.com/assets/default@0.1.95/assets.json