neo-cmp-cli 1.12.8 → 1.12.10

package/template/develop//344/272/213/344/273/266/345/212/250/344/275/234/344/277/235/345/255/230/346/265/201/347/250/213/345/210/206/346/236/220.md

@@ -1,390 +0,0 @@
-# 组件事件配置面板中添加的事件动作保存到 cmpExt 流程分析
-
-## 整体流程概览
-
-```
-用户操作 → 事件面板 → 创建/更新事件实例 → 保存到内存 → 序列化时写入 cmpExt
-```
-
-## 详细流程分析
-
-### 1. 事件配置面板初始化
-
-**文件**: `packages/neo-ui-designer-common/src/designerCmps/comConsole/propEditorCmps/events/collection/component.tsx`
-
-- `EventCollections` 组件负责渲染事件配置面板
-- 在 `componentDidMount` 时调用 `updateEvents()` 初始化事件列表
-- 从两个数据源获取事件：
-  - **事件定义**: `FxAndEvent.getEventDefsByCom(com)` - 从元模型获取组件支持的事件定义
-  - **已保存的事件**: 从 `store.frontendExt.cmpExt` 和 `store.frontendExt.layoutExt` 中获取
-
-```typescript:47:89:packages/neo-ui-designer-common/src/designerCmps/comConsole/propEditorCmps/events/collection/component.tsx
-updateEvents = () => {
-  const com = ComClicker.comSelected;
-  const store = com.$pageCom.$store;
-  const { cmpExt = [], layoutExt = [] } = store.frontendExt ?? {};
-  const netEvents = layoutExt.concat(cmpExt);
-  
-  // 获取事件定义和已保存的事件实例
-  const curEvents = FxAndEvent.getEventDefsByCom(com);
-  const evtFxs = FxAndEvent.getEventsById(com.keyIdentifier);
-  
-  // 合并数据，优先使用本地更新的事件
-  this.setState({
-    events: curEvents.map((eve) => {
-      const nativeEve = evtFxs.find((_) => _.apiKey === eve.apiKey);
-      if (nativeEve) {
-        return { ...eve, ...nativeEve };
-      }
-      const netEve = curNeoEvents.find((_) => _.apiKey === eve.apiKey);
-      if (netEve) {
-        return { ...eve, id: uuid(16), actions: netEve.actions };
-      }
-      return { ...eve, id: uuid(16) };
-    }),
-  });
-};
-```
-
-### 2. 添加事件动作
-
-**文件**: `packages/neo-ui-designer-common/src/designerCmps/comConsole/propEditorCmps/events/event/component.tsx`
-
-- `Event` 组件渲染单个事件及其动作列表
-- 点击"添加行为"按钮时，打开动作配置对话框
-
-```typescript:17:43:packages/neo-ui-designer-common/src/designerCmps/comConsole/propEditorCmps/events/event/component.tsx
-export const Event: React.FC<IEvent> = (event) => {
-  // 创建或获取事件实例
-  const eventIns = FxAndEvent.createEvent(event);
-  const [actions, setActions] = useState(eventIns.actions);
-  
-  // 当 actions 变化时，同步更新事件实例
-  useEffect(() => {
-    eventIns.setActions(actions);
-  }, [actions]);
-
-  // 新增 action
-  const addAction = () => {
-    NeoNavigator.openDialog({
-      bodySchema: {
-        type: 'neoDesignAction',
-        eventName: event.label,
-        eventParams: eventIns.eventParams,
-        cmpKeyIdentifier: event.cmpKeyIdentifier,
-      },
-    }).then((action: any) => {
-      setActions(actions.concat(action)); // 添加到本地状态
-    });
-  };
-```
-
-**关键点**:
-- `FxAndEvent.createEvent(event)` 创建或获取事件实例，存储在 `FxAndEvent.events` 数组中
-- 通过 `useEffect` 监听 `actions` 变化，调用 `eventIns.setActions(actions)` 更新事件实例
-
-### 3. 动作配置对话框
-
-**文件**: `packages/neo-ui-designer-common/src/designerCmps/comConsole/propEditorCmps/events/action/component.tsx`
-
-- `CmpActionConfig` 组件提供动作配置界面
-- 用户配置动作的各种属性（名称、执行条件、执行操作等）
-- 点击"确认"时，创建动作实例并回调
-
-```typescript:359:374:packages/neo-ui-designer-common/src/designerCmps/comConsole/propEditorCmps/events/action/component.tsx
-// 确认回传
-const onConfirm = () => {
-  // 先校验,再保存
-  if (validate()) return;
-  
-  // 创建动作实例
-  const newAction = FxAndEvent.createAction({
-    id: props.id ?? uuid(16),
-    label,
-    execMode,
-    actionType,
-    assignment,
-    condition,
-    function: aFunction,
-  });
-  
-  // 回调给父组件（Event组件）
-  props.onConfirm(newAction);
-  NeoNavigator.goBack();
-};
-```
-
-### 4. 事件实例管理
-
-**文件**: `packages/neo-ui-designer-common/src/marionette/event.fx/index.ts`
-
-`__FxAndEvent__` 类管理所有事件实例：
-
-```typescript:37:183:packages/neo-ui-designer-common/src/marionette/event.fx/index.ts
-export class __FxAndEvent__ {
-  /**
-   * 此次布局编辑中新增的事件实例
-   */
-  private events: NeoEvent[] = [];
-
-  // 创建事件实例
-  createEvent = (props: INeoEvent): NeoEvent => {
-    let event = this.events.find((eve) => {
-      if (eve.id && props.id && eve.id === props.id) {
-        return true;
-      }
-      return false;
-    });
-    if (event) {
-      return event; // 已存在则返回
-    }
-    event = new NeoEvent(props);
-    this.events.push(event); // 添加到内存数组
-    return event;
-  };
-
-  // 创建动作实例
-  createAction = (props: INeoAction) => new NeoAction(props);
-}
-```
-
-**关键点**:
-- `events` 数组存储本次编辑会话中所有创建/修改的事件实例
-- `createEvent` 会检查是否已存在，避免重复创建
-- 事件实例包含 `actions` 数组，存储该事件的所有动作
-
-### 5. 事件实例更新
-
-**文件**: `packages/neo-ui-designer-common/src/marionette/event.fx/event.ts`
-
-`NeoEvent` 类提供更新动作的方法：
-
-```typescript:40:64:packages/neo-ui-designer-common/src/marionette/event.fx/event.ts
-// 增加 action
-addAction = (action: NeoAction) => {
-  this.actions.push(action);
-};
-
-// 删除 action
-delAction = (id) => {
-  this.actions.splice(
-    this.actions.findIndex((ac) => ac.id === id),
-    1
-  );
-};
-
-// 更新 action
-updateAction = (action) => {
-  this.actions = this.actions.map((ac) => {
-    if (ac.id === action.id) {
-      return action;
-    }
-    return ac;
-  });
-};
-
-setActions = (acs) => {
-  this.actions = acs;
-};
-```
-
-### 6. 保存到 cmpExt
-
-**文件**: `packages/neo-ui-designer-common/src/marionette/event.fx/index.ts`
-
-当需要保存布局时，调用 `getEventsDataNet()` 方法将内存中的事件实例转换为接口格式：
-
-```typescript:232:303:packages/neo-ui-designer-common/src/marionette/event.fx/index.ts
-getEventsDataNet = () => {
-  const store = (window as any).$designer.rootCom.$store;
-  
-  // 1. 获取服务端已经保存的 events
-  const _frontendExt = store.frontendExt;
-  const cmpExt = _frontendExt?.cmpExt ? [..._frontendExt.cmpExt] : [];
-  const layoutExt = _frontendExt?.layoutExt ? [..._frontendExt.layoutExt] : [];
-
-  // 2. 将此次布局编辑中新增的事件，合并到服务端数据中
-  for (const evt of this.events) {
-    // 根据事件类型决定保存到 cmpExt 还是 layoutExt
-    let eventList = [];
-    if (evt.isCmpEvent) {
-      eventList = cmpExt; // 组件事件保存到 cmpExt
-    } else {
-      eventList = layoutExt; // 布局事件保存到 layoutExt
-    }
-
-    if (eventList) {
-      // 查找此事件是否已存在
-      const index = eventList.findIndex(
-        (acc) =>
-          evt.cmpKeyIdentifier === acc.cmpKeyIdentifier &&
-          evt.apiKey === acc.apiKey
-      );
-
-      // 如果删除了所有 actions，则删除事件
-      if (evt.actions.length === 0) {
-        if (index !== -1) {
-          eventList.splice(index, 1);
-        }
-      } else {
-        // 更新或添加事件
-        if (index !== -1) {
-          eventList[index] = evt._json(); // 覆盖已存在的事件
-        } else {
-          eventList.push(evt._json()); // 添加新事件
-        }
-      }
-    }
-  }
-
-  return {
-    cmpExt: cmpExt.filter((cmp) =>
-      NeoApp.getComByKId(`${cmp.cmpKeyIdentifier}`)
-    ),
-    layoutExt: layoutExt.filter((lay) =>
-      NeoApp.getComByKId(`${lay.cmpKeyIdentifier}`)
-    ),
-  };
-};
-```
-
-**关键点**:
-- `evt.isCmpEvent` 判断事件类型：`eventCategory === 2` 为组件事件，保存到 `cmpExt`
-- `evt._json()` 方法将事件实例序列化为 JSON 格式，只包含必要字段：
-  ```typescript
-  _json = () => {
-    return pick({ ...this, actions: this.getActions() }, [
-      'cmpKeyIdentifier',
-      'apiKey',
-      'actions',
-    ]);
-  };
-  ```
-
-### 7. 序列化保存
-
-**文件**: `packages/neo-ui-designer-common/src/designer/basic.layout.designer.ts`
-
-设计器在保存布局时调用 `getSerializeData()`：
-
-```typescript:460:476:packages/neo-ui-designer-common/src/designer/basic.layout.designer.ts
-getSerializeData(): any {
-  const layoutRoot = this.rootCom.querySelector(':neoLayoutRoot');
-  const schema = layoutRoot.$serialize();
-
-  const rst = {
-    layoutInfo: this.layoutInfo,
-    layoutCanvas: {
-      cmp: schema,
-      frontendExt: FxAndEvent.getEventsDataNet(), // 获取事件数据
-    },
-  };
-
-  return rst;
-}
-```
-
-## 数据流向图
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  用户操作：在事件配置面板中添加动作                           │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Event 组件                                                  │
-│  - FxAndEvent.createEvent(event) 创建/获取事件实例          │
-│  - setActions(actions) 更新事件实例的 actions 数组          │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│  __FxAndEvent__ 类                                           │
-│  - events: NeoEvent[] 存储所有事件实例                       │
-│  - createEvent() 创建事件实例                                │
-│  - createAction() 创建动作实例                               │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│  NeoEvent 类                                                 │
-│  - actions: NeoAction[] 存储动作列表                         │
-│  - setActions() 更新动作列表                                 │
-│  - _json() 序列化为接口格式                                  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│  getEventsDataNet() 方法                                     │
-│  - 遍历 events 数组                                         │
-│  - 根据 isCmpEvent 判断保存到 cmpExt 或 layoutExt            │
-│  - 调用 evt._json() 序列化                                  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│  getSerializeData() 方法                                     │
-│  - 调用 FxAndEvent.getEventsDataNet()                       │
-│  - 返回包含 frontendExt 的序列化数据                         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│  保存到后端                                                  │
-│  - frontendExt.cmpExt 包含组件事件配置                       │
-│  - frontendExt.layoutExt 包含布局事件配置                    │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 关键数据结构
-
-### 事件实例 (NeoEvent)
-```typescript
-{
-  id: string;
-  label: string;
-  apiKey: string;              // 事件标识
-  eventCategory: number;        // 2=组件事件, 其他=布局事件
-  cmpKeyIdentifier: string;     // 组件标识
-  actions: NeoAction[];         // 动作列表
-}
-```
-
-### 动作实例 (NeoAction)
-```typescript
-{
-  id: string;
-  label: string;
-  execMode: number;             // 执行模式：1=总是执行, 2=条件执行
-  actionType: number;           // 动作类型：1=执行函数, 2=赋值
-  assignment: Array<...>;      // 赋值规则（当 actionType=2 时）
-  condition: string;            // 执行条件（当 execMode=2 时）
-  function: {...};              // 函数配置（当 actionType=1 时）
-}
-```
-
-### cmpExt 中的事件数据格式
-```typescript
-{
-  cmpKeyIdentifier: string;     // 组件标识
-  apiKey: string;              // 事件标识
-  actions: Array<{             // 动作列表（已序列化）
-    id: string;
-    label: string;
-    execMode: number;
-    actionType: number;
-    // ... 其他动作属性
-  }>;
-}
-```
-
-## 总结
-
-1. **内存管理**: 事件实例存储在 `FxAndEvent.events` 数组中，只在编辑会话期间存在
-2. **实时更新**: 用户添加/修改/删除动作时，立即更新内存中的事件实例
-3. **延迟保存**: 只有在保存布局时，才调用 `getEventsDataNet()` 将内存数据写入 `cmpExt`
-4. **类型区分**: 根据 `eventCategory` 判断是组件事件（保存到 `cmpExt`）还是布局事件（保存到 `layoutExt`）
-5. **数据合并**: `getEventsDataNet()` 会将内存中的事件与已保存的事件合并，更新或新增
-
-