为 Farris Vue 通用组件提供“异步加载 + 动态注册”的元组件机制（已在 Flow Canvas 中验证）

## Issue 主题

我在开源之夏活动中实现了异步加载及动态注册 Flow Canvas Node 组件，在实现过程中发现 Farris Vue 通用组件尚未实现类似机制，希望该方案可以对 Farris Vue 通用组件有帮助，现在发表出来供社区讨论。

## 详细描述

**我要反馈** 
[ ] 缺陷
[x] 新特性

异步加载及动态注册Flow Canvas Node，是实现场景化扩展画布，将 Flow Canvas 应用于 AI Agent 工作流、财务报销助手等应用场景的关键技术。我实现的 Flow Canvas 画布节点遵循了 Farris Vue 元组件规范，在现有元组件规范基础上，补充实现动态注册及异步加载技术，具体技术细节包括以下几部分，请参考是否可以接纳为社区通用方案。

### 一、语义化描述元组件

根据 Farris Vue 元组件规范，一个元组件除包括实现其功能的代码外，还包括一系列描述该组件的模型文件，具体为：组件元模型、属性配置、工具箱配置。

以 Fuction Call Node 为例，依据 Farris Vue 元组件规范该组件的元模型如下描述，存储为`function-call-node.schema.json`

```json
{
    "title": "function-call-node",
    "description": "A Farris Component",
    "type": "object",
    "categories": {
        "basic": {
            "description": "Basic Infomation",
            "title": "基本信息",
            "properties": {
                "id": {
                    "description": "组件标识",
                    "title": "标识",
                    "type": "string",
                    "readonly": true
                },
				"type": {
                    "description": "节点类型",
                    "title": "类型",
                    "type": "string",
                    "default": "function-call"
				},
				"method": {
                    "description": "执行至该节点时被调用的方法",
                    "title": "方法",
                    "type": "string"
				}
            }
        }
    }
}
```

属性配置如下描述，存储为`function-call-node.property-config.json`

```json
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://farris-design.gitee.io/function-call.schema.json",
    "title": "Function Call Node",
    "description": "A Farris Flow Canvas Function Call Node",
    "type": "object",
    "allOf": [
        {
            "$ref": "flow-node.schema.json"
        }
    ],
    "properties": {
        "id": {
            "description": "The unique identifier for function call node",
            "type": "string"
        },
        "type": {
            "description": "The type string of function call node",
            "type": "string",
            "default": "function-call"
        },
        "method": {
            "description": "The method that should be called by function call node",
            "type": "string"
        },
        "input": {
            "type": "array",
            "description": "Input ports for this node",
            "items": {
                "$ref": "flow-port.schema.json"
            },
            "default": [
                {
                    "id": "${nodeId}-input",
                    "type": "port",
                    "direction": "input",
                    "position": "left",
                    "autoConnect": true
                }
            ]
        },
        "defaultOutput": {
            "type": "array",
            "description": "Default output ports (when no conditions match)",
            "items": {
                "$ref": "flow-port.schema.json"
            },
            "default": []
        }
    },
    "required": [
        "id",
        "type",
		"mehtod",
        "input"
    ]
}
```

工具箱配置入下描述，该配置会在注册元组件时写入工具箱，不作为独立模型文件存在。

```json
            {
                "id": "function-call",
                "text": "执行函数",
                "description": "函数执行节点",
                "category": "logic"
            }
```

#### 二、元组件注册接口

Farris Vue 元组件规范约定每个元组件需要实现三个接口，分别为：`install`, `register`, `registerDesigner`

其中install接口用于在Vue框架内注册组件；register接口用于向组件字典中注册组件，以便于渲染引擎可以动态创建并渲染组件；registerDesigner接口用于向设计时字典中注册组件，以便于可以在设计时画布中展示组件并进行可视化建模。

同样以 Function Call Node 为例，在该组件的index.ts入口文件中，分别实现以上描述的三个接口。

```typescript

import type { App, Plugin } from 'vue';
import FFunctionCallNode from './src/function-call-node/function-call-node.component';
export * from './src/function-call-node/function-call-node.props';

FFunctionCallNode.install = (app: App) => {
    app.component(FFunctionCallNode.name as string, FFunctionCallNode);
};
FFunctionCallNode.register = (
    componentMap: Record<string, any>, propsResolverMap: Record<string, any>,
    configResolverMap: Record<string, any>, resolverMap: Record<string, any>): void => {
    componentMap['function-call-node'] = FFunctionCallNode;
};
FFunctionCallNode.registerDesigner = (componentMap: Record<string, any>, propsResolverMap: Record<string, any>,
    configResolverMap: Record<string, any>): void => {
    componentMap['function-call-node'] = FFunctionCallNode;
};

export { FFunctionCallNode };

export default FFunctionCallNode as typeof FFunctionCallNode & Plugin;
```

### 三、打包元组件模块

为了实现动态注册和异步加载元组件的技术目标，我将元组件打包为独立的文件。在这里我选择了SystemJS作为打包元组件的模块系统，SystemJS提供了定义模块、定义模块依赖关系以及按需加载模块的机制，符合动态注册和异步加载技术要求。

#### 步骤一：声明打包配置文件

Farris CLI 提供了打包交付物功能，支持多种模块输出格式，以下面的格式为 Function Call Node 节点定义独立打包配置文件`farris-flow-canvas-node.config.mjs`。其中，我在`components/flow-canvas-node`目录下实现 Function Call Node 节点，声明以systemjs模块格式输出打包文件，模块及文件名为`function-call-node`，输出目录为`node-dist`。

```typescript
import { fileURLToPath, URL } from 'node:url';
import banner from 'vite-plugin-banner';

import { formatDate } from 'date-fns';

const currentTime = () => formatDate(new Date(), 'yyyy-MM-dd HH:mm:ss');

export default {
    lib: {
        entry: fileURLToPath(new URL('./components/flow-canvas-node/index.ts', import.meta.url)),
        name: "function-call-node",
        fileName: "function-call-node",
        formats: ['systemjs'],
    },    
    systemjs: true,
    outDir: fileURLToPath(new URL('./node-dist', import.meta.url)),
    externals: {
        include: [''],
        filter: (externals) => {
            return (id) => {
                return externals.find((item) => item && id.indexOf(item) === 0);
            };
        }
    },
    externalDependencies: true,
    minify: 'terser',
    alias: [
        { find: '@farris/ui-vue/components', replacement: fileURLToPath(new URL('./components', import.meta.url)) }
    ],
    plugins: [
        banner('Last Update Time: ' + currentTime())
    ]
};
```

#### 步骤二：声明打包命令

接下来，我在 ui-vue 项目的package.json文件中增加独立打包 Function Call Node 的脚步命令。

在scripts节点下增加`build:flow-nodes:system`节点执行以下命令，其中通过-c参数为Function Call Node节点独立的配置文件`farris-flow-canvas-node.config.mjs`

```json
	"scripts": {
		...
        "build:flow-nodes:system": "farris-cli build-lib -c ./farris-flow-canvas-node.config.mjs -ep"
    }
```

#### 步骤三：打包独立模块文件

通过执行以下命令，可以在node-dist目录下输出Function Call Node 节点的独立模块文件，输出结果为`packages/ui-vue/node-dist/function-call-node.systemjs.js`

```shell
pnpm --filter ui-vue run build:flow-nodes:system
```

### 四、异步加载元组件模块

#### 步骤一：声明配置资源

为实现异步加载元组件模块，我声明了配置文件存储模块资源。

定义ConfigOptions接口声明配置资源

```typescript
export interface ConfigOptions {
    /** 节点组件集合 */
    nodeUrl: string;
    /** 节点元模型集合 */
    nodeSchemasUrl: string;
    /** 节点属性配置集合 */
    propertyConfigUrl: string;
    /** 流程节点工具箱 */
    toolboxUrl: string;
}
```

实现config-defualt.json配置文件，提供配置资源地址

```json
{
    "nodeUrl": "./assets/flow-canvas/node.json",
    "nodeSchemasUrl": "./assets/flow-canvas/node-schema.json",
    "propertyConfigUrl": "./assets/flow-canvas/property-config.json",
    "toolboxUrl": "./assets/flow-canvas/toolbox.json"
}
```

在node.json中声明步骤打包生成的脚步文件

```json
{
    "function-call-node": "/assets/flow-canvas/function-call-node/function-call-node.js"
}
```

在node-schema.json中声明步骤二中定义组件元模型

```json
{
	...
    "function-call-node": "./assets/flow-canvas/function-call-node/function-call-node.schema.json"
}
```

在property-config.json中声明节点属性配置

```typescript
{
    ...
	"function-call-node": "/assets/flow-canvas/function-call-node/function-call-node.property-config.json"
}
```

#### 步骤二：实现异步加载资源

异步加载组件元模型

```typescript
	
	function loadSchema(schemaUrl: string) {
        return new Promise<any[]>((resolve, reject) => {
            axios.get(schemaUrl).then((response) => {
                resolve(response.data);
            });
        });
    }

异步加载组件属性配置文件

```typescript
    function loadConfig(schemaUrl: string) {
        return new Promise<any>((resolve, reject) => {
            axios.get(schemaUrl).then((response) => {
                resolve(response.data);
            });
        });
    }

异步加载组件代码，这里使用SystemJS提供的`System.import`接口加载组件模块

```typescript
    function loadNodeComponent() {
        return new Promise<any[]>((resolve, reject) => {
            axios.get(config.options.nodeUrl).then((response) => {
                if (response && response.data) {
                    const componentSourceMap = response.data;
                    const componentPromises = Object.keys(componentSourceMap).map((key) => {
                        const componentUrl = componentSourceMap[key];
                        return System.import(componentUrl);
                    });
                    Promise.all(componentPromises).then((nodeModules) => {
                        if (nodeModules && Array.isArray(nodeModules) && nodeModules.length) {
                            nodeModules.forEach((nodeModule) => {
                                registerNodeComponent(nodeModule);
                            });
                        }
                        resolve([]);
                    });
                }
            });
        });
    }
```

### 五、动态注册元组件

在步骤五异步加载元组件的实现方案中，调用了三个注册元组件及描述模型的方法，分别是`registerNodeSchema`, `registerPropertyConfig`, `registerNodeComponent`, 下面阐述其实现原理。

注册Flow Canvas Node元模型，分别声明`nodeSchemaMap`和`nodeSchemaResolverMap`存储元模型结构及元模型解释器。

```typescript
export type NodeSchemaResolverFunction = (
    schema: Record<string, any>,
    resolveContext: Record<string, any>
) => Record<string, any>;
export const nodeSchemaMap = {} as Record<string, any>;
export const nodeSchemaResolverMap = {} as Record<string, NodeSchemaResolverFunction | undefined>;

export function registerNodeSchema(schema: Record<string, any>, schemaResolver?: NodeSchemaResolverFunction) {
    nodeSchemaMap[schema.title] = schema;
    nodeSchemaResolverMap[schema.title] = schemaResolver;
}
```

注册属性配置，引用`dynamic-resolver`中的属性配置字典及属性处理函数字典，并向其中注册异步加载的属性配置。

```typescript
	import { propertyConfigSchemaMapForDesigner, propertyEffectMapForDesigner } from "@farris/ui-vue/components/dynamic-resolver";

function registerPropertyConfig(
        schemaType: string, propertyConfig: Record<string, any> = {},
        propertyEffect: (properties: Record<string, any>) => Record<string, any> = (properties: Record<string, any>) => properties
    ) {
        propertyConfigSchemaMapForDesigner[schemaType] = propertyConfig;
        propertyEffectMapForDesigner[schemaType] = propertyEffect;
    }
```

注册Flow Canvas Node 组件，引用`node-map`并通过执行组件的`register`接口注册组件。

```typescript
    import { nodeMap } from "../components/node-map";

### 六、总结

通过以上步骤可以实现异步加载及动态注册Flow Canvas Node，其中涉及的组件字典为Flow Canvas Node专用字典，如果将其拓展为 Farris Vue 组件字典可以应用于通用组件。期待社区讨论将其接收为通用方案。

GVP UBML/farris-vue

内容风险标识

评论 (9)

GVPUBML/farris-vue

内容风险标识