@cqsjjb/scene-app

场景编辑器组件，通过 iframe 嵌入场景编辑功能。

安装

npm install @cqsjjb/scene-app
# 或
yarn add @cqsjjb/scene-app
# 或
pnpm add @cqsjjb/scene-app

使用方法

基础用法

import { SceneEditor } from '@cqsjjb/scene-app';

function App() {
  const [visible, setVisible] = useState(false);
  const [designCode, setDesignCode] = useState<string>();

  const handleOpenEditor = (code?: string) => {
    setDesignCode(code);
    setVisible(true);
  };

  const handleClose = (data: {
    designCode: string;
    config: {
      title: string;
      content: string;
    };
  }) => {
    console.log('编辑器关闭，返回数据:', data);
    setVisible(false);
    
    // 处理返回的数据
    // data.designCode - 设计code
    // data.config.title - 场景的标题
    // data.config.content - 场景的内容（富文本）
  };

  return (
    <div>
      <button onClick={() => handleOpenEditor()}>新增场景</button>
      <button onClick={() => handleOpenEditor('10001')}>编辑场景</button>
      
      <SceneEditor
        designCode={designCode}
        visible={visible}
        onClose={handleClose}
      />
    </div>
  );
}

自定义主机地址

如果场景编辑器部署在不同的域名或端口，可以使用 host 属性指定：

<SceneEditor
  designCode="10001"
  visible={visible}
  onClose={handleClose}
  host="http://localhost:5173"
  // 最终 iframe src 为: http://localhost:5173/article-layout
/>

自定义完整源地址

如果需要完全自定义 iframe 的源地址，可以使用 src 属性（优先级高于 host）：

<SceneEditor
  designCode="10001"
  visible={visible}
  onClose={handleClose}
  src="http://localhost:5173/article-layout"
  // 如果同时提供了 src 和 host，src 优先级更高
/>

属性优先级说明

• 如果提供了 src，则直接使用 src 作为 iframe 的源地址
• 如果未提供 src 但提供了 host，则使用 ${host}/article-layout 作为源地址
• 如果两者都未提供，则使用 ${window.location.origin}/article-layout 作为源地址

API

SceneEditor

场景编辑器组件。

Props

| 属性 | 说明 | 类型 | 默认值 | 必填 | |------|------|------|--------|------| | host | 主机地址（协议 + 域名 + 端口），用于构建 iframe 的源地址。如果同时提供了 src，则 src 优先级更高 | string | window.location.origin | 否 | | designCode | 设计code，非必填，若未传则认为新增一个场景，若传则认为编辑 | string | - | 否 | | onClose | 关闭事件回调 | (data: { designCode: string; config: { title: string; content: string } }) => void | - | 否 | | src | iframe 的完整源地址。如果提供了 src，则优先使用 src，忽略 host 属性 | string | host + '/article-layout' | 否 | | visible | 是否显示组件 | boolean | true | 否 |

onClose 回调参数

{
  designCode: string;        // 设计code
  config: {
    title: string;          // 场景的标题
    content: string;        // 场景的内容（富文本）
  };
}

特性

• ✅ 通过 createPortal 渲染到 body，避免样式冲突
• ✅ 支持新增和编辑两种模式（通过 designCode 区分）
• ✅ 通过 postMessage 与 iframe 内应用通信
• ✅ TypeScript 支持
• ✅ 完整的类型定义

开发

安装依赖

cd packages
npm install

构建

npm run build

构建完成后，会在 publish 目录生成发布所需的文件，包括：

• index.esm.js - ES Module 格式
• index.cjs.js - CommonJS 格式
• index.d.ts - TypeScript 类型定义
• index.css - 样式文件
• package.json - 发布用的 package.json
• README.md - 文档

发布

构建完成后，进入 publish 目录执行发布：

cd publish
npm publish

或者使用 prepublishOnly 钩子自动构建：

npm publish

这会自动执行 npm run build 后再发布。

注意事项

1. Portal 渲染：组件通过 createPortal 渲染到 document.body，确保页面中已存在 body 元素
2. React 版本：组件依赖 React 16.8+、17.x 或 18.x，请确保项目中已安装 React 和 ReactDOM
3. 同源策略：iframe 的源地址需要与主应用同源，或配置正确的 CORS 策略
4. 消息通信：组件会监听来自 iframe 的 EVENT_CLOSE_SCENE_EDITOR 消息，请确保 iframe 内应用正确发送该消息
5. 样式隔离：组件使用固定定位（position: fixed）和最高层级（z-index: 9999），确保全屏显示
6. iframe 加载：组件会在 iframe 加载完成后自动发送 EVENT_OPEN_SCENE_EDITOR 消息，传递 designCode 参数
7. host 和 src 属性：
   • host 属性只需要提供协议、域名和端口（如：http://localhost:5173），组件会自动拼接 /article-layout 路径
   • src 属性需要提供完整的 URL（如：http://localhost:5173/article-layout）
   • 如果同时提供了 src 和 host，src 的优先级更高
   • 如果两者都未提供，默认使用当前页面的 origin + '/article-layout'

消息协议

发送到 iframe 的消息

当 iframe 加载完成后，组件会发送以下消息：

{
  type: 'EVENT_OPEN_SCENE_EDITOR',
  designCode: string  // 设计code，如果未传则为空字符串
}

接收来自 iframe 的消息

组件监听以下消息：

{
  type: 'EVENT_CLOSE_SCENE_EDITOR',
  designCode: string,
  config: {
    title: string,    // 场景的标题
    content: string   // 场景的内容（富文本）
  }
}

收到此消息后，会调用 onClose 回调函数。

License

ISC