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

今天也想MK代码

于 2025-08-09 19:49:28 发布

阅读量492

点赞数 19

CC 4.0 BY-SA版权

分类专栏：从零打造前端可视化平台(大屏) 文章标签：语言模型

本文链接：https://blog.csdn.net/weixin_42429220/article/details/150113895

从零打造前端可视化平台(大屏) 专栏收录该内容

5 篇文章

订阅专栏

源码

⸻

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

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

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

⸻

为什么选 UMD 格式？

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

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

webpack.config.js

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

打包后：

⸻

数据结构设计

在之前的文章中的 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 用于版本控制

⸻

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 模板在运行时替换：

⸻

主应用渲染 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
• 完全隔离样式 & 全局变量

⸻

版本控制与缓存策略

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

方案：
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.	渲染时严格按照配置的版本加载

⸻

总结

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