# 创建自定义事件 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/custom-event) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 声网互动白板 SDK 提供自定义事件接口,用于在房间内实时发送和接收自定义消息,帮助实现消息广播、实时聊天、点赞、送礼等功能。 本文介绍如何实现发送、接收和停止接收自定义事件。 ## 技术原理 [#技术原理] 互动白板 SDK 提供以下自定义事件接口: - `dispatchMagixEvent`:发送自定义事件。 - `addMagixEventListener`:注册自定义事件监听。 - `removeMagixEventListener`:移除自定义事件监听。 实现发送和接收自定义事件的步骤如下: 1. 定义事件名称、内容和回调函数。 2. 调用 `addMagixEventListener` 监听事件。 3. 调用 `dispatchMagixEvent` 发送事件。房间内所有监听该事件的用户都会收到事件通知。 4. 当不再需要接收事件通知时,可以调用 `removeMagixEventListener` 注销对该事件的监听。 ## 前提条件 [#前提条件] 开始前,请确保你已在项目中集成声网互动白板 SDK 并加入房间。详见[加入实时房间](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb)。 ## 实现方法 [#实现方法] 本节展示如何在[加入实时房间](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb)示例代码的基础上使用自定义事件接口发送和接收简单的文字消息。 ### 监听和发送自定义事件 [#监听和发送自定义事件] 在 `index.js` 文件中添加如下代码: ```javascript var whiteWebSdk = new WhiteWebSdk({ appIdentifier: "RMxxxAQ", }); var joinRoomParams = { uuid: "a7xxx69", roomToken: "NETLESSROOM_YWxxxjk", }; // 定义事件的名称和内容 var eventObject = { event: "Greetings", payload: "", }; // 定义事件回调函数 function onReceiveGreetings(eventObject) { // 当收到 Greetings 事件时,在控制台输出事件的内容 console.log(eventObject.payload); } whiteWebSdk.joinRoom(joinRoomParams).then(function(room) { room.bindHtmlElement(document.getElementById("whiteboard")); // 监听 Greetings 事件 room.addMagixEventListener("Greetings", onReceiveGreetings); // 发送 Greetings 事件 room.dispatchMagixEvent("Greetings", "Hello, how do you do"); }).catch(function(err) { console.error(err); }); ``` 保存修改后,刷新 `index.html` 页面,打开浏览器的控制台,可以看到如下信息: ```text Hello, how do you do ``` ### 注销自定义事件监听 [#注销自定义事件监听] 如果你想停止接收某一自定义事件的回调通知,可以调用 `removeMagixEventListener` 注销对该自定义事件的监听。 例如,要取消对 `Greetings` 事件的监听,在 `index.js` 文件中添加如下行: ```javascript whiteWebSdk.joinRoom(joinRoomParams).then(function(room) { room.bindHtmlElement(document.getElementById("whiteboard")); // 注销对 Greetings 事件的监听 room.removeMagixEventListener("Greetings", onReceiveGreetings); }).catch(function(err) { console.error(err); }); ``` ## 参考信息 [#参考信息] ### 开发注意事项 [#开发注意事项] 在使用自定义事件接口时,你需要注意以下几点: - 在高频率、事件 `payload` 较大的情况下,无法保证 `dispatchMagixEvent` 的稳定性,且房间可能出现延时或卡顿,影响用户体验。声网建议每个自定义事件的 `payload` 不超过 1 KB。 - 通过 `addMagixEventListener` 监听自定义事件时,只能接收到监听之后发送的自定义事件,不能接收到监听之前发送的自定义事件。 ### API 参考 [#api-参考] - [`dispatchMagixEvent`](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/interfaces/room#dispatchmagixevent) - [`addMagixEventListener`](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/interfaces/displayer#addmagixeventlistener) - [`removeMagixEventListener`](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/interfaces/displayer#removemagixeventlistener)