@cqsjjb/jjb-cloud-component

前端云组件库，支持动态加载远程React组件。

特性

• 🚀 动态加载远程云组件
• 🔧 支持组件依赖管理
• 🎨 样式隔离和自动清理
• 📦 CommonJS模块支持
• 🔄 完整的生命周期钩子
• 💪 TypeScript支持

安装

npm install @cqsjjb/jjb-cloud-component

快速开始

基础用法

import React from 'react';
import { CloudComponent } from '@cqsjjb/jjb-cloud-component';

function App() {
  return (
    <CloudComponent
      from="https://example.com/my-component.js"
      componentKey="my-component"
      componentProps={{
        title: "Hello World",
        count: 42
      }}
      onLoadStart={() => console.log('开始加载')}
      onLoadEnd={() => console.log('加载完成')}
      onMounted={(key, ref) => {
        console.log('组件已挂载', key);
        // 可以调用组件方法
        ref.updateData?.({ theme: 'dark' });
      }}
    />
  );
}

高级用法

import React from 'react';
import { CloudComponent } from '@cqsjjb/jjb-cloud-component';

function App() {
  return (
    <CloudComponent
      from="https://cdn.example.com/advanced-component.js"
      componentKey="advanced-component"
      dependencies={{
        'react': React,
        'lodash': require('lodash'),
        'moment': require('moment')
      }}
      cache="force-cache"
      headers={{
        'Authorization': 'Bearer token'
      }}
      initialize={true}
      componentProps={{
        config: { theme: 'dark' },
        data: { items: [] }
      }}
      onLoadStart={() => console.log('开始加载云组件')}
      onLoadEnd={() => console.log('云组件加载完成')}
      onMounted={(key, ref) => {
        console.log(`组件 ${key} 已挂载`);
        // 获取组件配置
        console.log('表单配置:', ref.formItems);
        // 更新组件数据
        ref.updateData?.({ 
          settings: { theme: 'light' },
          dataSource: { items: [1, 2, 3] }
        });
      }}
      onUpdated={(key, ref) => {
        console.log(`组件 ${key} 已更新`, ref);
      }}
      onDestroy={() => console.log('组件已销毁')}
    />
  );
}

API 文档

CloudComponent Props

| 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | from | string | ✅ | 云组件资源地址 | | componentKey | string | ✅ | 组件唯一标识 | | dependencies | Record<string, unknown> | ❌ | 组件依赖 | | cache | CacheStrategy | ❌ | 缓存策略 | | headers | Record<string, string> | ❌ | 请求头 | | initialize | boolean | ❌ | 是否需要初始化 | | componentProps | Record<string, unknown> | ❌ | 组件额外属性 | | onLoadStart | () => void | ❌ | 开始加载回调 | | onLoadEnd | () => void | ❌ | 加载完成回调 | | onMounted | (key: string, ref: ComponentRef) => void | ❌ | 组件挂载回调 | | onUpdated | (key: string, ref: UpdateRef) => void | ❌ | 组件更新回调 | | onDestroy | () => void | ❌ | 组件销毁回调 |

类型定义

type CacheStrategy = 'default' | 'force-cache' | 'no-cache' | 'no-store' | 'only-if-cached' | 'reload';

interface ComponentRef {
  formItems?: Record<string, unknown>;
  updateData?: (settings?: Record<string, unknown>, dataSource?: unknown) => void;
}

interface UpdateRef {
  settings?: Record<string, unknown>;
  dataSource?: unknown;
}

工具函数

useUnMountCloudComponentStyle

手动卸载云组件样式。

import { useUnMountCloudComponentStyle } from '@cqsjjb/jjb-cloud-component';

// 卸载指定样式的云组件
useUnMountCloudComponentStyle('style-id-123');

ImportCloudComponent

手动导入云组件模块。

import { ImportCloudComponent } from '@cqsjjb/jjb-cloud-component';

const { module, styleId, isNewVersion } = await ImportCloudComponent({
  from: 'https://example.com/component.js',
  dependencies: { react: React },
  cache: 'force-cache'
});

云组件开发

组件结构

云组件需要导出以下结构：

// 组件信息（可选，用于版本检测）
const info = {
  name: 'MyComponent',
  version: '1.0.0',
  description: '我的云组件',
  remark: '这是一个示例组件',
  environment: {},
  dependencies: {}
};

// 组件样式（可选）
const style = `
  .my-component { 
    color: blue; 
  }
`;

// 组件实现
function MyComponent(props) {
  return React.createElement('div', { 
    className: 'my-component',
    'data-cloud-component-style-id': '{cloudComponentStyleId}'
  }, props.title);
}

// 导出
module.exports = {
  info,
  default: MyComponent
};

样式处理

云组件中的样式会自动注入到页面中，使用 {cloudComponentStyleId} 占位符会被替换为实际的样式ID。

const style = `
  .my-component-{cloudComponentStyleId} {
    color: red;
  }
`;

注意事项

1. 网络请求: 确保云组件地址可访问
2. 依赖管理: 正确配置组件所需的依赖
3. 样式隔离: 使用样式ID避免样式冲突
4. 错误处理: 实现适当的错误处理机制
5. 版本兼容: 注意新旧版本云组件的兼容性

许可证

MIT

作者

jiaoxiwei