关于低代码引擎 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 自定义组件库并集成到项目中。
四、总结
这套低代码引擎是挺强大,想要的功能都有,可定制化程度也高。
但也有一些问题,比如文档的完整性和可读性待提高,导致上手成本略高。各种定义也很繁杂,想要在实际项目中落地,需要花费大量的时间研究规则。
不过总体成本还是比自己从零实现一套低代码系统要低很多,如果没有太多时间从头实现,那借用这一套低代码引擎是个不错的选择。
后续会继续更新关于物料描述、设置器扩展、面板扩展等全套的实现方案,欢迎关注~