This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
api:event:zh [2023/10/12 17:22] hfsr [Event(事件) API] |
api:event:zh [2023/10/12 17:53] hfsr [函数] |
||
|---|---|---|---|
| Line 7: | Line 7: | ||
| event API主要有两种用法: | event API主要有两种用法: | ||
| - | - 让程序在后台运行时能够对事件作出响应(驱动模式)。 | + | - 让程序在后台运行时对事件作出响应(驱动模式)。 |
| - 让程序在作为前台程序执行时处理事件(优先模式)。 | - 让程序在作为前台程序执行时处理事件(优先模式)。 | ||
| Line 13: | Line 13: | ||
| 而在优先模式下，你无需在程序中注册事件，可以直接使用`events.pull()`函数进行处理。 | 而在优先模式下，你无需在程序中注册事件，可以直接使用`events.pull()`函数进行处理。 | ||
| - | //注意://虽然从技术层面上讲可以同时使用两种工作模式，但不推荐这样做。为了保证所有进行了注册的函数都能接收到事件，事件的一次触发只有在所有函数都被调用后才算结束。因此如果你将处理函数(handler)进行了注册，又执行了拉取(pull)操作，那么同一个事件会被响应两次。 | + | //注意://虽然从技术层面上讲可以同时使用两种工作模式，但不推荐这样做。为了保证所有已注册的函数都能接收到事件，事件的一次触发只有在所有函数都被调用后才算结束。因此如果你将处理函数(handler)进行了注册，又执行了拉取(pull)操作，那么同一个事件会被响应两次。 |
| ===== 函数 ===== | ===== 函数 ===== | ||
| Line 22: | Line 22: | ||
| **返回值：**如果注册成功，数据类型为`number`，代表了事件id，可传递给`event.cancel`函数取消事件。如果函数已经注册过此类事件，将会返回`false`。 | **返回值：**如果注册成功，数据类型为`number`，代表了事件id，可传递给`event.cancel`函数取消事件。如果函数已经注册过此类事件，将会返回`false`。 | ||
| - `event.ignore(event: string, callback: function): boolean` | - `event.ignore(event: string, callback: function): boolean` | ||
| - | 注销一个先前注册的事件侦听器。 | + | 注销一个事件侦听器。 |
| **event(事件)** - 需要注销的信号名称。\\ | **event(事件)** - 需要注销的信号名称。\\ | ||
| **callback(回调函数)** - 之前注册到此事件的回调函数。\\ | **callback(回调函数)** - 之前注册到此事件的回调函数。\\ | ||
| **返回值：**如果事件成功注销则返回`true`。如果指定的函数并未注册到此类事件则返回`false`。\\ | **返回值：**如果事件成功注销则返回`true`。如果指定的函数并未注册到此类事件则返回`false`。\\ | ||
| - | //注意：//事件侦听器在注销自身时可能会返回`false`，此时相当于调用 `event.ignore`，并向其传参侦听器和侦听器所注册的函数。 | + | //注意：//事件侦听器返回`false`后将会被自动注销。相当于调用 `event.ignore`，并向其传递对应参数。 |
| - `event.timer(interval: number, callback: function[, times: number]): number` | - `event.timer(interval: number, callback: function[, times: number]): number` | ||
| 开启一个新的定时器，在经过`interval`指定的时长后将会被触发。 | 开启一个新的定时器，在经过`interval`指定的时长后将会被触发。 | ||
| **interval(触发间隔)** - 调用回调函数的间隔时长，单位为秒。可以为像0.05这样的小数。\\ | **interval(触发间隔)** - 调用回调函数的间隔时长，单位为秒。可以为像0.05这样的小数。\\ | ||
| **callback(回调函数)** - 要调用的函数。\\ | **callback(回调函数)** - 要调用的函数。\\ | ||
| - | **times(次数)** - 应调用函数的次数。如果省略则函数只会被调用一次。指定为`math.huge`可以无限次重复调用。\\ | + | **times(次数)** - 应调用的次数。如果省略则函数只会被调用一次。指定为`math.huge`可以无限次重复调用。\\ |
| **返回值：**定时器id，可以随时用于取消定时器。\\ | **返回值：**定时器id，可以随时用于取消定时器。\\ | ||
| - | //Note//: the timer resolution can vary. If the computer is idle and enters sleep mode, it will only be woken in a game tick, so the time the callback is called may be up to 0.05 seconds off. | + | //注意：//定时器的精度可能会发生变化。如果电脑闲置并进入了休眠模式，则电脑只会每游戏刻唤醒一次。因此触发回调函数的时间点可能会偏差至多0.05秒。 |
| - `event.cancel(timerId: number): boolean` | - `event.cancel(timerId: number): boolean` | ||
| 取消某个先前由`event.timer`函数创建的定时器。 | 取消某个先前由`event.timer`函数创建的定时器。 | ||
| Line 44: | Line 44: | ||
| **...** - 任意数量的参数，顺序需要与目标[[component:signals|信号]]所定义的相同。它们会被作为过滤器来筛选信号返回的额外参数，判断方式为是否完全相等。值可以为`nil`，这样将不会过滤此参数。\\ | **...** - 任意数量的参数，顺序需要与目标[[component:signals|信号]]所定义的相同。它们会被作为过滤器来筛选信号返回的额外参数，判断方式为是否完全相等。值可以为`nil`，这样将不会过滤此参数。\\ | ||
| 样例： | 样例： | ||
| - | `touch`信号(在玩家点击二级或三级显示器时触发)带有如下参数：` screenX: number`(点击处的X坐标)、`screenY: number`(点击处的Y坐标)、`playerName: string`(进行点击的玩家姓名)。 | + | `touch`信号(在玩家点击二级或三级显示器时触发)带有如下参数：` screenX: number, screenY: number, playerName: string`(点击处的X、Y坐标，进行点击的玩家ID) |
| 若要仅拉取玩家"Steve"的点击，你需要使用： | 若要仅拉取玩家"Steve"的点击，你需要使用： | ||
| `local _, x, y = event.pull("touch", nil, nil, "Steve")` | `local _, x, y = event.pull("touch", nil, nil, "Steve")` | ||