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

·  阅读 6554

关于低代码引擎 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/lowcode-demo@1.0.9
npm ERR! Found: react@18.0.0
npm ERR! node_modules/react
npm ERR!   peer react@">=16.0.0" from @alifd/next@1.25.29
npm ERR!   node_modules/@alifd/next
npm ERR!     peer @alifd/next@"1.x" from @alilc/lowcode-engine-ext@1.0.3
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/meet-react@2.6.7
npm ERR!   node_modules/@alifd/meet-react
npm ERR!     peer @alifd/meet-react@"^2.0.0" from @alifd/next@1.25.29
npm ERR!     node_modules/@alifd/next
npm ERR!       peer @alifd/next@"1.x" from @alilc/lowcode-engine-ext@1.0.3
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/lowcode-engine-ext@1.0.3
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/lowcode-demo@1.0.9 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.tsxindex.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.tsxsrc/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

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

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

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

需要改 packagescomponentscomponentList三个地方,需要添加的内容如下:

{
  "version": "1.1.13",
  "packages": [
     {
      "title": "我的自定义组件",
      "package": "mini-elements",
      "version": "0.1.1",
      "library": "MiniElements",
      "urls": [
        "https://unpkg.com/mini-elements@0.1.1/build/lowcode/view.js",
        "https://unpkg.com/mini-elements@0.1.1/build/lowcode/view.css"
      ]
    } 
  ],
  "components": [
    {
      "exportName": "MiniElementsMeta",
      "npm": {
        "package": "mini-elements",
        "version": "0.1.1"
      },
      "url": "https://unpkg.com/mini-elements@0.1.1/build/lowcode/meta.js",
      "urls": {
        "default": "https://unpkg.com/mini-elements@0.1.1/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"
        }
      ]
    },
  ]
}
复制代码

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

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

npm run start
复制代码

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

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

四、总结

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

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

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

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

分类:
前端
标签:
收藏成功!
已添加到「」, 点击更改