源码

⸻

支持 UMD 自定义组件与版本控制：从 Schema 到动态渲染

在低代码平台或可视化大屏 SDK 中，支持用户上传自定义组件 是一个必备能力。
而在 React 场景下，自定义组件通常以 UMD 格式 打包并暴露为全局变量。

本篇文章，我们将介绍：
1. UMD 组件在 Schema 中的定义方式
2. React 版本隔离与 iframe 渲染
3. 版本控制与缓存策略

⸻

1. 为什么选 UMD 格式？

UMD（Universal Module Definition） 是一种兼容 AMD、CommonJS 和全局变量的打包格式，常见特性：
• 可以直接用

对于用户上传的 React 组件，我们可以这样打包：

webpack.config.js

output: {
library: ‘MyCustomComponent’, // globalName
libraryTarget: ‘umd’,
},

打包后：

⸻

2. 数据结构设计

在之前的文章中的 MaterialItem 里，我们已经为自定义组件设计了字段：

export interface MaterialItem {id: string;name: string;type: 'builtin' | 'custom';icon?: string;// 内置组件component?: React.ComponentType<any>;// 自定义组件url?: string;                // UMD 地址globalName?: string;         // 全局变量名version?: string;            // 版本号configSchema?: Record<string, any>;
}

当 type = custom 时：
• url 是脚本地址
• globalName 是 UMD 入口变量
• version 用于版本控制

⸻

3. React 版本隔离：为什么要用 iframe？

直接在主应用 eval 用户 UMD 脚本可能遇到：
• React 版本冲突（Hooks API 不兼容）
• 样式污染（CSS 全局作用域）
• 全局变量污染（window 上的其他库）

解决方案：
• iframe 沙箱加载（硬隔离）
• iframe 内单独加载用户指定版本的 React
• 再加载用户的 UMD 组件脚本

⸻

3.1 iframe 沙箱 HTML 模板

⸻

3.2 React 版本动态切换

用户在 MaterialItem 中可以指定：

reactVersion: ‘17’ | ‘18’;

iframe 模板在运行时替换：

⸻

4. 主应用渲染 UMD 组件

// IframeRenderer.tsx
import React, { useEffect, useRef } from 'react';interface IframeRendererProps {url: string;globalName: string;props?: Record<string, any>;reactVersion: string;
}export const IframeRenderer: React.FC<IframeRendererProps> = ({url, globalName, props, reactVersion
}) => {const iframeRef = useRef<HTMLIFrameElement>(null);useEffect(() => {const iframe = iframeRef.current;if (!iframe) return;iframe.onload = () => {iframe.contentWindow?.renderCustomComponent(url, globalName, props || {});};iframe.src = `/iframe-template.html?reactVersion=${reactVersion}`;}, [url, globalName, props, reactVersion]);return <iframe ref={iframeRef} style={{ width: '100%', height: '100%' }} />;
};

这样：
• 主应用不会直接运行用户代码
• 用户组件在 iframe 中加载指定版本 React
• 完全隔离样式 & 全局变量

⸻

5. 版本控制与缓存策略

问题：如果用户上传了多个版本的同一组件，如何管理？

方案：
1. 物料库管理：每个 MaterialItem 存版本号
2. 缓存策略：
• url 加上版本 query：my-component.umd.js?v=1.0.0
• 浏览器可缓存不同版本脚本
3. 页面配置绑定版本：

{materialId: 'chart-bar',version: '1.0.0',url: '/components/chart-bar@1.0.0.umd.js'
}

4.	渲染时严格按照配置的版本加载

⸻

6. 总结

这套方案的优势：
• 完全隔离：iframe 沙箱 + React 独立版本
• 版本可控：不同页面、不同组件可用不同版本
• 通用 Schema：内置 & 自定义组件共用同一套数据结构