lowcode-engine 组件面板详解：资产包解析、分组排序与搜索机制

lowcode-engine 组件面板详解：资产包解析、分组排序与搜索机制

【免费下载链接】lowcode-engineAn enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系项目地址: https://gitcode.com/GitHub_Trending/lo/lowcode-engine

导读

组件面板（Component Panel）是 lowcode-engine 搭建界面中承载并展示组件的核心面板，它负责获取并解析低代码引擎的资产包数据，按照分组（group）与分类（category）规则对组件进行 tab / collapse 两级编排，并提供基于关键词的搜索能力。读完本文，你将掌握资产包数据与面板展示之间的字段映射关系、sort.groupList/sort.categoryList的排序协议、组件低代码 schema 片段（snippets）在拖拽时的插入机制，以及如何为组件配置搜索关键词，从而为上层搭建平台定制一套符合业务需要的组件面板。

组件面板概述：数据从资产包到面板

组件面板顾名思义就是承载组件的面板。它本身并不负责"生产"组件，而是获取并解析传入给低代码引擎的资产包数据，从中得到需要被展示的组件列表，再根据分类、排序规则对组件进行排列，同时提供搜索功能。

这里的"资产包数据"即 低代码引擎资产包协议（Assets 协议）所定义的结构化数据。按该协议，资产包最顶层包含 7 类描述内容：

• version：当前协议版本号；
• packages：低代码编辑器中加载的资源列表（公共库、组件库 CDN 资源等）；
• components：所有组件的描述协议列表；
• sort：用于描述组件面板中的 tab 和 category；
• plugins：设计器插件描述协议列表；
• setters：设计器中设置器描述协议列表；
• extConfig：平台自定义扩展字段。

其中，components与sort是组件面板展示的直接数据来源：前者描述"有哪些组件、每个组件长什么样"，后者描述"这些组件在面板里如何分组、如何排序"。协议中sort属于 AA 级规范（推荐规范，由低代码引擎官方插件支持），定义在协议文档 2.4 sort 章节。

组件信息：面板承载的七类组件元数据

组件面板承载的组件信息包括：

信息项	说明	面板上的呈现方式
组件标题（title）	组件的中文/展示名称	直接可见，用于识别组件
组件截图（screenshot）	组件的快照图片	直接可见，作为组件预览图
组件低代码 schema 片段（snippets）	组件不同状态下的低代码 schema，可有多份	拖拽到设计器时自动插入页面 schema
组件分组（group）	一级分组，决定组件位于组件面板的哪个 tab	作为 tab 分组依据
组件分类（category）	二级分组，决定组件位于同一 tab 下的哪个区域	作为 collapse（折叠区）分组依据
是否隐藏组件	控制组件是否出现在面板中	控制展示/隐藏
关键词（keywords）	用于搜索，聚合 name、title、description、keywords 等字段	作为搜索匹配目标

这些组件信息均通过资产包数据获取。在源码层面，与上述字段一一对应的类型定义位于 packages/types/src/shell/type/component-metadata.ts，其IPublicTypeComponentMetadata接口明确声明了：

• title：title or description；
• screenshot：组件快照；
• snippets：可用片段（见下文）；
• group：一级分组；
• category：二级分组；
• priority：组件优先级排序；
• keywords、tags、description等附加检索字段。

字段更完整的定义可参考 《低代码引擎物料协议规范》 中 2.2.2 组件描述协议 的基础信息表：componentName、title、description、docUrl、screenshot、icon、tags、keywords、devMode、npm、snippets、group、category、priority。其中group用于描述当前组件位于组件面板的哪个 tab，category用于描述组件位于组件面板同一 tab 的哪个区域，priority用于描述组件在同一 category 中的排序。

组件低代码 schema 片段（snippets）与拖拽插入

IPublicTypeSnippet（定义见 packages/types/src/shell/type/snippet.ts）描述组件在面板中可供拖拽的"可用片段"，其内容为组件不同状态下的低代码 schema，可以有多个：

• title：组件分类 title；
• screenshot：snippet 截图；
• schema：待插入的 schema。

从源码注释可以确认其运行机制：用户从组件面板拖入组件到设计器时，会向页面 schema 中插入snippets中定义的组件低代码 schema。也就是说，面板里看到的标题与截图是"皮"，真正起作用的是背后的 schema 片段——一次拖拽本质上是把一段预置的低代码 schema 落到当前编辑页面的节点树上，这与 资产包协议 中Snippet接口（title/screenshot/schema: ElementJSON）的定义完全一致。

组件分组、分类与排序

组件面板采用"两级分组"的编排结构：

• tab（一级）：相同group的组件放在同一个 tab 下；
• collapse（二级）：相同category的组件放在同一个 collapse（折叠区间）中；
• 同时支持对 tab 和 collapse 进行整体排序。

由于这是"整体性"的排序，单个组件自身的信息无法决定该排序，因此在资产包数据根节点新增了sort字段用于指定分组和分类的排序。按 资产包协议 2.4 sort 章节 的定义：

根属性名称	类型	说明	变量支持	默认值
sort.groupList	String[]	组件分组，用于组件面板 tab 展示	-	['精选组件', '原子组件']
sort.categoryList	String[]	组件面板中同一个 tab 下的不同区间用 category 区分，category 的排序依照 categoryList 顺序排列	-	['通用', '数据展示', '表格类', '表单类']

该类型在引擎中的 TypeScript 定义为IPublicTypeComponentSort，见 packages/types/src/shell/type/component-sort.ts：

export interface IPublicTypeComponentSort { /** 用于描述组件面板的 tab 项及其排序，例如：["精选组件", "原子组件"] */ groupList?: string[]; /** 组件面板中同一个 tab 下的不同区间用 category 区分，category 的排序依照 categoryList 顺序排列； */ categoryList?: string[]; }

需要强调的是，groupList/categoryList中的顺序即面板中的展示顺序：groupList决定 tab 从左到右的排列，categoryList决定每个 tab 内折叠区自上而下的排列。面板会将组件按其group/category归入对应位置，未出现在列表中的分组/分类按默认策略处理。

组件自身的 group、category、priority

除了资产包根节点的sort，组件描述本身也携带分组相关信息（见 物料协议基础信息表）：

• group：用于描述当前组件位于组件面板的哪个 tab；
• category：用于描述组件位于组件面板同一 tab 的哪个区域；
• priority：用于描述组件在同一 category 中的排序。

结合IPublicTypeComponentMetadata（component-metadata.ts）可以看到group/category同时支持string | IPublicTypeI18nData，即支持多语言文案，适合国际化搭建平台按当前语言展示分组名。实践中建议约定：组件描述里的group/category取值应尽量与资产包根节点sort.groupList/sort.categoryList中的项保持一致，否则组件会被归入面板的"其他"区域或默认位置。

搜索机制：关键词如何命中组件

组件面板提供搜索能力，其匹配目标是组件元数据中的多个文本字段。按本文档说明，面板会提取组件的 name、title、description、keywords 等字段作为搜索匹配的目标。因此：

• 通过组件名称、组件描述可以直接搜索到对应组件；
• 还可以额外指定一些keywords关键词，用来命中"名称和描述里没有、但业务上希望可被搜到"的词汇；
• keywords既可以是数组（string[]），也可以是字符串（string）类型，两种写法均被支持。

在组件描述协议中，keywords字段被定义为"组件关键词，用于搜索联想"（见 物料协议 2.2.2.2 基础信息），其类型为String，允许为空；IPublicTypeComponentMetadata中keywords?: string[]也印证了数组形式的存在。搜索的实现实际上是多个字段的聚合匹配，即一次搜索会同时拿查询词去比对 name、title、description、keywords，因此为组件补充恰当的关键词可以显著提升其在面板中的可检索性。

实战：构造一份带分组排序的资产包

下面给出一份最小可用的资产包示例，完整演示sort、components与组件元数据字段的配合写法（字段含义以 资产包协议 为准）：

{ "version": "1.1.0", "packages": [ { "package": "@example/biz-components", "version": "1.0.0", "library": "BizComponents", "editUrls": ["https://cdn.example.com/biz-components/view.js"], "urls": ["https://cdn.example.com/biz-components/index.js"] } ], "sort": { "groupList": ["精选组件", "原子组件", "业务组件"], "categoryList": ["通用", "数据展示", "表格类", "表单类"] }, "components": [ { "componentName": "BizTable", "title": "业务表格", "description": "带分页与筛选的业务表格", "keywords": ["table", "列表", "分页"], "group": "业务组件", "category": "表格类", "priority": 1, "npm": { "package": "@example/biz-components", "exportName": "BizTable", "version": "1.0.0" }, "snippets": [ { "title": "业务表格", "schema": { "componentName": "BizTable", "props": { "size": "medium", "pagination": true } } } ] } ] }

将该资产包作为 assets 参数传入引擎初始化后，组件面板会：

1. 解析components，得到组件列表及每个组件的标题、截图、schema 片段、分组、分类、关键词等元数据；
2. 依据sort.groupList依次创建"精选组件 / 原子组件 / 业务组件"三个 tab；
3. 在每个 tab 内依据sort.categoryList创建"通用 / 数据展示 / 表格类 / 表单类"四个折叠区，并把BizTable归入"业务组件"tab 下的"表格类"区域；
4. 当用户搜索"分页"或"table"时，通过 keywords 聚合命中BizTable；
5. 当用户把BizTable拖入画布时，将snippets[0].schema作为节点插入页面 schema。

至此，组件面板的"数据解析 → 分组排序 → 检索 → 拖拽插入"完整链路就打通了。

总结

组件面板是 lowcode-engine 物料体系面向编辑器的窗口：它通过 资产包协议 读取组件描述与排序配置，将group映射为 tab、category映射为 collapse，并通过根节点的sort.groupList/sort.categoryList完成整体排序；组件自身的title、screenshot、snippets、keywords等字段则分别支撑面板展示、拖拽插入与搜索联想。理解这套字段映射关系后，上层搭建平台即可通过定制资产包数据，灵活控制组件面板的分组结构、展示顺序与检索效果，而无需改动引擎本身。

【免费下载链接】lowcode-engineAn enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系项目地址: https://gitcode.com/GitHub_Trending/lo/lowcode-engine