@windypro-rourou/dsh-eda 0.1.4 → 0.1.5

package/skill/references/classes/PCB_Event.md

@@ -1,1081 +1,1166 @@
-# PCB\_Event class
-
-PCB & footprint / event class
-
-## Signature
-
-```typescript
-class PCB_Event
-```
-
-## Remarks
-
-Register an event callback
-
-## Methods
-
-<table><thead><tr><th>
-
-Method
-
-</th><th>
-
-Modifiers
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-[addCrossProbeSelectEventListener(id, callFn)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-**_(BETA)_** Add a cross-probe selection event listener
-
-</td></tr>
-<tr><td>
-
-[addMouseEventListener(id, eventType, callFn, onlyOnce)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-**_(BETA)_** Add a mouse event listener
-
-</td></tr>
-<tr><td>
-
-[addNetEventListener(id, eventType, callFn, onlyOnce)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-**_(BETA)_** Add a net event listener
-
-</td></tr>
-<tr><td>
-
-[addPrimitiveEventListener(id, eventType, callFn, onlyOnce)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-**_(BETA)_** Add a primitive event listener
-
-</td></tr>
-<tr><td>
-
-[addRayTracerEngine3DViewCameraChangeEventListener(id, callFn, onlyOnce)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-**_(BETA)_** Add a ray tracer engine 3D preview camera change (dragging the 3D model) event listener
-
-</td></tr>
-<tr><td>
-
-[addRayTracerEngine3DViewClickMaterialEventListener(id, callFn, onlyOnce)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-**_(BETA)_** Add a ray tracer engine 3D preview material click event listener
-
-</td></tr>
-<tr><td>
-
-[addRealTimeDrcResultEventListener(id, eventType, callFn)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-**_(BETA)_** Add a real-time DRC result event listener
-
-</td></tr>
-<tr><td>
-
-[isEventListenerAlreadyExist(id)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-Query whether the event listener exists
-
-</td></tr>
-<tr><td>
-
-[removeEventListener(id)](./PCB_Event.md)
-
-</td><td>
-
-</td><td>
-
-Remove Event listener
-
-</td></tr>
-</tbody></table>
-
----
-
-## 方法详情
-
-### addcrossprobeselecteventlistener
-
-# PCB\_Event.addCrossProbeSelectEventListener() method
-
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-Add a cross-probe selection event listener
-
-## Signature
-
-```typescript
-function addCrossProbeSelectEventListener(
-	id: string,
-	callFn: (props: any) => void | Promise<void>,
-): void;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID, used to prevent duplicate event registration
-
-</td></tr>
-<tr><td>
-
-callFn
-
-</td><td>
-
-(props: any) =&gt; void \| Promise&lt;void&gt;
-
-</td><td>
-
-The callback function triggered when the event fires
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-void
-
-## Remarks
-
-Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_cross_probe';
-
-// 1. 注册交叉选择事件监听（回调在用户执行交叉选中时触发，本例不依赖实际触发）
-eda.pcb_Event.addCrossProbeSelectEventListener(listenerId, (props) => {
-	console.log('crossProbeSelect:', JSON.stringify(props));
-});
-
-// 2. 回读确认注册成功（同 id 重复注册会被防重机制忽略）
-const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('registered:', registered);
-
-// 3. 清理监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-```
-
-### addmouseeventlistener
-
-# PCB\_Event.addMouseEventListener() method
-
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-Add a mouse event listener
-
-## Signature
-
-```typescript
-function addMouseEventListener(
-	id: string,
-	eventType: 'all' | EPCB_MouseEventType,
-	callFn: (
-		eventType: EPCB_MouseEventType,
-		props: [
-			{
-				primitiveId: string;
-				primitiveType: EPCB_PrimitiveType;
-				net?: undefined | string;
-				designator?: undefined | string;
-				parentComponentPrimitiveId?: undefined | string;
-				parentComponentDesignator?: undefined | string;
-			},
-		],
-	) => void | Promise<void>,
-	onlyOnce?: boolean,
-): void;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID, used to prevent duplicate event registration
-
-</td></tr>
-<tr><td>
-
-eventType
-
-</td><td>
-
-'all' \| [EPCB\_MouseEventType](../enums/EPCB_MouseEventType.md)
-
-</td><td>
-
-Event type
-
-</td></tr>
-<tr><td>
-
-callFn
-
-</td><td>
-
-(eventType: [EPCB\_MouseEventType](../enums/EPCB_MouseEventType.md)<!-- -->, props: \[{ primitiveId: string; primitiveType: [EPCB\_PrimitiveType](../enums/EPCB_PrimitiveType.md)<!-- -->; net?: undefined \| string; designator?: undefined \| string; parentComponentPrimitiveId?: undefined \| string; parentComponentDesignator?: undefined \| string }\]) =&gt; void \| Promise&lt;void&gt;
-
-</td><td>
-
-The callback function triggered when the event fires
-
-</td></tr>
-<tr><td>
-
-onlyOnce
-
-</td><td>
-
-boolean
-
-</td><td>
-
-_(Optional)_ Whether to listen only once
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-void
-
-## Remarks
-
-Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_mouse_event';
-
-// 1. 注册鼠标事件监听，eventType 用 'all' 接收全部鼠标事件，onlyOnce 为 false 持续监听
-eda.pcb_Event.addMouseEventListener(
-	listenerId,
-	'all',
-	(eventType, props) => {
-		// 回调在用户画布操作时触发；props 是命中图元的信息数组
-		console.log('mouseEvent:', eventType, JSON.stringify(props));
-	},
-	false
-);
-
-// 2. 回读确认注册成功
-const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('registered:', registered);
-
-// 3. 清理监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-```
-
-### addneteventlistener
-
-# PCB\_Event.addNetEventListener() method
-
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-Add a net event listener
-
-## Signature
-
-```typescript
-function addNetEventListener(
-	id: string,
-	eventType: 'all' | EPCB_NetEventType,
-	callFn: (eventType: EPCB_NetEventType, props: [{ net: string }]) => void | Promise<void>,
-	onlyOnce?: boolean,
-): void;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID, used to prevent duplicate event registration
-
-</td></tr>
-<tr><td>
-
-eventType
-
-</td><td>
-
-'all' \| [EPCB\_NetEventType](../enums/EPCB_NetEventType.md)
-
-</td><td>
-
-Event type
-
-</td></tr>
-<tr><td>
-
-callFn
-
-</td><td>
-
-(eventType: [EPCB\_NetEventType](../enums/EPCB_NetEventType.md)<!-- -->, props: \[{ net: string }\]) =&gt; void \| Promise&lt;void&gt;
-
-</td><td>
-
-The callback function triggered when the event fires
-
-</td></tr>
-<tr><td>
-
-onlyOnce
-
-</td><td>
-
-boolean
-
-</td><td>
-
-_(Optional)_ Whether to listen only once
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-void
-
-## Remarks
-
-Net select event only
-
-1. When the net option is selected in the filter panel and a net is selected on the canvas
-
-2. When a net is selected in Engineering Design -<!-- -->&gt; Nets
-
-the event will be triggered
-
-Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_net_event';
-
-// 1. 注册网络事件监听，eventType 用 'all' 接收全部网络事件
-eda.pcb_Event.addNetEventListener(
-	listenerId,
-	'all',
-	(eventType, props) => {
-		// 回调在网络选中变化时触发；props 是网络信息数组
-		console.log('netEvent:', eventType, JSON.stringify(props));
-	},
-	false
-);
-
-// 2. 回读确认注册成功
-const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('registered:', registered);
-
-// 3. 清理监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-```
-
-### addprimitiveeventlistener
-
-# PCB\_Event.addPrimitiveEventListener() method
-
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-Add a primitive event listener
-
-## Signature
-
-```typescript
-function addPrimitiveEventListener(
-	id: string,
-	eventType: 'all' | EPCB_PrimitiveEventType,
-	callFn: (
-		eventType: EPCB_PrimitiveEventType,
-		props: [
-			{
-				primitiveId: string;
-				primitiveType: EPCB_PrimitiveType;
-				net?: undefined | string;
-				designator?: undefined | string;
-				parentComponentPrimitiveId?: undefined | string;
-				parentComponentDesignator?: undefined | string;
-			},
-		],
-	) => void | Promise<void>,
-	onlyOnce?: boolean,
-): void;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID, used to prevent duplicate event registration
-
-</td></tr>
-<tr><td>
-
-eventType
-
-</td><td>
-
-'all' \| [EPCB\_PrimitiveEventType](../enums/EPCB_PrimitiveEventType.md)
-
-</td><td>
-
-Event type
-
-</td></tr>
-<tr><td>
-
-callFn
-
-</td><td>
-
-(eventType: [EPCB\_PrimitiveEventType](../enums/EPCB_PrimitiveEventType.md)<!-- -->, props: \[{ primitiveId: string; primitiveType: [EPCB\_PrimitiveType](../enums/EPCB_PrimitiveType.md)<!-- -->; net?: undefined \| string; designator?: undefined \| string; parentComponentPrimitiveId?: undefined \| string; parentComponentDesignator?: undefined \| string }\]) =&gt; void \| Promise&lt;void&gt;
-
-</td><td>
-
-The callback function triggered when the event fires
-
-</td></tr>
-<tr><td>
-
-onlyOnce
-
-</td><td>
-
-boolean
-
-</td><td>
-
-_(Optional)_ Whether to listen only once
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-void
-
-## Remarks
-
-Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_primitive_event';
-const events = [];
-
-// 1. 注册图元事件监听，eventType 用 'all' 接收全部图元事件
-eda.pcb_Event.addPrimitiveEventListener(
-	listenerId,
-	'all',
-	(eventType, props) => {
-		events.push({ eventType, primitiveType: props?.[0]?.primitiveType });
-	},
-	false
-);
-
-// 2. 创建一个测试焊盘，触发图元 add 事件
-const pad = await eda.pcb_PrimitivePad.create(1, '1', 5000, 3000, 0, ['ELLIPSE', 60, 60], '', null, 0, 0, 0, false, 0);
-await new Promise(r => setTimeout(r, 500));
-
-// 3. 删除测试焊盘，再触发一次图元删除事件（同时清理测试图元）
-await eda.pcb_PrimitivePad.delete([pad.getState_PrimitiveId()]);
-await new Promise(r => setTimeout(r, 500));
-
-// 4. 观察两次操作分别触发的事件
-console.log('events:', JSON.stringify(events));
-
-// 5. 清理监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-```
-
-### addraytracerengine3dviewcamerachangeeventlistener
-
-# PCB\_Event.addRayTracerEngine3DViewCameraChangeEventListener() method
-
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-Add a ray tracer engine 3D preview camera change (dragging the 3D model) event listener
-
-## Signature
-
-```typescript
-function addRayTracerEngine3DViewCameraChangeEventListener(
-	id: string,
-	callFn: (props: {
-		position: { x: number; y: number; z: number };
-		rotation: { x: number; y: number; z: number };
-		focalLength: number;
-	}) => void | Promise<void>,
-	onlyOnce?: boolean,
-): void;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID, used to prevent duplicate event registration
-
-</td></tr>
-<tr><td>
-
-callFn
-
-</td><td>
-
-(props: { position: { x: number; y: number; z: number }; rotation: { x: number; y: number; z: number }; focalLength: number }) =&gt; void \| Promise&lt;void&gt;
-
-</td><td>
-
-The callback function triggered when the event fires
-
-</td></tr>
-<tr><td>
-
-onlyOnce
-
-</td><td>
-
-boolean
-
-</td><td>
-
-_(Optional)_ Whether to listen only once
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-void
-
-## Remarks
-
-Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error` ADD since EDA v4
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_3d_camera';
-
-// 1. 注册相机变动监听（回调在 3D 预览拖动时触发，本例不依赖实际触发）
-eda.pcb_Event.addRayTracerEngine3DViewCameraChangeEventListener(
-	listenerId,
-	(props) => {
-		console.log('cameraChange:', JSON.stringify(props));
-	}
-);
-
-// 2. 回读确认注册成功
-const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('registered:', registered);
-
-// 3. 清理监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-```
-
-### addraytracerengine3dviewclickmaterialeventlistener
-
-# PCB\_Event.addRayTracerEngine3DViewClickMaterialEventListener() method
-
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-Add a ray tracer engine 3D preview material click event listener
-
-## Signature
-
-```typescript
-function addRayTracerEngine3DViewClickMaterialEventListener(
-	id: string,
-	callFn: (props: { materialId: number; material: any }) => void | Promise<void>,
-	onlyOnce?: boolean,
-): void;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID, used to prevent duplicate event registration
-
-</td></tr>
-<tr><td>
-
-callFn
-
-</td><td>
-
-(props: { materialId: number; material: any }) =&gt; void \| Promise&lt;void&gt;
-
-</td><td>
-
-The callback function triggered when the event fires
-
-</td></tr>
-<tr><td>
-
-onlyOnce
-
-</td><td>
-
-boolean
-
-</td><td>
-
-_(Optional)_ Whether to listen only once
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-void
-
-## Remarks
-
-Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error` ADD since EDA v4
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_3d_material';
-
-// 1. 注册点击材质监听（回调在 3D 预览点击材质时触发，本例不依赖实际触发）
-eda.pcb_Event.addRayTracerEngine3DViewClickMaterialEventListener(
-	listenerId,
-	(props) => {
-		console.log('clickMaterial:', JSON.stringify(props));
-	}
-);
-
-// 2. 回读确认注册成功
-const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('registered:', registered);
-
-// 3. 清理监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-```
-
-### addrealtimedrcresulteventlistener
-
-# PCB\_Event.addRealTimeDrcResultEventListener() method
-
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-Add a real-time DRC result event listener
-
-## Signature
-
-```typescript
-function addRealTimeDrcResultEventListener(
-	id: string,
-	eventType: 'all',
-	callFn: (eventType: undefined, props: [{ drcResult: any }]) => void | Promise<void>,
-): void;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID, used to prevent duplicate event registration
-
-</td></tr>
-<tr><td>
-
-eventType
-
-</td><td>
-
-'all'
-
-</td><td>
-
-Event type
-
-</td></tr>
-<tr><td>
-
-callFn
-
-</td><td>
-
-(eventType: undefined, props: \[{ drcResult: any }\]) =&gt; void \| Promise&lt;void&gt;
-
-</td><td>
-
-The callback function triggered when the event fires
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-void
-
-## Remarks
-
-Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_drc_result';
-
-// 1. 注册实时 DRC 结果监听，eventType 固定为 'all'
-eda.pcb_Event.addRealTimeDrcResultEventListener(
-	listenerId,
-	'all',
-	(eventType, props) => {
-		// 回调在实时 DRC 检出违规时触发；props 是 DRC 结果数组
-		console.log('drcResult:', JSON.stringify(props));
-	}
-);
-
-// 2. 回读确认注册成功
-const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('registered:', registered);
-
-// 3. 清理监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-```
-
-### iseventlisteneralreadyexist
-
-# PCB\_Event.isEventListenerAlreadyExist() method
-
-Query whether the event listener exists
-
-## Signature
-
-```typescript
-function isEventListenerAlreadyExist(id: string): boolean;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-boolean
-
-Whether the event listener exists
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_event_exist';
-
-// 1. 注册前查询：应为 false
-const before = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('before:', before);
-
-// 2. 注册一个鼠标事件监听使 id 生效
-eda.pcb_Event.addMouseEventListener(listenerId, 'all', () => {}, false);
-
-// 3. 注册后查询：应为 true
-const after = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('after:', after);
-
-// 4. 移除后查询：应回到 false
-eda.pcb_Event.removeEventListener(listenerId);
-const afterRemove = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('afterRemove:', afterRemove);
-```
-
-### removeeventlistener
-
-# PCB\_Event.removeEventListener() method
-
-Remove Event listener
-
-## Signature
-
-```typescript
-function removeEventListener(id: string): boolean;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-</th><th>
-
-Type
-
-</th><th>
-
-Description
-
-</th></tr></thead>
-<tbody><tr><td>
-
-id
-
-</td><td>
-
-string
-
-</td><td>
-
-Event ID
-
-</td></tr>
-</tbody></table>
-
-## Returns
-
-boolean
-
-Whether Remove Specify event listener
-
-## Example
-
-```javascript
-const listenerId = '嘉立创示例_event_remove';
-
-// 1. 先注册一个鼠标事件监听作为移除目标
-eda.pcb_Event.addMouseEventListener(listenerId, 'all', () => {}, false);
-const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('registered:', registered);
-
-// 2. 移除该监听
-const removed = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removed:', removed);
-
-// 3. 回读确认已不存在
-const existAfter = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
-console.log('existAfter:', existAfter);
-
-// 4. 重复移除同一 id：返回 false（本就未注册）
-const removedAgain = eda.pcb_Event.removeEventListener(listenerId);
-console.log('removedAgain:', removedAgain);
-```
+# PCB\_Event class
+
+PCB &amp; footprint / event class
+
+## Signature
+
+```typescript
+class PCB_Event
+```
+
+## Remarks
+
+Register an event callback
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[addCrossProbeSelectEventListener(id, callFn)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** Add a cross-probe selection event listener
+
+</td></tr>
+<tr><td>
+
+[addImageEventListener(id, callFn)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** 新增插入图片事件监听
+
+</td></tr>
+<tr><td>
+
+[addMouseEventListener(id, eventType, callFn, onlyOnce)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** Add a mouse event listener
+
+</td></tr>
+<tr><td>
+
+[addNetEventListener(id, eventType, callFn, onlyOnce)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** Add a net event listener
+
+</td></tr>
+<tr><td>
+
+[addPrimitiveEventListener(id, eventType, callFn, onlyOnce)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** Add a primitive event listener
+
+</td></tr>
+<tr><td>
+
+[addRayTracerEngine3DViewCameraChangeEventListener(id, callFn, onlyOnce)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** Add a ray tracer engine 3D preview camera change (dragging the 3D model) event listener
+
+</td></tr>
+<tr><td>
+
+[addRayTracerEngine3DViewClickMaterialEventListener(id, callFn, onlyOnce)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** Add a ray tracer engine 3D preview material click event listener
+
+</td></tr>
+<tr><td>
+
+[addRealTimeDrcResultEventListener(id, eventType, callFn)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+**_(BETA)_** Add a real-time DRC result event listener
+
+</td></tr>
+<tr><td>
+
+[isEventListenerAlreadyExist(id)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+Query whether the event listener exists
+
+</td></tr>
+<tr><td>
+
+[removeEventListener(id)](./PCB_Event.md)
+
+</td><td>
+
+</td><td>
+
+Remove Event listener
+
+</td></tr>
+</tbody></table>
+
+---
+
+## 方法详情
+
+### addcrossprobeselecteventlistener
+
+# PCB\_Event.addCrossProbeSelectEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Add a cross-probe selection event listener
+
+## Signature
+
+```typescript
+function addCrossProbeSelectEventListener(
+	id: string,
+	callFn: (props: any) => void | Promise<void>,
+): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID, used to prevent duplicate event registration
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(props: any) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+The callback function triggered when the event fires
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+void
+
+## Remarks
+
+Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_cross_probe';
+
+// 1. 注册交叉选择事件监听（回调在用户执行交叉选中时触发，本例不依赖实际触发）
+eda.pcb_Event.addCrossProbeSelectEventListener(listenerId, (props) => {
+	console.log('crossProbeSelect:', JSON.stringify(props));
+});
+
+// 2. 回读确认注册成功（同 id 重复注册会被防重机制忽略）
+const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('registered:', registered);
+
+// 3. 清理监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+```
+
+### addimageeventlistener
+
+# PCB\_Event.addImageEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+> Warning: This API is now obsolete.
+>
+> 临时接口（插入图片 PCB 迁移打通流程用）：统一事件机制落地后替换，请尽快迁移，勿在新功能中继续依赖
+
+新增插入图片事件监听
+
+## Signature
+
+```typescript
+function addImageEventListener(
+	id: string,
+	callFn: (message: { file?: File; source: 'toolbar' | 'paste' }) => void | Promise<void>,
+): boolean;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+事件 ID，用于防止重复注册（内部自动加扩展 uuid 前缀）
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(message: { file?: File; source: 'toolbar' \| 'paste' }) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+事件触发时的回调，接收 pro-ui 触发的放置图片请求
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+boolean
+
+是否注册成功
+
+## Remarks
+
+ADD since EDA v5
+
+### addmouseeventlistener
+
+# PCB\_Event.addMouseEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Add a mouse event listener
+
+## Signature
+
+```typescript
+function addMouseEventListener(
+	id: string,
+	eventType: 'all' | EPCB_MouseEventType,
+	callFn: (
+		eventType: EPCB_MouseEventType,
+		props: [
+			{
+				primitiveId: string;
+				primitiveType: EPCB_PrimitiveType;
+				net?: string;
+				designator?: string;
+				parentComponentPrimitiveId?: string;
+				parentComponentDesignator?: string;
+			},
+		],
+	) => void | Promise<void>,
+	onlyOnce?: boolean,
+): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID, used to prevent duplicate event registration
+
+</td></tr>
+<tr><td>
+
+eventType
+
+</td><td>
+
+'all' \| [EPCB\_MouseEventType](../enums/EPCB_MouseEventType.md)
+
+</td><td>
+
+Event type
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(eventType: [EPCB\_MouseEventType](../enums/EPCB_MouseEventType.md)<!-- -->, props: \[{ primitiveId: string; primitiveType: [EPCB\_PrimitiveType](../enums/EPCB_PrimitiveType.md)<!-- -->; net?: string; designator?: string; parentComponentPrimitiveId?: string; parentComponentDesignator?: string }\]) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+The callback function triggered when the event fires
+
+</td></tr>
+<tr><td>
+
+onlyOnce
+
+</td><td>
+
+boolean
+
+</td><td>
+
+_(Optional)_ Whether to listen only once
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+void
+
+## Remarks
+
+Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_mouse_event';
+
+// 1. 注册鼠标事件监听，eventType 用 'all' 接收全部鼠标事件，onlyOnce 为 false 持续监听
+eda.pcb_Event.addMouseEventListener(
+	listenerId,
+	'all',
+	(eventType, props) => {
+		// 回调在用户画布操作时触发；props 是命中图元的信息数组
+		console.log('mouseEvent:', eventType, JSON.stringify(props));
+	},
+	false
+);
+
+// 2. 回读确认注册成功
+const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('registered:', registered);
+
+// 3. 清理监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+```
+
+### addneteventlistener
+
+# PCB\_Event.addNetEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Add a net event listener
+
+## Signature
+
+```typescript
+function addNetEventListener(
+	id: string,
+	eventType: 'all' | EPCB_NetEventType,
+	callFn: (eventType: EPCB_NetEventType, props: [{ net: string }]) => void | Promise<void>,
+	onlyOnce?: boolean,
+): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID, used to prevent duplicate event registration
+
+</td></tr>
+<tr><td>
+
+eventType
+
+</td><td>
+
+'all' \| [EPCB\_NetEventType](../enums/EPCB_NetEventType.md)
+
+</td><td>
+
+Event type
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(eventType: [EPCB\_NetEventType](../enums/EPCB_NetEventType.md)<!-- -->, props: \[{ net: string }\]) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+The callback function triggered when the event fires
+
+</td></tr>
+<tr><td>
+
+onlyOnce
+
+</td><td>
+
+boolean
+
+</td><td>
+
+_(Optional)_ Whether to listen only once
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+void
+
+## Remarks
+
+Net select event only
+
+1. When the net option is selected in the filter panel and a net is selected on the canvas
+
+2. When a net is selected in Engineering Design -<!-- -->&gt; Nets
+
+the event will be triggered
+
+Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_net_event';
+
+// 1. 注册网络事件监听，eventType 用 'all' 接收全部网络事件
+eda.pcb_Event.addNetEventListener(
+	listenerId,
+	'all',
+	(eventType, props) => {
+		// 回调在网络选中变化时触发；props 是网络信息数组
+		console.log('netEvent:', eventType, JSON.stringify(props));
+	},
+	false
+);
+
+// 2. 回读确认注册成功
+const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('registered:', registered);
+
+// 3. 清理监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+```
+
+### addprimitiveeventlistener
+
+# PCB\_Event.addPrimitiveEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Add a primitive event listener
+
+## Signature
+
+```typescript
+function addPrimitiveEventListener(
+	id: string,
+	eventType: 'all' | EPCB_PrimitiveEventType,
+	callFn: (
+		eventType: EPCB_PrimitiveEventType,
+		props: [
+			{
+				primitiveId: string;
+				primitiveType: EPCB_PrimitiveType;
+				net?: string;
+				designator?: string;
+				parentComponentPrimitiveId?: string;
+				parentComponentDesignator?: string;
+			},
+		],
+	) => void | Promise<void>,
+	onlyOnce?: boolean,
+): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID, used to prevent duplicate event registration
+
+</td></tr>
+<tr><td>
+
+eventType
+
+</td><td>
+
+'all' \| [EPCB\_PrimitiveEventType](../enums/EPCB_PrimitiveEventType.md)
+
+</td><td>
+
+Event type
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(eventType: [EPCB\_PrimitiveEventType](../enums/EPCB_PrimitiveEventType.md)<!-- -->, props: \[{ primitiveId: string; primitiveType: [EPCB\_PrimitiveType](../enums/EPCB_PrimitiveType.md)<!-- -->; net?: string; designator?: string; parentComponentPrimitiveId?: string; parentComponentDesignator?: string }\]) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+The callback function triggered when the event fires
+
+</td></tr>
+<tr><td>
+
+onlyOnce
+
+</td><td>
+
+boolean
+
+</td><td>
+
+_(Optional)_ Whether to listen only once
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+void
+
+## Remarks
+
+Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_primitive_event';
+const events = [];
+
+// 1. 注册图元事件监听，eventType 用 'all' 接收全部图元事件
+eda.pcb_Event.addPrimitiveEventListener(
+	listenerId,
+	'all',
+	(eventType, props) => {
+		events.push({ eventType, primitiveType: props?.[0]?.primitiveType });
+	},
+	false
+);
+
+// 2. 创建一个测试焊盘，触发图元 add 事件
+const pad = await eda.pcb_PrimitivePad.create(1, '1', 5000, 3000, 0, ['ELLIPSE', 60, 60], '', null, 0, 0, 0, false, 0);
+await new Promise(r => setTimeout(r, 500));
+
+// 3. 删除测试焊盘，再触发一次图元删除事件（同时清理测试图元）
+await eda.pcb_PrimitivePad.delete([pad.getState_PrimitiveId()]);
+await new Promise(r => setTimeout(r, 500));
+
+// 4. 观察两次操作分别触发的事件
+console.log('events:', JSON.stringify(events));
+
+// 5. 清理监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+```
+
+### addraytracerengine3dviewcamerachangeeventlistener
+
+# PCB\_Event.addRayTracerEngine3DViewCameraChangeEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Add a ray tracer engine 3D preview camera change (dragging the 3D model) event listener
+
+## Signature
+
+```typescript
+function addRayTracerEngine3DViewCameraChangeEventListener(
+	id: string,
+	callFn: (props: {
+		position: { x: number; y: number; z: number };
+		rotation: { x: number; y: number; z: number };
+		focalLength: number;
+	}) => void | Promise<void>,
+	onlyOnce?: boolean,
+): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID, used to prevent duplicate event registration
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(props: { position: { x: number; y: number; z: number }; rotation: { x: number; y: number; z: number }; focalLength: number }) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+The callback function triggered when the event fires
+
+</td></tr>
+<tr><td>
+
+onlyOnce
+
+</td><td>
+
+boolean
+
+</td><td>
+
+_(Optional)_ Whether to listen only once
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+void
+
+## Remarks
+
+Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error` ADD since EDA v4
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_3d_camera';
+
+// 1. 注册相机变动监听（回调在 3D 预览拖动时触发，本例不依赖实际触发）
+eda.pcb_Event.addRayTracerEngine3DViewCameraChangeEventListener(
+	listenerId,
+	(props) => {
+		console.log('cameraChange:', JSON.stringify(props));
+	}
+);
+
+// 2. 回读确认注册成功
+const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('registered:', registered);
+
+// 3. 清理监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+```
+
+### addraytracerengine3dviewclickmaterialeventlistener
+
+# PCB\_Event.addRayTracerEngine3DViewClickMaterialEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Add a ray tracer engine 3D preview material click event listener
+
+## Signature
+
+```typescript
+function addRayTracerEngine3DViewClickMaterialEventListener(
+	id: string,
+	callFn: (props: { materialId: number; material: any }) => void | Promise<void>,
+	onlyOnce?: boolean,
+): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID, used to prevent duplicate event registration
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(props: { materialId: number; material: any }) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+The callback function triggered when the event fires
+
+</td></tr>
+<tr><td>
+
+onlyOnce
+
+</td><td>
+
+boolean
+
+</td><td>
+
+_(Optional)_ Whether to listen only once
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+void
+
+## Remarks
+
+Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error` ADD since EDA v4
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_3d_material';
+
+// 1. 注册点击材质监听（回调在 3D 预览点击材质时触发，本例不依赖实际触发）
+eda.pcb_Event.addRayTracerEngine3DViewClickMaterialEventListener(
+	listenerId,
+	(props) => {
+		console.log('clickMaterial:', JSON.stringify(props));
+	}
+);
+
+// 2. 回读确认注册成功
+const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('registered:', registered);
+
+// 3. 清理监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+```
+
+### addrealtimedrcresulteventlistener
+
+# PCB\_Event.addRealTimeDrcResultEventListener() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Add a real-time DRC result event listener
+
+## Signature
+
+```typescript
+function addRealTimeDrcResultEventListener(
+	id: string,
+	eventType: 'all',
+	callFn: (eventType: undefined, props: [{ drcResult: any }]) => void | Promise<void>,
+): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID, used to prevent duplicate event registration
+
+</td></tr>
+<tr><td>
+
+eventType
+
+</td><td>
+
+'all'
+
+</td><td>
+
+Event type
+
+</td></tr>
+<tr><td>
+
+callFn
+
+</td><td>
+
+(eventType: undefined, props: \[{ drcResult: any }\]) =&gt; void \| Promise&lt;void&gt;
+
+</td><td>
+
+The callback function triggered when the event fires
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+void
+
+## Remarks
+
+Note: This API is only valid for extensions. Calling it in a standalone script environment will always `throw Error`
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_drc_result';
+
+// 1. 注册实时 DRC 结果监听，eventType 固定为 'all'
+eda.pcb_Event.addRealTimeDrcResultEventListener(
+	listenerId,
+	'all',
+	(eventType, props) => {
+		// 回调在实时 DRC 检出违规时触发；props 是 DRC 结果数组
+		console.log('drcResult:', JSON.stringify(props));
+	}
+);
+
+// 2. 回读确认注册成功
+const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('registered:', registered);
+
+// 3. 清理监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+```
+
+### iseventlisteneralreadyexist
+
+# PCB\_Event.isEventListenerAlreadyExist() method
+
+Query whether the event listener exists
+
+## Signature
+
+```typescript
+function isEventListenerAlreadyExist(id: string): boolean;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+boolean
+
+Whether the event listener exists
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_event_exist';
+
+// 1. 注册前查询：应为 false
+const before = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('before:', before);
+
+// 2. 注册一个鼠标事件监听使 id 生效
+eda.pcb_Event.addMouseEventListener(listenerId, 'all', () => {}, false);
+
+// 3. 注册后查询：应为 true
+const after = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('after:', after);
+
+// 4. 移除后查询：应回到 false
+eda.pcb_Event.removeEventListener(listenerId);
+const afterRemove = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('afterRemove:', afterRemove);
+```
+
+### removeeventlistener
+
+# PCB\_Event.removeEventListener() method
+
+Remove Event listener
+
+## Signature
+
+```typescript
+function removeEventListener(id: string): boolean;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+</td><td>
+
+string
+
+</td><td>
+
+Event ID
+
+</td></tr>
+</tbody></table>
+
+## Returns
+
+boolean
+
+Whether Remove Specify event listener
+
+## Example
+
+```javascript
+const listenerId = '嘉立创示例_event_remove';
+
+// 1. 先注册一个鼠标事件监听作为移除目标
+eda.pcb_Event.addMouseEventListener(listenerId, 'all', () => {}, false);
+const registered = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('registered:', registered);
+
+// 2. 移除该监听
+const removed = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removed:', removed);
+
+// 3. 回读确认已不存在
+const existAfter = eda.pcb_Event.isEventListenerAlreadyExist(listenerId);
+console.log('existAfter:', existAfter);
+
+// 4. 重复移除同一 id：返回 false（本就未注册）
+const removedAgain = eda.pcb_Event.removeEventListener(listenerId);
+console.log('removedAgain:', removedAgain);
+```