120 lines
3.3 KiB
Markdown
120 lines
3.3 KiB
Markdown
|
# 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`
|