# User Scripts 事件开发指南

本文档记录如何为表单设计器添加新的组件事件。

## 添加 Table Cell 事件的完整步骤

以添加 `cellFocus` 和 `cellBlur` 事件为例：

### 第一步：在 Events.ts 中添加枚举值

**文件路径**: `packages/types/form-designer/user-script/Events.ts`

在 `CompEventEnum` 枚举中添加新的事件类型：

```typescript
export enum CompEventEnum {
  // ... 现有事件 ...
  TABLE_CELL_CONTEXT_MENU = "cellContextMenu",
  TABLE_CELL_FOCUS = "cellFocus", // 新增
  TABLE_CELL_BLUR = "cellBlur", // 新增
  TABLE_CELL_ALL_MOUNTED = "cellAllMounted",
  // ...
}
```

### 第二步：在 Table.ts 中添加事件配置

**文件路径**: `packages/form-designer/src/config/user-script/eventInfo/comp/Table.ts`

在 `getTableCompEvents` 数组中添加事件配置：

```typescript
const getTableCompEvents: () => EventItemBO[] = () => [
  // ... 现有事件配置 ...
  {
    name: CompEventEnum.TABLE_CELL_FOCUS,
    label: t("userScript.events.component.tableCellFocus.label"),
    desc: t("userScript.events.component.tableCellFocus.desc"),
  },
  {
    name: CompEventEnum.TABLE_CELL_BLUR,
    label: t("userScript.events.component.tableCellBlur.label"),
    desc: t("userScript.events.component.tableCellBlur.desc"),
  },
  // ...
];
```

### 第三步：在 UseComp.ts 中添加触发函数

**文件路径**: `packages/form-designer/src/config/user-script/hooks/UseComp.ts`

1. 在 `useCompEvent` 函数内部添加处理函数：

```typescript
function handleTableCellFocus(...args: any[]) {
  emitCompEvent(CompEventEnum.TABLE_CELL_FOCUS, args);
}
function handleTableCellBlur(...args: any[]) {
  emitCompEvent(CompEventEnum.TABLE_CELL_BLUR, args);
}
```

2. 在 return 语句中导出函数：

```typescript
return {
  // ... 现有导出 ...
  handleTableCellMouseEnter,
  handleTableCellMouseLeave,
  handleTableCellFocus, // 新增
  handleTableCellBlur, // 新增
  handleTableCellChagne,
  // ...
};
```

### 第四步：添加多语言配置

**文件路径**: `packages/form-designer/src/locales/model/UserScript.json`

在 `userScript.events.component` 节点下添加：

```json
{
  "userScript": {
    "events": {
      "component": {
        // ... 现有配置 ...
        "tableCellFocus": {
          "label": "单元格聚焦",
          "desc": "表格单元格获得焦点时触发"
        },
        "tableCellBlur": {
          "label": "单元格失焦",
          "desc": "表格单元格失去焦点时触发"
        }
      }
    }
  }
}
```

## 通用步骤总结

为任何组件添加新事件的通用流程：

1. **定义事件类型** → `packages/types/form-designer/user-script/Events.ts` 中的 `CompEventEnum`
2. **配置事件信息** → `packages/form-designer/src/config/user-script/eventInfo/comp/` 下的对应组件文件
3. **实现触发函数** → `packages/form-designer/src/config/user-script/hooks/UseComp.ts`
4. **添加多语言** → `packages/form-designer/src/locales/model/UserScript.json`

## 注意事项

- 事件名称使用驼峰命名法（如 `cellFocus`）
- 枚举值使用大写下划线命名法（如 `TABLE_CELL_FOCUS`）
- 多语言 key 采用小驼峰命名（如 `tableCellFocus`）
- 如果事件是钩子函数（需要拦截/校验），需要设置 `isHook: true`
- 如果事件仅供内部使用，设置 `internal: true`