阿里低代码引擎 lowcode-engine 使用详解 - 开发自定义组件并集成

关于低代码引擎 lowcode-engine， 市面上的文章大多是资讯类的，或是浅显的跑个 demo，很少有真正认真使用过的详细文章。本文将使用阿里的低代码引擎实现封装自定义组件，并在 demo 项目中引用自己的自定义组件，同时记录遇到的坑。

阿里的低代码引擎官网：lowcode-engine.cn/

但偶尔官方文档打不开…也可以看语雀上的文档：www.yuque.com/lce/doc

一、运行官方demo

创建低代码应用提供了两种方式：

• 接入编辑器
• 接入运行时

我们先接入编辑器，开启一波三折的集成之旅。

找到 demo git 仓库，clone 下来，然后运行 npm install

// clone demo 到本地
git clone https://github.com/alibaba/lowcode-demo.git
// 安装依赖
npm install
// 运行项目
npm start
复制代码

本想按照上面无脑三部曲就可以把项目跑起来，但还是太天真……

npm install 依赖报错

运行 npm install 会报如下错误

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: @alilc/[email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/react
npm ERR!   peer react@">=16.0.0" from @alifd/[email protected]
npm ERR!   node_modules/@alifd/next
npm ERR!     peer @alifd/next@"1.x" from @alilc/[email protected]
npm ERR!     node_modules/@alilc/lowcode-engine-ext
npm ERR!       dev @alilc/lowcode-engine-ext@"^1.0.0" from the root project
npm ERR!   peer react@">=16.0.0" from @alifd/[email protected]
npm ERR!   node_modules/@alifd/meet-react
npm ERR!     peer @alifd/meet-react@"^2.0.0" from @alifd/[email protected]
npm ERR!     node_modules/@alifd/next
npm ERR!       peer @alifd/next@"1.x" from @alilc/[email protected]
npm ERR!       node_modules/@alilc/lowcode-engine-ext
npm ERR!         dev @alilc/lowcode-engine-ext@"^1.0.0" from the root project
npm ERR!   1 more (react-dom)
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.3.0" from @alilc/[email protected]
npm ERR! node_modules/@alilc/lowcode-engine-ext
npm ERR!   dev @alilc/lowcode-engine-ext@"^1.0.0" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! See /Users/solonnliu/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/solonnliu/.npm/_logs/2022-04-07T02_24_06_472Z-debug.log
复制代码

大意是依赖有冲突，如果要忽略，在后面加上 --force, or --legacy-peer-deps

npm install --force
复制代码

一番周折之后终于安装完依赖。

npm start 报错

你以为这就完了？运行 npm start依然被错误卡住

% npm start

> @alilc/[email protected] start
> build-scripts start --disable-reload --port 5556

@alib/build-scripts 0.1.32
Run `npm install sass` or `yarn add sass` inside your workspace.
复制代码

不过这次还好，只是需要安装 sass，按照提示运行命令：npm install sass

然后再次启动：npm start，这时又有新的问题：

 ERROR  Failed to compile with 1 errors                                                                                                   10:44:51 AM

This dependency was not found:

* react-is in ./node_modules/@formily/next/esm/__builtins__/toArray.js

To install it, you can run: npm install --save react-is
复制代码

依旧按照提示运行 npm install --save react-is

然后再次运行启动命令，终于启动成功了！

npm start

// ……中间省略

Starting the development server at:
 - Local  :  http://localhost:5556/
复制代码

二、开发自己的组件库

如果官方提供的组件库不能满足需求，想拓展自己的组件库，就需要使用引擎提供的项目模板另外新建项目开发组件库。或者在自己原来的项目基础上，安装 build-scripts 和它的低代码开发插件。

我们先使用新开发组件的方式：

官方文档地址：lowcode-engine.cn/docV2/funcv…

组件项目初始化

npm init @alilc/element your-material-name
复制代码

选择组件类型等基本信息这里我们选择 react-组件库，之后便生出我们的组件库项目，目录结构如下：

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

组件开发与调试

# 启动 lowcode 环境进行调试预览
npm run lowcode:dev

# 构建低代码产物
npm run lowcode:build 
复制代码

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

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

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

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

2）新增组件配置项

3）更改当前配置项

实操

上面基本是官方文档关于自定义组件的描述，个人觉得写的还是有点仓促，对开发者而言自定义组件算是比较重要的，文档还是有点少。

按照上面的描述一步步走，最后发现新增的组件显示不出来，会隐藏一些暗坑。

在 src/components下新建一个文件夹 compo，并新建两个文件：Compo.tsx和 index.tsx，其中Compo.tsx是组件的代码， index.tsx主要做导出

// Compo.tsx
import * as React from 'react'
import {createElement} from 'react'

export interface CompoProps {
  text?: string;
}

const Compo: React.FC<CompoProps> = ({text}) => {
  // @ts-ignore
  return (<div>{text || 'demo test'}</div>)
}

export default Compo


// index.tsx
import Compo from "./Compo";
export type {CompoProps} from './Compo'
export default Compo;
复制代码

然后在 src/index.tsx中新增导出 Compo 和 CompoProps

export type {CompoProps} from './components/compo'
export {default as Compo} from './components/compo'
复制代码

这样简单的自定义组件就完成了

注意这里有几个坑点：

• 除了在组件自身的 index.tsx和src/index.tsx导出具体的组件，还要导出组件的 props 类型定义，否则在组件库里找不到。上面的例子，如果只导出 Compo而不导出 CompoProps就渲染不出来。
• 新增一个组件后，需要重新执行命令：npm run lowcode:dev，自带的热更新应该不能监听新增的文件，所以不重启就看不到效果。

发布组件

新创建的组件库在本地调试过后，需要发布到 npm 上之后才能集成到项目中。

检查组件库的 package.json文件的 name在 npm 上是否唯一，如果有重名的会发布失败。

然后执行以下命令发布组件：

npm publish
复制代码

注意需要先到 npm官网 注册 npm 账号，然后通过 npm login登录之后才能 pubulish。

发布完成后打开 npm 官网查看是否发布成功

到这里，恭喜你已经完成了自定义组件的开发和发布了！

三、在 demo 中使用自定义组件库

困境：文档不全

上一步已经完成了自定义组件的开发， 那么如何使用呢？

关于如何使用自定义组件，翻遍官方的文档，没有找到描述特别清晰的文档，没有告诉下一步应该怎么做，只能自己去看 demo 的代码摸索。

分析 demo 源码

遇到文档描述不清晰的地方如何处理呢？最有效的方法是先看页面，找出哪个模块最接近我们想要的答案。

经过分析，发现 demo 中有一个切换组件的下拉框，其中有一项是 “基础 fusion 组件 + 单自定义组件”，有自定义组件的示例，这可能就包含我们想找的。

在页面上找到功能点之后，如何快速定位到代码中呢？可以逐个看目录结构，理解每个文件夹的含义，这种方式比较费时，命名不规范的也很容易被误导。最简单的方式是全局搜关键字，比如搜 “自定义组件”，看到如下结果：

从搜索结果看，基础 fusion 组件 + 单自定义组件属于 basic-fusion-with-single-component 模块，打开目录，果然看到这个模块

模块被我们找到了，接下来就是分析如何使用了。

照猫画虎，尝试引入自定义组件

通过代码和文档介绍得知，组件的配置是在 assets.json中配置的，我们打开 basic-fusion-with-single-component 的 assets.json看有什么内容

一共两万多行……

折叠起来之后，其实就四部分，我们一个个看。

先看 packages，这里定义了每个组件库的地址，找两个看看如何写：

"packages": [
  {
    "title": "fusion组件库",
    "package": "@alifd/next",
    "version": "1.23.0",
    "urls": [
      "https://g.alicdn.com/code/lib/alifd__next/1.23.18/next.min.css",
      "https://g.alicdn.com/code/lib/alifd__next/1.23.18/next-with-locales.min.js"
    ],
    "library": "Next"
  },
  {
    "title": "自定义单个组件",
    "package": "m-220318",
    "version": "1.23.0",
    "urls": [
      "./fixtures/basic-fusion-with-single-component/view.css",
      "./fixtures/basic-fusion-with-single-component/view.js"
    ],
    "library": "M220318"
  }
]
复制代码

可以看到每个组件库的的结构都差不多，自定义单个组件引用的是本地的路径，但我们的组件库是发布出去的，所以不合适我们，第一个 fusion组件库 的方式才是我们需要的。

那这个 packages定义在哪里找呢？回到自定义组件的项目 mini-elements，找到build/lowcode/assets.prod.json

这里面有 packages和 components的定义。注意先在浏览器打开 urls里的两个 url 看能否正常访问。

{
  "packages": [
    {
      "package": "mini-elements",
      "version": "0.1.1",
      "library": "MiniElements",
      "urls": [
        "https://unpkg.com/[email protected]/build/lowcode/view.js",
        "https://unpkg.com/[email protected]/build/lowcode/view.css"
      ],
      "editUrls": [
        "https://unpkg.com/[email protected]/build/lowcode/view.js",
        "https://unpkg.com/[email protected]/build/lowcode/view.css"
      ]
    }
  ],
  "components": [
    {
      "exportName": "MiniElementsMeta",
      "npm": {
        "package": "mini-elements",
        "version": "0.1.1"
      },
      "url": "https://unpkg.com/[email protected]/build/lowcode/meta.js",
      "urls": {
        "default": "https://unpkg.com/[email protected]/build/lowcode/meta.js"
      }
    }
  ],
  "sort": {
    "groupList": [
      "精选组件",
      "原子组件"
    ],
    "categoryList": [
      "基础元素",
      "布局容器类",
      "表格类",
      "表单详情类",
      "帮助类",
      "对话框类",
      "业务类",
      "通用",
      "引导",
      "信息输入",
      "信息展示",
      "信息反馈"
    ]
  },
  "groupList": [
    "精选组件",
    "原子组件"
  ],
  "ignoreComponents": {}
}
复制代码

按照 demo 中其他文件的定义，把需要的字段复制过去即可。

需要改 packages、components、componentList三个地方，需要添加的内容如下：

{
  "version": "1.1.13",
  "packages": [
     {
      "title": "我的自定义组件",
      "package": "mini-elements",
      "version": "0.1.1",
      "library": "MiniElements",
      "urls": [
        "https://unpkg.com/[email protected]/build/lowcode/view.js",
        "https://unpkg.com/[email protected]/build/lowcode/view.css"
      ]
    } 
  ],
  "components": [
    {
      "exportName": "MiniElementsMeta",
      "npm": {
        "package": "mini-elements",
        "version": "0.1.1"
      },
      "url": "https://unpkg.com/[email protected]/build/lowcode/meta.js",
      "urls": {
        "default": "https://unpkg.com/[email protected]/build/lowcode/meta.js"
      }
    }
  ],
   "componentList": [
    {
      "title": "我的自定义组件",
      "icon": "",
      "children": [
        {
          "componentName": "ChartDemo",
          "library": "MiniElements",
          "title": "图表Demo",
          "icon": ""
        },
        {
          "componentName": "ColorfulButton",
          "title": "多彩按钮",
          "description": "这里是多彩按钮的介绍",
          "library": "MiniElements"
        },
        {
          "componentName": "ColorfulInput",
          "title": "多彩Input",
          "description": "这里是多彩按钮ColorfulInput的介绍",
          "library": "MiniElements"
        }
      ]
    },
  ]
}
复制代码

其中 componentList的 children里写的是我们的自定义组件库中导出的具体组件，在这里显示的写出来才会被识别，上面导出了三个组件。

修改完assets.json之后，重新运行 demo:

npm run start
复制代码

可以看到我们的自定义组件出现在了组件库中，拖动到画布里能正常渲染，点击预览也可以正常渲染。

到这里就完成了使用 lowcode-engine 自定义组件库并集成到项目中。

四、总结

这套低代码引擎是挺强大，想要的功能都有，可定制化程度也高。

但也有一些问题，比如文档的完整性和可读性待提高，导致上手成本略高。各种定义也很繁杂，想要在实际项目中落地，需要花费大量的时间研究规则。

不过总体成本还是比自己从零实现一套低代码系统要低很多，如果没有太多时间从头实现，那借用这一套低代码引擎是个不错的选择。

后续会继续更新关于物料描述、设置器扩展、面板扩展等全套的实现方案，欢迎关注~