事件系统

描述

事件系统对任何研究都是必不可少的。它是您设置要记录的值、使实验进展和创建任务的方式。用户可以创建一个事件系统来执行任务中的所有功能、逻辑和交互。事件通常充当对象和变量之间的中介。

有关触发器的完整列表，请参见 triggers
有关操作的完整列表，请参见 actions
有关设置事件下值的 Value-Select 菜单的更多信息

事件系统由 triggers 和 actions. 组成。您可以在这里设置规则，比如“当发生这种情况”（触发器），“然后执行此操作”（动作）。例如：如果参与者单击特定图像（触发器），则显示另一个不同的随机图像（动作）。

有关事件在 Labvanced 中的工作原理的介绍，请参考此快速视频：

创建事件 - 概述

事件在任务编辑器的右上角的“事件”选项卡下进行管理。可以通过单击 + Frame Event 创建新的事件，以便在该框架上发生的事件，或者通过单击 + Trial Event 将事件应用于所有框架。所有现有事件在右侧面板的列表视图中显示。事件在框架级别上定义，可以针对每个框架单独/特定定义或在试验的每个框架中重复/相同。

在 Labvanced 中添加事件

无论哪种方式，事件始终为指定框架内的所有试验组定义。然而，自定义逻辑允许用户仅在特定试验、条件或其他情况下执行事件。

选择触发器

当您创建一个新事件时，触发器选择会以 瓷砖网格 的形式打开。触发器类型按类别（用户输入、生理信号、试验和框架、变量、媒体对象、API 和全局）进行组织。顶部的搜索框允许您按名称过滤触发器类型。单击任何瓷砖将其设置为事件的触发器。

选择触发器后，事件将显示包含当前触发器名称和图标的紧凑条。要切换到其他触发器，请单击 Change trigger 按钮（铅笔图标）以重新打开瓷砖网格。

下面的视频概述了 Labvanced 中的可用触发器和操作：

事件的执行顺序可以进行调整。默认情况下，具有相同触发器的事件会排在列表的更上面，并将首先执行。事件也可以被复制和删除。选择现有事件时，右下角（事件属性）面板中会显示具体内容。为了更好地概览，现有事件也可以重新打开（名称字段旁边的图标）。

触发器

触发器定义了事件何时执行。这可以是对特定对象的鼠标单击、某个键盘输入、变量的变化、视频文件的开始或许多其他事情。以下列表解释了所有触发器及其设置/参数：

触发器类别	触发器选项	描述
`User Input Triggers`	鼠标触发器键盘触发器按钮单击输入时按回车滚动触发器手柄/操纵杆触发器	用户输入触发器指任何可以通过用户/参与者手动激活的触发器，例如移动鼠标、单击键盘元素、滚动等。
`Physiological Signal Triggers`	眼动追踪注视眼动追踪固定头部追踪	生理信号触发器在有特定生理输入时发生，例如注视特定元素或头部运动变化。
`Trial and Frame Triggers`	任务初始化框架初始化框架开始框架结束	这些触发器与实验试验和框架有关，例如框架开始或结束时。
`Variable Value Changed Trigger`	变量（值变化）	当特定变量值发生变化时，事件就会触发。
`Media Object Trigger`	媒体对象触发器	此触发器与媒体对象有关，例如视频/音频文件的暂停、录制完成等。
`API Triggers`	Websocket 触发器 Open AI 触发器收到 PostMessage	这些触发器在从 API 接收到数据时发生。
`Global Triggers`	暂停/恢复实验参与者离开多人研究	全局触发器指任何对实验的重大更改，例如实验被暂停或多人研究中的参与者离开。

用户输入触发器

用户输入触发器指任何可以由用户/参与者手动激活的触发器。

Labvanced 中的用户输入触发器菜单

下表提供了在 Labvanced 中所有可用用户输入触发器的初步概述。每个触发器将在后面的部分中详细描述。

用户输入触发器选项	概述
`Mouse Trigger`	任何鼠标移动可以作为触发器来启动事件，例如：滚动、单击、悬停等。您还可以将特定元素或目标与触发器关联。例如，只有在单击特定图像时，鼠标单击才会用作触发器。
`Keyboard Trigger`	任何键盘按键都可以作为触发器来启动事件。您可以指定特定的字母或数字作为触发器。
`Button-Clicks`	在 Labvanced 中创建的按钮对象可以用作触发器来启动事件。
`Enter on Input`	当参与者在实验中按下“回车”时，此触发器常用于提交他们在文本字段区域中的书面响应或输入。
`Scroll Trigger`	当参与者滚动时，此触发器会发生。您可以指定 x 或 y 滚动方向，以及滚动发生在何种元素上，以用作事件触发器。
`Gamepad/ Joystick Trigger`	此触发器允许您在实验设计中使用手柄和操纵杆控制器作为记录数据的输入设备。

鼠标触发器

“鼠标触发器”选项是一个非常流行的事件触发器，因为它可以根据任何鼠标交互（例如：上下移动鼠标、单击、悬停在特定对象上、离开特定对象或任何移动）来启动事件！

Labvanced中输入触发器菜单中的“鼠标触发器菜单”选项。

下面的示例显示了一个“鼠标触发器”，当在名为“Image_1”的“目标”对象上执行“左键”单击时，将发生触发：

Example of the mouse trigger option being used in Labvanced.

以下是您在使用鼠标触发器时可以选择的选项的完整概述：

菜单项目	菜单区域	鼠标触发器选项和规格
`Action` 下拉列表：		下拉列表中可以选择以下鼠标触发器选项：点击：由鼠标点击触发按下：由鼠标按下触发抬起：由鼠标抬起触发悬停：由鼠标悬停在对象上触发离开：由鼠标离开对象触发移动：由任何鼠标移动触发
`Button` 下拉列表：		左键：由左鼠标按钮触发右键：由右鼠标按钮触发
`Targets` 选项：	在上面的示例中，“Image_1”是将触发事件的按钮点击的目标。可以通过单击底部的 `‘+Add Target’` 选项添加多个目标。	指定目标时，可以选择以下选项：在帧背景上触发：鼠标触发器可以在不点击对象或元素的情况下激活。任何元素：鼠标触发器可以在点击帧上的任何元素时激活。添加目标：选择要单击以激活触发器的特定元素。

注意： 在事件系统中选择鼠标触发器后，您可以选择在各种操作中使用和引用特定触发器的鼠标值，通过值选择菜单。

键盘触发器

“键盘触发器”选项是另一种常用的事件触发方式。本质上，键盘上的任何输入都可以用作触发器。这包括：按下、按住或释放一个键。

The keyboard trigger option in Labvanced

在下面的示例中，触发器设置为在按下指定的目标数值（0、2或6）时发生键盘按压：

Example of the keyboard trigger being used.

以下是您在使用键盘触发器时可以选择的按键和选项的完整概述：

菜单项目	菜单区域	键盘触发器选项
`Action` 下拉列表：		可用的键盘动作选项有： PressKey：由按键按下触发（键处于按下状态）按下或保持键：在按下或保持键时触发 ReleaseKey：由按键释放触发注意：在再次作为触发器“发射”之前，需要释放一个键。
`Keys` 触发事件的哪个键		触发使用的键由单击 `+Add:` 选择选项来指定箭头：四个箭头键数字：从0到9的数字字母：英文字母中的所有字母特殊：特殊键（进入、空格、控制、Tab、Shift） F键： F1到F10 任何键：任何这些键都是可以接受的可以通过再次单击 `+Add:` 按钮添加多个键盘触发器
其他选项		启用小数字键按钮选项允许在实验中使用小数字键作为触发器。对于允许事件传播选项，如果多个事件具有相同的键盘触发器，则所有事件会触发，而不考虑此选项。只有第一个会被触发，事件执行将在第一个事件完成后停止。

注意： 在事件系统中选择键盘触发器后，您可以选择在各种操作中使用和引用特定触发器的键盘值，通过值选择菜单。

按钮点击触发器

如果您在编辑器中放置了按钮或导航对象，您可以利用它们作为事件的一部分，单击按钮作为动作的触发器。

The button click menu in Labvanced

单击此触发器会显示以下菜单，您可以在其中指定哪个特定按钮将作为触发器：

Options available for the button click trigger

以下是所示项目的更详细查看：

菜单项目	菜单区域	按钮点击触发器选项
目标： `+Set Target`		选择按钮元素作为目标
`Button:` 选项		指定帧上哪个特定按钮

注意： 在事件系统中选择按钮点击触发器后，您可以选择在各种操作中使用和引用特定触发器的按钮点击值，通过值选择菜单。

输入时按回车触发器

触发条件：当在特定元素上按下 Enter/Return 键时。

参数：

添加目标：向事件中添加输入元素。
注意： 在事件系统中选择输入时按回车触发器后，您可以选择在各种操作中使用和引用特定触发器的输入回车值，通过值选择菜单。

滚动触发器

触发条件：在特定元素上使用滚动条、触控板滚动或鼠标滚轮。

参数：

选择滚动是沿 Y 轴还是 X 轴（垂直滚动或水平滚动）。

目标：设置将应用滚动触发器的目标元素。

注意：对于长文本，在“对象属性”(/content/learn/zh/guide/task-editor/objects.html#object-properties)面板的“样式”部分，Overflow-X和/或Overflow-Y选项需要选择scroll作为选项。

注意： 在事件系统中选择滚动触发器后，您可以选择在各种操作中使用和引用特定触发器的滚动值，通过值选择菜单。

游戏手柄/游戏杆触发器

Gamepad/ Joystick Trigger 允许您在实验设计中将游戏手柄和游戏杆控制器用作输入设备进行数据记录。 注意： 请记得在Settings 标签下启用此选项。

了解更多。

生理信号触发器

这些触发器将只在已为任务启用眼动追踪和/或头部追踪的情况下适用。

眼动追踪凝视触发器

触发条件：

总体来说，当启用眼动追踪时，此触发器将适用。
仅在注视特定元素时触发

参数：

如果您选择仅在特定元素上触发，请将这些元素作为目标添加。
注意： 在事件系统中选择眼动追踪凝视触发器后，您可以选择在各种操作中使用和引用特定触发器的凝视值，通过值选择菜单。

眼动追踪固定触发器

该触发器仍处于测试阶段。

注意： 在事件系统中选择键盘触发器后，您可以选择在各种操作中使用和引用特定触发器的固定值，通过值选择菜单。

头部追踪触发器

触发条件：

头部方向或头部移动的变化。
注意： 在事件系统中选择头部追踪触发器后，您可以选择在各种操作中使用和引用特定触发器的头部追踪值，通过值选择菜单。 ```markdown

试验和帧触发器

任务初始化触发器

触发于：

任务的第一个试验的第一帧。每个任务只会执行一次，尽管在事件选项卡中会显示该帧的所有实例。

这个触发器与打乱和从中读取操作配对得很好。通过这些组合，您可以在任务开始时打乱数组条目或数据帧，并将被试分配到刺激集，而无需创建多个事件来读取刺激或数据。

参数：无

注意: 在事件系统中选择任务初始化触发器后，您可以选择在各个操作中利用和引用特定触发器的任务初始化值与value-select菜单一起使用。

帧初始化触发器

触发于：

帧的初始化，在它对参与者可见之前。

这个触发器与打乱、从中读取和绘制随机数操作配对得很好。通过这些组合，这些操作可以在帧出现之前完成，为其他操作的开始清晰开辟出通道。

注意: 不要将帧初始化触发器与记录变量或涉及系统变量（如试验编号或条件编号）的事件一起使用。这是因为帧初始化触发器发生在试验之间，因此无法准确计算即将显示的试验或条件的完整计数。

参数：无

注意: 在事件系统中选择帧初始化触发器后，您可以选择在各个操作中利用和引用特定触发器的帧初始化值与value-select菜单一起使用。

关于任务和帧初始化触发器的注意事项: 由于任务和帧初始化触发器在任务或帧开始之前发生，因此在此时创建的变量将在任务/帧实际开始时重置。使用此事件时将出现警告：

帧初始化警告

如果您不想重置变量值，请记得在变量属性窗口中取消选中“在试验开始时重置”框。

帧开始触发器

触发于：

帧的开始

参数：无

注意: 在事件系统中选择帧开始触发器后，您可以选择在各个操作中利用和引用特定触发器的帧开始值与value-select菜单一起使用。

帧结束触发器

触发于：

帧的结束（帧不再可见后）

参数：无

注意: 在事件系统中选择帧结束触发器后，您可以选择在各个操作中利用和引用特定触发器的帧结束值与value-select菜单一起使用。

变量值变化触发器

变量值变化

触发于：

变量的值从其起始值改变

参数：

变量：选择一个或多个变量，您希望“监听”其变化。这些变量的任何值变化都会立即触发对应的操作。
注意: 在事件系统中选择变量值变化触发器后，您可以选择在各个操作中利用和引用特定触发器的变量值变化值与value-select菜单一起使用。

媒体对象触发器

以前称为“控制音频/视频触发器”和“控制对象”触发器。

触发于：

视频或音频文件的开始、暂停或停止
文件上传完成、文件选择、录音对象的录音完成
相机快照对象的快照完成或上传完成

参数：

目标：选择一个存在于帧上的对象元素
执行时：选择触发器的子类型
- 音频或视频对象选项：
  - 播放开始：当元素开始播放时触发
  - 播放停止：当元素暂停时触发
  - 播放结束：当元素停止播放时触发
- 视频、音频或屏幕录制对象选项：
  - 录音完成：当音频录制停止时触发
  - 上传完成：当文件上传完成时触发
- 文件上传对象选项：
  - 文件选择：当选择文件时触发
  - 上传完成：当文件上传完成时触发
- 相机快照对象选项：
  - 快照完成：当相机成功拍摄快照时触发
  - 上传完成：当快照上传完成时触发
注意: 在事件系统中选择媒体对象触发器后，您可以选择在各个操作中利用和引用特定触发器的媒体对象值与value-select菜单一起使用。

API触发器

如果您需要将数据从外部服务器发送或传输到Labvanced，那么可以使用“API触发器”和“API操作”。可以用作触发器的包括：

Websocket触发器
OpenAI触发器
收到PostMessage

Labvanced中的API触发器菜单。

Websocket触发器

Websocket触发器用于当来自Websocket/API的消息被接收并处理作为操作的触发器时。

Websocket触发器菜单选项。

单击此选项后，将出现以下项目。

Websocket触发器对话框菜单。

接受/接收来源: 自动检测本地主机的IP地址。可以在Settings选项卡下手动更改Special Features。
触发器/消息: 输入将作为触发器的消息。输入'any'以接受多个消息作为触发器。

有关API触发器/操作如何使用的示例，请单击对话框中的“检查”选项查看此演示https://www.labvanced.com/page/library/51053。

有关API访问的更多信息，请访问此页面。

注意: 在事件系统中选择WebSocket触发器后，您可以选择在各个操作中利用和引用特定触发器的WebSocket值与value-select菜单一起使用。

OpenAI触发器

“OpenAI触发器”可用于根据来自OpenAI的信息启动操作。

Labvanced中的OpenAI触发器菜单。

选择此选项后将显示以下参数：

OpenAI触发器菜单选项。

注意: 还可参考这个演练，在其中我们逐步构建一个研究，将ChatGPT集成到研究中并利用此触发器。

在下面的示例中，被分配的数据框被称为‘df’，来自‘OpenAI触发器’的结果将附加到此数据框。此数据框需要有两个列。第一列表示‘角色’，第二列表示‘聊天消息’。操作的值将自动附加到此处链接的数据框中。

Labvanced中OpenAI触发器的示例。

如果您还使用‘发送到OpenAI’操作，则需要在此处表示与之相同的数据框。

注意: 在事件系统中选择OpenAI触发器后，您可以选择在各个操作中利用和引用特定触发器的OpenAI值与value-select菜单一起使用。

收到PostMessage触发器

PostMessage Received触发器在运行的实验接收到来自外部源的消息时触发，通过浏览器的postMessage API。它对于将实验连接到父页面、自定义应用程序或发送数据到研究的嵌入式外部网站非常有用。

了解更多.

注意: 在事件系统中选择收到PostMessage触发器后，您可以选择在各个操作中利用和引用特定触发器的PostMessage Received值与value-select菜单一起使用。


### 全局触发器

全局触发器是在实验中发生重大变化时发生的事件，例如暂停实验或参与者离开多用户研究等“全局”事件！以下选项被列为全局触发器：
* 暂停 / 恢复实验
* 参与者离开多用户研究

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/global_menu.webp" alt="Labvanced中的全局触发器菜单。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

#### 暂停/恢复实验

“暂停 / 恢复实验”触发器是一个选项，允许您根据实验的暂停或恢复执行事件。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/pause_trigger.webp" alt="在实验中使用暂停作为触发器的选项。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

选择此触发器后，将出现以下视图，您可以进一步指定触发器的性质，无论是应该在实验暂停时还是继续/恢复时执行：

 <p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/global_dialog.webp" alt="此全局触发器的对话框菜单" width="50%">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/global_options.webp" alt="全局触发器菜单中的可用选项" width="50%">
</p>

* **实验暂停：** 参与者暂停（退出全屏）研究。
* **实验继续：** 参与者恢复研究。此触发器在眼动追踪研究中效果很好。它可以用于将参与者返回到上一个试验或框架，如果他们离开了虚拟下巴托架。

* **注意：** 在事件系统中选择暂停/恢复实验触发器后，您可以选择利用和引用[特定触发器值](#trigger-global-experiment-event-values)在各种操作中使用[值选择菜单。](#the-value-select-menu) 

#### 参与者离开多用户研究
如果参与者离开多用户研究，这也可以作为事件的触发器。如果参与者离开多用户研究，这在全局上会影响实验，因为它会阻止其他参与者继续进行研究。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/left_mus.webp" alt="Labvanced中的参与者离开多用户研究选项作为触发器" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

通过选择此触发器，您可以指定如果参与者离开多用户研究将会发生何种操作。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/left_mus_dialog.webp" alt="参与者离开多用户研究触发器对话框。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

* **注意：** 在事件系统中选择参与者离开多用户研究触发器后，您可以选择利用和引用[特定触发器值](#trigger-user-leaves-experiment-values)在各种操作中使用[值选择菜单。](#the-value-select-menu) 


## 操作
操作定义了在执行事件时应该发生的事情。它们可以用于更改变量和对象属性、记录数据、从/向数组读取和写入数据，或跳转到下一个试验或任务。通常每个事件有若干操作。通过“ControlActions”，可以使用逻辑运算（If-Else语句）、循环、回调函数，以及将操作嵌套在彼此之内（例如在if语句中的while循环）。因此，事件系统可以被视为一个图形化编程环境。在此视图中，触发器充当函数调用，而操作描述功能逻辑。这种方法保证了几乎任何实验逻辑都可以实现，而无需使用某些编程/语法结构。

下表提供了Labvanced中可用操作的简介：

| 操作类别 <img width=200/>  | 操作选项 <img width=500/>| 描述 <img width=400/> | 
| :----: | -- | ----- | 
| [`Object Actions`](#object-actions)| <ul><li> [设置对象属性](#set-object-property-action) </li> <li> [控制媒体对象](#control-media-object-action) </li> <li> [复制对象](#copy-object-action) </li> <li> [对于每个对象](#foreach-object-action) </li> </ul> | 对象操作指对任务中存在的对象进行的任何操作。 |
| [`Variable Actions`](#variable-actions) | <ul><li> [设置 / 记录变量](#set-record-variable-action) </li> <li> [复制到剪贴板](#copy-to-clipboard-action) </li> <li>[随机数绘制](#draw-random-number-action) </li> <li> [获取URL参数](#get-url-parameter-action) </li> <li> [从/写入设备](#read-from-write-to-device-action) </li> <li> [从/写入共享变量](#read-from-write-to-shared-variable-action) </li> <li> [数学与统计](#math-statistics-action) </li> <li>[即时记录变量](#record-variables-instantly-action) </li> <li>[移动平均滤波器](#moving-average-filter-action) </li> <li> [分配变量](#distribute-variable-action) </li> </ul> |  任何读取或记录变量值的操作。 |
| [`Array Actions`](#array-actions) | <ul><li> [从数组中选择（读取）](#select-read-from-array-action) </li> <li> [添加/删除数组条目](#add-remove-array-entries-action) </li> <li> [更改数组条目（替换）](#change-replace-array-entry-action) </li> <li> [打乱数组条目](#shuffle-array-entries-action)  </li> </ul> | 数组操作涉及选择、添加、删除、改变和打乱数组及其条目。 | 
| [`Data Frame Operations`](#data-frame-operations) | <ul><li> [从/写入数据框](#read-from-write-to-data-frame-action) </li> <li> [打乱数据框条目](#shuffle-data-frame-entries-action)  </li> </ul> | 如果您在实验中处理.csv文件（数据框），这些操作是相关的。 |
| [`Jump Actions`](#jump-actions) | <ul><li> [跳转到](#jump-to-action) </li> <li> [接受/结束会话](#accept-end-session-action) </li> <li> [拒绝/结束会话](#reject-end-session-action) </li> <li>[重定向到URL](#redirect-to-url-action)</li></ul> | 允许您通过跳转到特定部分来导航实验，以及接受和拒绝参与者部分。 | 
| [`Control Actions`](#control-actions) | <ul><li>  [要求操作（如果…那么）](#requirement-actions-if-then-else-if-action) </li><li> [重复操作（while循环）](#repeated-actions-while-loop-action) </li><li> [延迟操作（时间回调）](#delayed-actions-time-callback-action) </li><li> [操作组](#action-group) </li></ul> | 控制操作用于执行特定事件序列，如if/then逻辑、循环（如播放重复声音或闪烁图像）以及设置延迟以决定何时发生某个操作。 | 
| [`API Actions`](#api-actions) | <ul><li> [发送PostMessage](#send-postmessage-action) </li><li> [发送到Websocket](#send-to-websocket-action) </li><li> [发送到OpenAI](#send-to-openai-action) </li></ul> | 指代特定于API的操作，用于向API发送数据。 |
| [`Code Actions`](#code-actions) | <ul><li> [运行JavaScript](#run-javascript-action) </li> <li> [设置全局CSS](#set-global-css-action) </li></ul> |  代码操作允许您使用JavaScript或CSS。 
| [`Paste Action`](#paste-action) | 粘贴操作  | 允许您粘贴之前复制的操作。 |

### 对象操作 
对象操作指对任务中存在的对象进行的任何操作。有几种对象操作选项：
* 设置对象属性
* 控制媒体对象
* 复制对象
* 对于每个对象 

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/object_actions_menu.webp" alt="Labvanced中的对象操作选项。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

#### 设置对象属性操作
使用“设置对象属性”操作，您可以通过指定相关对象、要更改的属性和新值来改变对象的外观。

[了解更多。](/content/learn/zh/guide/events/set-object-property-action.html) 


#### 控制媒体对象操作

以前是单独的“控制音频/视频”和“控制对象”操作。

效果：更改视频/音频元素的播放或更改上传/录制元素的状态。

参数：
* 目标：选择一个媒体对象
* 效果：选择一个子操作
    * 音频或视频对象选项：
        * 开始播放：开始播放视频/音频文件
        * 停止播放：停止视频/音频文件
        * 暂停播放：暂停视频/音频文件
        * 跳转至时间：允许您指定在音频/视频文件中跳转的时间（以毫秒为单位）
        * 静音：关闭对象的声音
        * 取消静音：恢复对象的声音
    * 音频、视频或屏幕录制对象选项：
        * 开始录制：开始新的（音频）录制
        * 停止录制：停止（音频）录制
        * 开始上传：开始文件的上传
        * 清除录制：删除（音频）录制数据。
        * 开始播放：开始播放录制的文件
        * 停止播放：停止播放录制的文件
        * 暂停录制：暂停对象的录制
        * 恢复录制：恢复对象的录制
    * 文件上传对象选项：
        * 开始上传：开始所选文件的上传过程
        * 清除文件：删除所选文件
        * 选择文件：允许参与者选择所需文件
    * 相机快照对象选项：
        * 开始相机：开启参与者的相机
        * 停止相机：关闭参与者的相机
        * 开始上传：开始将快照上传到实验
        * 拍摄快照：使用参与者的相机拍照
``````markdown
#### 复制对象操作
效果：复制一个对象，替代对多个独立对象和重复事件的需求。

参数： 
* 源：选择要复制的帧上的对象。
* 复制数量：输入要制作的源对象的副本数。
* 设置新元素名称：从几个参数中选择，以确定副本的名称。 
* 以递增后缀分配名称：在新元素名称的末尾添加数字标签以区分副本。 
* 操作顺序：允许您从常见的操作列表中选择将对副本执行的操作。选择“CurrentObject”作为目标以对所有副本应用该操作。

#### 对每个对象操作
效果：对多个相同类型的对象应用一个操作。 

参数： 
* 过滤器：选择要定位的元素类型。
* 允许附加名称过滤器：输入要定位的对象名称。如果帧上有几个对象的名称相同，这效果很好。
* 操作顺序：允许您从常见的操作列表中选择对选定元素将发生的操作。选择“CurrentObject”作为目标以对所有满足上述指定标准的元素应用该操作。 

### 变量操作

变量操作用于设置或创建变量值，记录和定义值，包括跨会话的值。 

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/variable_actions_full.webp" alt="变量操作在事件系统中的位置" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

下表提供了 Labvanced 中所有可用变量操作选项的介绍性概述。每个选项在后续部分中将更详细地描述。

| 变量操作选项 | 描述 |
|:-----:|-----|
| [`Set / Record Variable`](#set-record-variable-action) | 写入或设置变量值 |
| [`Copy to Clipboard`](#copy-to-clipboard-action) | 将变量值复制到计算机内部剪贴板。 |
| [`Draw Random Number`](#draw-random-number-action) | 抽取一个或多个随机数并将其保存在变量中 |
| [`Get URL Parameter`](#get-url-parameter-action) | 从参与者的唯一 URL 中保存一个值 |
| [`Read from / Write to Device`](#read-from-write-to-device-action) <img width=300/>  | 从本地设备的存储中读取或写入变量。此操作将数据保存到参与者的设备，而不是发送到 Labvanced 服务器。 |
| [`Read from / Write to Shared Variable`](#read-from-write-to-shared-variable-action) | 从跨研究会话共享的变量中读取或写入。该变量可以与所有参与者共享或私有化到每个个体。 |
| [`Math & Statistics`](#math-statistics-action)  | 对某个输入变量（数组）执行数学运算并将结果保存在一个输出变量中。 |
| [`Record Variables Instantly`](#record-variables-instantly-action)  | 创建所有变量值的快照并将其发送到 Labvanced 服务器。  |
| [`Moving Average Filter`](#moving-average-filter-action) | 计算某个输入的移动平均（数据的持续更新平均值）并将结果存储在新变量中。  |
| [`Distribute Variable`](#distribute-variable-action)  | 将一个值发送给其他参与者。该值存储在一个变量中。 |

#### 设置 / 记录变量操作

“设置 / 记录变量”操作将在 Labvanced 的每个实验中使用，因为它是存储和记录值及行为测量的方法。 

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/set_record_variable.webp" alt="设置/记录变量操作在事件系统中的位置" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

点击此操作后，将出现以下对话框菜单，您可以指定应该记录哪个变量及其感兴趣的值：

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/set_record_variable_options.webp" alt="设置/记录变量选项在事件系统中的位置" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

| 菜单项 | 菜单区域 | 描述 |
|:-----:|-----| ---------| 
| **`Select`** | ![选择分配变量的参与者](/content_imgs/learn/guide/task-editor/imgs/events/select_button.webp) | 点击选择后，您指定哪个变量应存储该值。您还可以在这里创建一个新变量。   |
| 笔图标 | ![选择分配变量的参与者](/content_imgs/learn/guide/task-editor/imgs/events/value_select_icon.webp) | 笔图标象征着 [值选择菜单](#the-value-select-menu)，用于定义和指定应分配给所选变量的确切值（如等号（=）左侧的绿色按钮所指定）。   |


在下面的示例中，我们创建了一个名为 `counter` 的新变量，并从值选择菜单中使用算术选项使变量值增加 1（基于上一步骤中定义的触发器）。 

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/counter_ex.webp" alt="在 Labvanced 中创建计数器变量" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

下图记录鼠标 X,Y 坐标，以捕捉研究期间的鼠标跟踪。下图展示了如何使用三个操作来实现变量值记录。左侧的变量是手动创建的，而等号（=）右侧的值是系统提供的 [鼠标触发特定值](#trigger-mouse-values)，您可以在记录值时引用。 

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/mouse_track_ex.webp" alt="在 Labvanced 中创建鼠标跟踪和坐标测量的变量" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

**注意：** `Set / Record Variable` 操作通常也用于 [`Control Actions`](#control-actions) 上下文中，您可以根据变量值使用“如果/则”和“循环”的条件。 

#### 复制到剪贴板操作 
效果：将变量值复制到计算机的内部剪贴板。 

#### 抽取随机数字操作
效果：抽取一个或多个随机数并将其保存在变量中

参数：
* 类型：选择连续值和离散值
* 分布：选择高斯分布和均匀分布
* 多次抽取（布尔值真/假）：选择抽取一次或多次。
* 抽取数量：选择抽取的数量
* 最小值：定义均匀分布的最小值
* 最大值：定义均匀分布的最大值
* 平均值：定义高斯分布的平均值
* 标准差：定义高斯分布的标准差
* 保存到变量：选择一个存储值的变量。

#### 获取 URL 参数操作
效果：从参与者的唯一 URL 中保存一个值

参数：
* 参数名称：输入所需参数的名称 
* 保存到变量：选择要保存参数值的变量

此操作可以与其他操作组合，以为参与者构造唯一的 URL 或提取数据分析所需的信息。 

#### 从/写入设备操作
效果：从本地设备的存储中读取或写入变量。此操作将数据保存到参与者的设备，而不是发送到 Labvanced 服务器。

参数： 
* 选择从本地设备读取或写入。
* 选择要读取或写入的变量。 

用例：纵向/多会话研究
* 使用此操作，可以将特定于设备的数据从会话传递到会话，前提是同一参与者在每个会话中使用同一设备。 
* 例如，您可以使用此操作记录每个参与者在会话 1 中呈现的图像，并确保在会话 2 中向他们呈现不同的图像。
    * 创建一个图像数组，并随机选择几个在每个会话中呈现。
    * 写入设备：会话 1 中呈现的图像的索引号。
    * 从设备读取：在会话 2 中，读取会话 1 中图像的索引并包含一个 JavaScript 操作，以防止选择这些索引用于第二会话。

#### 从/写入共享变量操作
效果：从跨研究会话共享的变量中读取或写入。该变量可以与所有参与者共享或私有化到每个个体。 

参数：
* 选择要同步的变量。必须是标量或数组。
* 高级选项
    * 存储键：选择一个变量的名称作为访问同步变量的键。
    * 读取或写入方法：
        * 从共享变量中读取，修改，然后写入：读取变量，进行更改，然后将变量发送到研究。
        * 仅从服务器读取共享值：调用在研究中共享的变量，但不进行任何更改。
        * 仅将变量写入服务器：对共享变量进行更改，但不向参与者显示。 
        * 在不同参与者之间共享值（不只是会话之间）：允许参与者在不同会话中查看彼此的同步变量值。默认情况下选择此选项，但可以通过单击复选框取消选择。
* 操作顺序：
    * 从所有可用操作列表中选择对共享/同步变量发生的操作。
```

用例：纵向/多会话研究
* 使用此操作，参与者特定的数据可以在会话间传递，并且可以在各会话之间共享给参与者。
* 例如，您可以使用此操作记录测试的得分，然后允许参与者将他们的得分与完成测试的其他参与者的平均得分进行比较。
* 另一个示例（类似于从/写入设备操作）是让参与者从一个数组中挑选出他们喜欢的5张图像，执行一个任务，然后在后续会话中再次呈现这5张图像。不同之处在于，此操作可以用来向其他参与者展示被选中的图像，或者将这些图像排除在其他参与者的可选项之外。

#### 数学与统计操作
效果：执行某些输入变量（数组）的数学运算，并将结果保存在输出变量中。

参数：
* 类型：选择数组操作、线性代数和统计测试
* 操作：选择一种数学运算（例如，求和、最小值、标准差等）
* 输入数组：选择要执行操作的输入变量（数组）
* 参数：某些操作有附加参数。
* 输出：选择一个输出变量，以存储结果。

#### 即时记录变量操作
效果：创建所有变量值的快照并将其发送到Labvanced服务器。

参数：无

#### 移动平均滤波器操作
效果：计算某些输入的移动平均（数据的不断更新的平均值），并将结果存储在一个新变量中。

参数：
* 滤波形状：选择滤波器类型
    * 简单移动平均：计算简单移动平均，其中所有样本具有相同的权重。
    * 线性加权移动平均：加权样本，使样本的权重线性减少。
    * 指数移动平均：加权样本，使样本的权重以指数方式减少。
* 样本数量：确定每个步骤使用多少个样本。
* 输入：选择要计算移动平均的输入变量（数组）
* 输出：选择一个输出变量，以存储结果。

#### 分配变量操作
分配变量操作是[Labvanced中的多用户研究](https://www.labvanced.com/content/technology/zh/multi-user-psychology-studies/)的关键。通过此操作，变量值可以在参与者之间共享，实质上允许信息（包括刺激位置和任何更改）在参与者的屏幕上反映出来。 

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/distribute_variable_menu.webp" alt="Labvanced操作菜单中的分配变量操作。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

选择此操作后，将出现以下对话框，您可以在其中指定正在参与者之间分配的变量值。 

下图显示的是所有菜单项都已填充时，功能分配变量操作对话框的样子。在此示例中，分配变量是一个用于通过分配输入字段对象的变量值在两个参与者之间创建聊天的一种方式。 

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/distribute_variable_example.webp" alt="分配变量在所有菜单选项设置作为示例时的使用。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

查看此演示，其中包含分配变量和聊天框功能：[带聊天附加功能的图像描述任务。](https://www.labvanced.com/page/library/3008)

有关对话菜单项的完整说明如下：

| 菜单项 | 菜单区域 |  分配变量操作选项和描述 |
|:-----:|-----| ---------| 
| **`Distribute value to`** | ![选择分配变量发送给哪些参与者](/content_imgs/learn/guide/task-editor/imgs/events/dist_participants.webp) | 选择应将该值发送给哪些其他参与者。 <ul><li>**所有参与者：**将该值发送给所有参与者</li><li>**选定参与者：**将该值发送给选定参与者。</li></ul> | 
| **`Choose target variable and value`** | ![指定变量目标和值](/content_imgs/learn/guide/task-editor/imgs/events/dist_target.webp) | <ul><li> **目标变量：**选择一个目标变量，以存储该值。</li><li>**值：**确定应发送给其他参与者的值。</li></ul>|
| **`Block`** | ![分配变量的块选项](/content_imgs/learn/guide/task-editor/imgs/events/block_dist_variable.webp) | 如果启用，则目标变量在当前值分配完成之前无法更改。 | 
| **`Rate Limit Strategy`**| ![分配变量的速率限制策略选项](/content_imgs/learn/guide/task-editor/imgs/events/dist_rate_limit.webp) | 速率限制策略是保护您的实验不超载服务器的一种方式，并作为控制请求速率（即通过分配变量的更新发送到服务器的请求）的预防策略。以下策略选项可用： <ul><li>**防抖：**当此操作在100毫秒的时间窗口内执行超过一次时，则新的服务器消息将被“防抖”（只有在100毫秒不再执行此操作后，最新消息将被发送）。</li><li>**节流：**当此操作在100毫秒的时间窗口内执行超过一次时，则新消息将被限制（即，在上一次发送消息以来经过100毫秒后，只有最新消息将被分配）。</li><li>**丢弃：**当此操作在100毫秒的时间窗口内执行超过一次时，则在该100毫秒窗口内的新消息将被丢弃。</li><li>**队列：**当此操作在100毫秒的时间窗口内执行超过一次时，则新的变量值将排队（最高队列大小为10条消息）。</li></ul> |

### 数组操作 

#### 从数组中选择（读取）操作
效果：将从数组中读取一个变量，并将该值存储在一个标量变量中。

参数：
* 数组变量：用于读取值的输入数组。
* 索引类型：确定使用何种索引。
    * 固定：为读取操作使用固定索引。在这种情况下，输入要读取的信息的位置（从1开始）。
    * 变量：使用数字变量作为读取操作的索引。在这种情况下，选择一个标量数字变量，以确定读取位置。
    * 数组末尾：从数组末尾读取。
* 输出变量：选择一个标量变量，以存储读取值。

#### 添加/删除数组条目操作
效果：将条目添加和/或从数组中删除。

参数：
* 数组变量：应执行添加或删除操作的数组变量。
* 索引类型：确定使用何种索引。
    * 固定：为插入/删除操作使用固定索引。在这种情况下，输入条目应被插入/删除的数组位置（从1开始）。
    * 变量：使用数字变量作为插入/删除操作的索引。在这种情况下，选择一个标量数字变量，以确定条目应插入/删除的位置。
    * 数组末尾：从数组末尾插入/删除。
* 要删除的条目数：将从定义的索引位置开始删除数组条目（在插入新条目之前）。0表示不删除任何值。
* 要插入的变量：选择一个或多个标量变量，这些变量将添加到数组变量的定义索引位置。

#### 更改（替换）数组条目操作
效果：将替换/更改数组中的一个值。

参数：
* 数组变量：数组变量，其中一个值应被修改
* 索引类型：确定使用何种索引。
    * 固定：为替换操作使用固定索引。在这种情况下，输入应更改的数组位置（从1开始）。
    * 变量：使用数字变量作为替换操作的索引。在这种情况下，选择一个标量数字变量，以确定替换操作的位置。
    * 数组末尾：替换数组中的最后一个条目。 
* 输入变量：选择一个（标量）变量，该变量持有新值。

#### 随机打乱数组条目操作
效果：将重新打乱数组中的条目/顺序。

参数：无

### 数据框操作

#### 从/写入数据框操作
效果：从数据框中读取值或向数据框中写入值，并将它们保存在新的数组变量中。

参数：
* 数据框变量：选择要读取的数据框变量。
* 读取或写入：选择从选定的数据框中读取或向选定的数据框中写入。 
* 按行或列：选择数据应如何被读取。
* 索引类型：选择将用于读取数据框的索引变量类型。可以是固定、变量或最后一行。
* 索引变量：选择将用作读取数据框的索引的变量。 
* 输出变量：选择将存储读取/写入数据作为输出的变量。必须是数组变量。```markdown
#### 洗牌数据框条目操作
效果：打乱数据框中条目的顺序。

参数：
* 选择要洗牌的数据框。
* 选择数据框是否应按行或列洗牌。

### 跳转操作

#### 跳转到操作
效果：“跳转”参与者到实验中的不同步骤。此操作可以改变实验中试验和任务的顺序，并可用于为每个参与者创建个性化的实验逻辑。

参数：
* 跳转到：确定在实验中跳转到的位置。
    * 下一个框架：跳转到下一个框架。如果试验中没有定义更多框架，则将跳转到下一个试验的第一个框架。
    * 下一个试验：跳转到下一个试验。如果没有定义更多试验，则将跳转到下一个任务的第一个试验。
    * 下一个任务：跳转到下一个任务。如果没有定义更多任务，则将跳转到下一个区块的第一个任务。
    * 下一个区块：跳转到下一个区块。如果没有定义更多区块，实验将结束。
    * 上一个框架：跳转到上一个框架。如果没有上一个框架，则不会执行该操作。
    * 特定框架：跳转到特定框架。用户直接选择要跳转的框架。
    * 特定试验：跳转到特定试验。用户直接选择要跳转的试验编号。
    * 特定任务：跳转到当前区块中指定任务的第一次实例。用户直接选择要跳转的任务。
    * 特定区块：跳转到指定区块的第一次实例。用户直接选择要跳转的区块。
* 跳转前检查必需答案：如果启用，实验将检查所有必需答案是否已经回答。如果没有，跳转操作将不被执行。

#### 接受/结束会话操作
效果：将接受参与者的数据，结束录音会话并显示众包代码。

参数：
* 在完成会话前记录试验数据：如果启用，最新的试验数据将在退出研究前存储（发送到服务器）。
* 显示默认结束页面：如果启用，默认的 Labvanced 结束屏幕将出现。如果这是一个众包会话（使用了众包链接），补偿代码将显示给参与者。如果禁用，实验将在显示当前框架后结束，并不会显示默认的结束屏幕和补偿代码。

#### 拒绝/结束会话操作
效果：结束录音会话，**不**将参与者的数据标记为完成，且**不**显示默认的结束屏幕和补偿代码。

在使用此操作拒绝参与者的数据时，用户应向参与者显示适当的信息，解释他们为何将不被奖励时间。

参数：无

#### 重定向到 URL 操作
效果：将参与者重定向到特定的 URL。

注意：该 URL 必须以 https:// 开头才能使该操作正常工作。

### 控制操作

#### 需求操作（如果...那么...否则如果）操作
效果：评估一个如果-那么语句并依赖地执行一系列操作。每个如果/否则如果语句由嵌套的 AND / OR 比较组成，以评估所有要求是否满足（语句为真）或不满足（语句为假）。如果语句为真，则执行“然后”下的操作。

参数：
* 添加要求：向语句添加新的要求。“值选择”菜单将在两侧出现，以进行逻辑比较。在语句中间，您可以选择如何比较两侧（例如相等、小于、不等等）。
* 添加或组：在 OR 组中的所有要求中，只需一个为真即可使整个组为真。如果子操作需要在多种情况下执行，请添加 OR 组。
* 添加且组：在 AND 组中的所有要求必须为真才能使整个组为真。如果子操作仅在满足多个要求时才执行，请添加 AND 组。
* 操作序列：每个如果/否则如果语句都有一个操作列表，该列表在“然后”下定义。操作序列列出特定如果/否则如果语句的所有操作。可以通过“添加操作”图标添加新操作。操作序列仅在相关的如果/否则如果语句的要求满足时执行。
* 添加否则如果案例：要求操作可以包含多个独立的如果/否则如果 --> 然后语句。但是，仅能执行一个语句。如果某个如果/否则如果语句被正面评估（返回真），则“然后”块中的操作将被执行，其余的要求操作将被跳过。
* 添加否则案例（真/假）：如果启用，将为要求操作添加默认/后备选项。如果没有执行任何如果/否则如果语句（返回真），则将执行在否则案例中定义的操作。

#### 重复操作（循环）操作
效果：反复执行一系列操作，可以立即执行或在定义的间隔内执行。可以指定停止条件，以便循环执行将被停止。

参数：
* 执行类型：选择立即执行或定时执行
    * 执行完整循环：这将持续执行循环，直到停止条件满足。
    * 每...毫秒执行：这将在定义的间隔内执行循环（例如，循环每50毫秒执行）。
* 定义循环次数：当选择“每...毫秒执行”时，用户可以为循环应执行的次数分配一个整数值。这替代了定义停止条件的需要。
* 执行间隔：这确定执行的间隔。
* 立即开始（真/假）：如果启用，这将在立刻执行循环。如果禁用，循环将在下一个执行间隔开始。
* 允许多次启动（真/假）：如果启用，可以并行启动多个循环实例。如果禁用，任何时间只能执行一个循环实例。
* 启用停止条件（真/假）：如果启用，可以为循环指定停止条件。
* 停止条件：停止条件可以用来指定逻辑表达式，以确定何时停止循环执行。类似于如果/否则如果语句，可以组合 AND 组、OR 组和要求进行逻辑比较。
* 操作序列：操作序列列出在每次循环迭代中执行的所有操作。可以通过“添加操作”图标添加新操作。

#### 延迟操作（时间回调）操作
效果：在某个时间延迟后执行一系列操作。

参数：
* 延迟类型：选择固定延迟或可变延迟
    * 固定延迟：操作将在固定延迟后执行。
    * 可变延迟：操作将在指定的（数值）变量延迟后执行。
* 延迟：以毫秒（ms）为单位的延迟长度。
* 操作序列：操作序列列出在指定时间延迟后执行的所有操作。可以通过“添加操作”图标添加新操作。

#### 操作组

操作也可以组织成**操作组**。操作组允许您将某些操作组合在一起，以便更容易视觉结构，但也适用于您想要一次性复制、重复或删除多个操作的情况。

[了解更多.](/content/learn/zh/guide/events/action-group.html)

### API 操作

如果您需要将数据从外部服务器发送或传输到 Labvanced，那么可以使用“API 操作”和 [“API 触发器”](/content/learn/zh/guide/task-editor/event-system.html#api-triggers)。在此类别下，您可以使用以下操作：
* 发送 PostMessage
* 发送到 Websocket
* 发送到 OpenAI

为了使这些操作“可用”或可执行，您必须在 [`Settings`](/content/learn/zh/guide/settings/) 标签下输入 API 密钥。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/api_menu.webp" alt="Labvanced 操作菜单中的 API 操作。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

#### 发送 PostMessage 操作

`Send PostMessage` 操作使用浏览器的 postMessage API 从运行的 Labvanced 实验发送消息到外部目标，例如父网页或嵌入的框架。

[了解更多.](/content/learn/zh/guide/events/send-postmessage-action.html)

#### 发送到 Websocket 操作

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/websocket_a_menu.webp" alt="Labvanced 操作菜单中的发送到 Websocket 操作。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

选择此操作时，将出现以下选项：

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/websocket_action_m.webp" alt="发送到 Websocket 操作的选项。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

上面的示例及完整的事件结构可以在此处访问：[https://www.labvanced.com/page/library/51053](https://www.labvanced.com/page/library/51053) 点击“检查”。

| 菜单项 | 描述 |   
|----------|----------| 
| **发送到：** | 指定在 [`Settings`](/content/learn/zh/guide/settings/) 标签下列出的 Websocket 地址。 | 
| **触发器/要发送的消息：** | 指定要发送的触发器或消息。 | 
| **发送变量（可选）：** | 指定可以作为操作的一部分发送的变量。 |

**[有关 API 访问的更多信息，请访问本页面。](https://www.labvanced.com/content/learn/zh/guide/api-access/)**

#### 发送到 OpenAI 操作
“发送到 OpenAI”操作允许您将信息（例如字符串输入值）发送到 OpenAI。请注意，使用此选项必须在 [`Settings`](/content/learn/zh/guide/settings/) 标签下列出您的 API 密钥。
```<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/openai_a_menu.webp" alt="Labvanced 操作菜单中的发送到 OpenAI 操作。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

点击此事件后，将出现以下选项：

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/openai_dialog_action.webp" alt="发送到 OpenAI 操作的选项。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

这是在提供所有必要信息时，此事件的功能示例：

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/openai_ex_action.webp" alt="发送到 OpenAI 操作被利用的示例。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

为了更好地理解您如何利用此功能并查看其实际效果，请随时联系我们以演示，通过提交[此联系表单](https://www.labvanced.com/?openCallDialog=true)。

**注意：** 另请参考[此体验指南](/content/learn/zh/walkthroughs/2024-09-chatgpt-study-example/)，在该指南中，我们逐步构建研究，将 ChatGPT 集成到研究中并利用此操作。

以下是对“发送到 OpenAI”操作下包含字段的更深入解释：

| 菜单项 | 菜单区域 | “发送到 OpenAI”操作选项 |
|:-----:|----| ----------| 
| **`Model Type`**   |  ![模型类型下拉列表](/content_imgs/learn/guide/task-editor/imgs/events/ai_model_type.webp)    | <img width=500/> 指定即将使用的 AI 模型。 <br><br>   |
| **`Chat History Dataframe`**   | ![指定数据框变量的字段](/content_imgs/learn/guide/task-editor/imgs/events/ai_df.webp)   | 连接到具有两列的数据框。第一列将表示“角色”，第二列为“聊天消息”。操作中的值将自动附加到此处链接的数据框中。 <br><br> 数据框也可以通过数据框操作进行操作。有关更多参考，请查看 [OpenAI 的文档](https://platform.openai.com/docs/api-reference/chat/create)。 |
| **`Insert Message ‘+’ `**   |  ![插入消息图标.](/content_imgs/learn/guide/task-editor/imgs/events/ai_roles.webp)    | 点击此处将出现变量对话框。您需要指明哪个“变量”值被发送到 OpenAI，以及相关消息的“角色”：<ul><li>**system:** 指高层次的 ChatGPT 系统 </li><li>**user:** 参与者 </li><li>**assistant:** 指在系统内创建的特定子角色  </li></ul> |

由于 OpenAI 每天都在发展，请查看 [OpenAI 的文档](https://platform.openai.com/docs/api-reference/chat/create) 以获取进一步的澄清。

### 代码操作

在某些情况下，您的实验可能需要您使用自定义代码。通过这些操作，您可以做到这一点！在“代码操作”菜单下提供以下选项：
* 运行 JavaScript
* 设置全局 CSS

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/code_actions_menu.webp" alt="Labvanced 操作菜单中的代码操作。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

#### 运行 JavaScript 操作
“运行 JavaScript”操作允许您编程特定事件，并通过输入自定义 JavaScript 来读取/设置 Labvanced 变量，该 JavaScript 将在触发时作为操作运行。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/run_js.webp" alt="Labvanced 操作菜单中的运行 JavaScript 操作。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

当选择上述“运行 JavaScript”操作时，您将看到一个区域（代码编辑器），在其中应该编写 JavaScript 代码，以及关于如何使用它的说明：

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/js_editor.webp" alt="Labvanced 中的 JavaScript 代码编辑器。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

#### 设置全局 CSS 操作
使用“设置全局 CSS”操作，您可以使用自定义 CSS 代码在触发时更改研究的某个方面。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/global_css.webp" alt="Labvanced 操作菜单中的设置全局 CSS 操作。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

点击此操作后，将打开以下字段：

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/css_editor.webp" alt="Labvanced 中的 CSS 代码编辑器。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

使用“设置全局 CSS”操作的一个示例是在参与者从多项选择问题中选择特定颜色时更改研究的背景颜色。

### 粘贴操作
此选项允许您粘贴先前创建和复制的操作。这使您在设计实验时能够更快地工作，从而不必反复选择相同的项目。例如，如果您有一个与已经存在的事件相似的事件，您可以直接复制、粘贴并修改它，而不是从头开始构建。

## 值选择菜单
<img align="left" width="10%" style="padding: 10px;" height="auto" loading ="lazy" src="/content_imgs/learn/guide/task-editor/imgs/events/value_select_icon.webp"> 在处理某些事件时，您会注意到一个笔图标出现。这被称为值选择菜单，因为它允许您选择并指示要记录或跟踪什么类型的值。这是您必定会在实验设计和设置中使用的非常强大和重要的选项。

此笔图标 / 值选择菜单在事件系统中某些操作的各个位置出现，例如设置/记录变量操作、设置对象属性操作和需求（如果...则）操作，如下所示。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/value_select_menu_locations.webp" alt="Labvanced 中的值选择位置。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

点击笔图标会导致一个下拉菜单，在其中您可以指定要读取或写入的值。**下拉菜单将始终首先列出特定于触发器的值选项，然后继续到其他 5 个类别（当前时间、常量值、变量、框架/任务/选项和操作），每个类别都有其自己的选项。** 这些将在下面更详细地描述。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/value_select_menu.webp" alt="Labvanced 中的值选择菜单" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

上面的图像显示了在使用鼠标触发时值选择菜单的样子。正如您所见，左侧的第一个菜单项以特定于触发器的类别开始，然后转到其他 5 个类别（当前时间等）。

### 菜单选项
下表进一步解释了类别和选项：

| 类别 | 选项 | 描述 |
|:---:|---|---|
| [`Trigger-specific`](#trigger-specific-values) |  取决于您之前为事件选择的触发器类型。 | 根据您为事件选择的触发器，值选择菜单顶部将出现特定的选项列表供您选择。请参阅 [特定于触发器的值](#trigger-specific-values) 部分以查看完整的选项和描述列表。 |
| [`Current Time`](#current-time-values) | <ul><li> [UNIX 时间戳](#current-time-unix-timestamp) </li><li> [从框架开始的时间](#current-time-time-from-frame-onset) </li> </ul> | 测量和调用时间值。 |
| [`Constant Value`](#constant-values) | <ul><li> 字符串 </li><li> 数字 </li><li> 布尔 </li><li> 类别 </li><li> 日期</li><li> 时间 </li><li> 色彩 </li> </ul> | 根据您需要的变量类型（如字符串或数字）分配常量值。这些值有时与其他选项如 [`Arithmetic`](#arithmetic) 结合使用以创建计数器。 |
| [`Variable`](#variable-values) | <ul> <li> 选择变量 </li><li> 从数组中选择值 </li><li> 从数据框中选择值 </li></ul> | 指定或引用变量或从数组或数据框中选择值。 |
| [`Frame / Task / Object`](#frame-task-object-values) | <ul><li> 对象属性 </li><li> 框架 </li><li> 眼动追踪 </li><li> 设备 </li> </ul> | 允许您获取与对象属性、框架、眼动追踪（如果已激活）和设备（屏幕刷新率）相关联的值。 |
| [`Operations`](#operations) | <ul><li>算术 </li><li> 字符串操作 </li><li> 数学操作 </li> </ul> | 使用操作对变量进行指定的更改，如组合变量值、将字符串转换为全小写或执行数学操作。 |

### 当前时间值
通过“当前时间”选项，您可以记录或参考与时间相关的值。

提供以下选项：
* [UNIX 时间戳](#current-time-unix-timestamp)
* [从框架开始的时间](#current-time-time-from-frame-onset)#### 当前时间：UNIX时间戳
该值以毫秒为单位捕获UNIX格式的时间戳。  

#### 当前时间：从帧开始的时间
该值捕获从帧开始已过的时间。通常，这等同于反应时间。

### 常量值
根据所需的变量类型分配常量值，例如字符串或数字。这些常量有时与其他选项结合使用，如 [`Arithmetic`](#arithmetic) 来创建计数器。

以下选项可用：
* [字符串](#constant-string)
* [数字](#constant-numeric)
* [布尔](#constant-boolean)
* [分类](#constant-categorical)
* [日期](#constant-date)
* [时间](#constant-time)
* [颜色](#constant-color)

#### 常量：字符串
分配字符串/文本值。

#### 常量：数字
分配数字/数值。

#### 常量：布尔
分配 true 或 false 值。

#### 常量：分类
分配水平值（主要用于因子）。

#### 常量：日期
分配日期值。

#### 常量：时间
分配时间值。

#### 常量：颜色
分配颜色（十六进制字符串）值。

### 变量值
指定或引用变量，或从数组或数据框中选择值。以下选项可用：
* [选择变量](#select-variable)
* [从数组中选择值](#select-value-from-array)
* [从数据框中选择值](#select-value-from-data-frame)

#### 选择变量
允许您选择并指向一个变量。

#### 从数组中选择值
允许您从数组中选择一个值。

#### 从数据框中选择值
允许您从您创建的数据框中选择一个值。

### 帧/任务/对象值
允许您获取与对象属性、帧、眼动追踪（如果已激活）和设备（屏幕刷新率）相关的值。
* [对象属性](#object-property)
* [帧](#frame)
* [眼动追踪](#eye-tracking)
* [设备](#device)

#### 对象属性 
读取对象属性。

#### 帧

| 帧值选项 | 描述 |
| :---: | ---|
| **`Last cached Mouse X Position`** | 参与者鼠标的最后 X 坐标值。 |
| **`Last cached Mouse Y Position`** | 参与者鼠标的最后 Y 坐标值。 | 
| **`Last cached Mouse [X,Y] Array`** | 参与者鼠标的最后 [X,Y] 坐标值，采用数组格式。 | 
| **`Frame Name`** | 帧的名称。 |  

#### 眼动追踪

| 眼动追踪值选项 | 描述 |
| :---: | ---|
| **`Last cached Coordinate X`** | 参与者注视的最后 X 坐标值。 |
| **`Last cached Coordinate Y`** | 参与者注视的最后 Y 坐标值。  | 
| **`Last cached Coordinate [X,Y] Array`** | 参与者注视的最后 [X,Y] 坐标值，采用数组格式。 | 
| **`Last cached Coordinate + Time [X,Y,T] Array`** | 参与者注视的最后 [X,Y] 坐标值，加上相机捕捉 T 值，采用数组格式。 |  

#### 设备
* **刷新率:** 参与者设备的刷新率值。

### 操作
使用操作对您的变量进行指定的更改，例如合并变量值、将字符串转换为全小写或执行数学操作。

以下选项可用：
* [算术](#arithmetic)
* [字符串操作](#string-operation)
* [数学操作](#math-operation)

#### 算术 
算术操作对于许多不同的目的非常有用，包括合并字符串甚至修改对象属性。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/arithmetic_menu.webp" alt="Labvanced中的算术菜单。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

本质上，算术操作允许您对多个值进行操作。

选择此选项后，会出现额外的笔图标（即值选择菜单），以及一系列操作，如加法。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/arithmetic_selected.webp" alt="Labvanced中的算术选项位置。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

可以使用这 5 种不同的操作对值进行操作：
* (+) 加法
* (-) 减法
* (/) 除法
* (*) 乘法
* (%) 取模

下面的示例展示了如何利用算术操作创建一个新的字符串变量（在绿色按钮中），名为'intermediateVar'。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/chat_example_explained.webp" alt="使用算术运算创建新字符串变量的示例。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

新变量值（'intermediateVar'）由使用多个算术操作与之前创建的变量（即'userChatName'和'chatInput'）的组合定义，以及 [常量字符串值，](#constant-8594-string) 即分号 `:` 和断行空格 `<br>`。此操作创建了用户聊天的效果，可用于多用户研究。

#### 字符串操作

| 字符串操作选项 | 描述 |
| :---: | ---|
| **`To Lowercase`** | 将字符串变量中的所有字母转换为小写字母。<br><br> **&#8594; 示例:** (AAABBB) 转换为 (aaabbb) |
| **`To Uppercase`** | 将字符串变量中的所有字母转换为大写字母。 <br><br> **&#8594; 示例:** (aaabbb) 转换为 (AAABBB) |
| **`To Link`** | 将变量中的字符串转换为以另一个窗口打开的URL|
| **`Remove Whitespaces`** | 删除字符串变量中字母之间的任何空格。 <br><br> **&#8594; 示例:** (aaa bbbb cccc) 转换为 (aaabbbbccc) |
| **`Trim Whitespaces`** | 删除字符串变量开头的空格。 <br><br> **&#8594; 示例:** (  aaabbbcccc) 转换为 (aaabbbcccc) |
| **`Replace Substring Regexp`** | 替换字符串值变量中的某些字母。 <br><br> **&#8594; 示例:**  (aaabbbccc) 将 _bbb_ 替换为 _xxx_ ，使得该值转变为 (aaaxxxccc) |

#### 数学操作
对标量值执行数学操作。

| 数学操作选项 | 描述 |
| :---: | ---|
| **`abs`** | 返回值的绝对值。 |
| **`sqrt`** | 返回值的平方根。 | 
| **`round`** | 返回四舍五入到 0 到 3 位小数的值。 | 
| **`floor`** | 返回向下取整的值。 |  
| **`ceil`** | 返回向上取整的值。 | 
| **`cos`** | 返回余弦值。 | 
| **`sin`** | 返回正弦值。 | 
| **`tan`** | 返回正切值。 | 

### 触发器特定值

触发器特定值是指与特定事件内定义的触发器相关的值。例如，如果您的事件使用鼠标触发器，那么，在指定动作的某些区域下（例如在使用 [`Set / Record Variable`](#set-record-variable-action) 行动或 [`Set Object Property`](#set-object-property-action) 行动时），您可以在[值选择菜单](#the-value-select-menu) 中引用鼠标触发器特定值。

在下面的示例中，使用鼠标触发器的触发器特定值记录 x 值和 y 值以及使用 [`Set / Record Variable`](#set-record-variable-action) 行动创建的 [X,Y] 数组。

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/mouse_track_ex.webp" alt="演示如何使用鼠标特定的触发值进行鼠标追踪。" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p>

下面是 Labvanced 中所有类型的触发器特定值的表格，后面是每个选项的详细说明。

| 名称| 值选项 - 概览 |
| :---: | ---|
| [`Trigger (Mouse)`](#trigger-mouse-values)  | <ul><li> 鼠标 X </li><li> 鼠标 Y </li><li> 鼠标 [X,Y] 数组 </li><li> 刺激名称 </li><li> 刺激信息 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li> </ul> <img width=500/>|
| [`Trigger (Keyboard)`](#trigger-keyboard-values) | <ul><li> 键的 ID </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (Button Bar)`](#trigger-button-bar-values) | <ul><li> 刺激名称 </li><li> 刺激信息 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (Enter On Input)`](#trigger-enter-on-input-values)  | <ul><li> 键的 ID  </li><li> 触发时间戳（Unixtime）  </li><li> 触发时间（从帧开始）  </li></ul> |
| [`Trigger (Scroll)`](#trigger-scroll-values) | <ul><li> 刺激名称 </li><li> 刺激信息 </li><li> 滚动位置 X </li><li> 滚动位置 Y </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> | 
| [`Trigger (Gamepad/ Joystick)`](#trigger-gamepad-joystick-values) | <ul><li>手柄设备 ID </li><li> 按下的键（数组） </li><li> 按下或保持的键（数组） </li><li> 释放的键（数组） </li><li> 轴（数组） </li><li> 手柄时间戳（Unixtime） </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (Eyetracking Gaze)`](#trigger-eyetracking-gaze-values) | <ul><li> 坐标 X </li><li> 坐标 Y </li><li> 坐标 [X,Y] 数组 </li><li> 刺激名称 </li><li> 刺激信息 </li><li> 相机捕捉时间 T </li><li> 注视置信度 C </li><li> 坐标 + 时间 [X,Y, T] 数组 </li><li> 坐标 + 时间 + 置信度 [X,Y, T,C] 数组 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> | 
| [`Trigger (Eyetracking Fixation)`](#trigger-eyetracking-fixation-values) | <ul><li> 注视质心 X </li><li> 注视质心 Y </li><li> 注视持续时间 </li><li> 注视开始时间 </li><li> 注视结束时间 </li><li> 注视分散度 </li><li> 刺激名称 </li><li> 刺激信息 </li><li> [X,Y, Dur, Start, End, Disp] </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始）  </li></ul> |
| [`Trigger (Head Tracking)`](#trigger-head-tracking-values) |  <ul><li> 相机捕捉时间 T </li><li>  头部转动 </li><li>  头部倾斜 </li><li>  头部滚动 </li><li>  头部位置 [X,Y, T] 数组 </li><li>  鼻子位置 [X,Y, T] 数组 </li><li>  鼻子向量 [X,Y, Z, T] 数组 </li><li>  触发时间戳（Unixtime） </li><li>  触发时间（从帧开始） </li></ul> |
| [`Trigger (On Task Initialization)`](#trigger-on-task-initialization-values) |  <ul><li>  触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (On Frame Init)`](#trigger-on-frame-init-values) |  <ul><li> 试验编号 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (on Frame Start)`](#trigger-on-frame-start-values) |  <ul><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (On Frame End)`](#trigger-on-frame-end-values)  |  <ul><li> 总帧时间 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |		
| [`Trigger (Variable Value Changed)`](#trigger-variable-value-changed-values) |  <ul><li> 变量的新值 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (Media Object Trigger)`](#trigger-media-object-trigger-values) |  <ul><li>  触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (Websocket Trigger)`](#trigger-websocket-trigger-values) |  <ul><li> 消息 </li><li> 数据 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (OpenAI Trigger)`](#trigger-openai-trigger-values) |  <ul><li> Chat GPT回答 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (PostMessage Received)`](#trigger-postmessage-received-values) |  <ul><li> 消息内容 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |
| [`Trigger (Global Experiment Event)`](#trigger-global-experiment-event-values) |  <ul><li> 总帧时间 </li><li> 全球事件的原因 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始）  </li></ul> |
| [`Trigger (User Leaves Experiment)`](#trigger-user-leaves-experiment-values) |  <ul><li> 剩余参与者数量 </li><li> 触发时间戳（Unixtime） </li><li> 触发时间（从帧开始） </li></ul> |#### 触发器（鼠标）值
当使用[鼠标触发器](#mouse-trigger)时，可以在处理某些操作时调用以下[特定于触发器的值](#trigger-specific-values)：  

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/mouse_trigger_specific_values.webp" alt="可用的鼠标触发值选项" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

| 触发器（鼠标）选项 | 描述 |
| :---: | ---|
| **`Mouse X`** | 返回当前在帧坐标中的鼠标 X 位置。 |
| **`Mouse Y`**| 返回当前在帧坐标中的鼠标 Y 位置。 |
| **`Mouse [X,Y] Array`** | 鼠标的 [X,Y] 坐标，格式为数组。 | 
| **`Stimulus Name`** | 触发事件的对象的名称（例如点击了哪个图像）。 |
| **`Stimulus Info`** | 触发事件的对象的刺激信息。 |
| **`Trigger Timestamp (Unixtime)`** | 触发发生时的时间戳，使用 Unix 时间格式，并包含毫秒。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到触发发生的经过时间，以毫秒为单位。 |


#### 触发器（键盘）值
当使用[键盘触发器](#keyboard-triggers)时，可以在处理某些操作时调用以下特定于触发器的值： 

| 触发器（键盘）选项 | 描述 |
| :---: | ---|
| **`Id of Key`** | 按下的键作为触发器的 ID 值。 |
| **`Trigger Timestamp (Unixtime)`** | 触发发生时的时间戳，使用 Unix 时间格式，并包含毫秒。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到触发发生的经过时间，以毫秒为单位。 |

#### 触发器（按钮栏）值

当使用[按钮点击触发器](#button-click-trigger)时，可以在处理某些操作时调用以下特定于触发器的值：

| 触发器（按钮栏）选项 | 描述 |
| :---: | ---|
| **`Stimulus Name`** | 触发事件的按钮对象的名称。 |
| **`Stimulus Info`** | 触发事件的按钮对象的刺激信息。 |
| **`Trigger Timestamp (Unixtime)`** | 触发发生时的时间戳，使用 Unix 时间格式，并包含毫秒。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到触发发生的经过时间，以毫秒为单位。 |

#### 触发器（输入时回车）值

当使用[输入时回车触发器](#enter-on-input-trigger)时，可以在处理某些操作时调用以下特定于触发器的值：

| 触发器（输入时回车）选项 | 描述 |
| :---: | ---|
| **`Id of Key`** | 按下的键作为触发器的 ID 值。 |
| **`Trigger Timestamp (Unixtime)`** | 触发发生时的时间戳，使用 Unix 时间格式，并包含毫秒。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到触发发生的经过时间，以毫秒为单位。 |


#### 触发器（滚动）值

当使用[滚动触发器](#scroll-trigger)时，可以在处理某些操作时调用以下特定于触发器的值：

| 触发器（滚动）选项 | 描述 |
| :---: | ---|
| **`Stimulus Name`** | 触发事件的按钮对象的名称。 |
| **`Stimulus Info`** | 触发事件的按钮对象的刺激信息。 |
| **`Scroll Position X`** | 事件触发时鼠标在 X 轴上的滚动位置。  |
| **`Scroll Position Y`** | 事件触发时鼠标在 Y 轴上的滚动位置。|
| **`Trigger Timestamp (Unixtime)`** | 触发发生时的时间戳，使用 Unix 时间格式，并包含毫秒。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到滚动触发发生的经过时间，以毫秒为单位。 |

#### 触发器（游戏手柄/操纵杆）值

当使用[`Gamepad/Joystick trigger`](#gamepad-joystick-trigger)时，可以在处理某些操作时调用以下特定于触发器的值：

<p style="text-align:center;">
<img width="80%" style="padding: 10px; border:1px solid #39AECB" height="auto" loading="lazy" src="/content_imgs/learn/guide/task-editor/imgs/events/gamepad_trigger_specific.webp" alt="游戏手柄触发菜单选项">
</p>

| 触发器（游戏手柄/操纵杆）选项 | 描述 |
| :---: | ---|
| **`Gamepad Device Id`** | 连接的游戏手柄的 ID 或名称。 |
| **`Pressed Keys (Array)`** | 按下的键。 |
| **`Pressed OR Hold Keys (Array)`** | 被按下或保持的键。 |
| **`Released Keys (Array)`** | 被释放的键。 |
| **`Axes (Array)`** | 轴值。 |
| **`Gamepad Timestamp (Unixtime)`** | 游戏手柄的时间戳，以 Unix 时间表示。|
| **`Trigger Timestamp (Unixtime)`** | 触发发生的时间戳，以 Unix 时间表示。 |
| **`Trigger Time (From Frame Onset)`** | 触发发生时间戳相对于帧开始的时间戳，以 Unix 时间表示。 |

#### 触发器（眼动追踪注视）值

当使用[眼动追踪注视触发器](#eyetracking-gaze-trigger)时，可以在处理某些操作时调用以下特定于触发器的值：

<p style="text-align:center;">
<img src="/content_imgs/learn/guide/task-editor/imgs/events/ET_gaze_trigger_specific_values.webp" alt="注视触发值选项" width="80%" style="border:1px solid #39AECB" height="auto" loading="lazy">
</p> 

| 触发器&nbsp;(眼动追踪注视)&nbsp;选项  | 描述  |
| :---: | --- |
| **`Coordinate X`** | 注视的 X 坐标值。 |
| **`Coordinate Y`** | 注视的 Y 坐标值。 |
| **`Coordinate [X,Y] Array`** | 注视坐标 X,Y，格式为数组。 |
| **`Stimulus Name`** | 触发注视的刺激的名称。 |
| **`Stimulus Info`** | 触发注视的刺激背后的刺激信息。  |
| **`Camera Capture Time T`** | 快照发生的确切时间。在 Labvanced 的眼动追踪流程中，相机快照在算法和神经网络执行注视计算之前首先发生。因此，`Camera Capture Time T` 是初始快照发生的 UNIX 时间戳。有关我们基于网络摄像头的眼动追踪技术的更多信息，请参考我们的[ET技术页面](/content/technology/zh/labvanced-eye-tracking/)。   |
| **`Gaze Confidence C`** | 此值的范围为 0 到 1，表示图像快照中存在开放眼睛的置信度和概率，实际充当“眨眼检测器”。有关更多详细信息，请参阅我们[发表的同行评审论文](https://link.springer.com/article/10.3758/s13428-023-02237-8)。  |
| **`Coord. + Time [X,Y,T] Array`** | 包含注视的 x/y 坐标和相机捕捉时间 (T) 的时间戳的数组，如上所述。  |
| **`Coord. + Time + Confidence [X,Y, T,C] Array`** | 包含注视的 x/y 坐标、相机捕捉时间 (T) 和注视置信度 (C) 的时间戳的数组，如上所述。 |
| **`Trigger Timestamp (Unixtime)`** | 触发注视发生的时间戳，使用 Unix 时间格式，并包含毫秒。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到触发注视发生的经过时间，以毫秒为单位。 |

#### 触发器（眼动追踪注视停留）值

当使用[眼动追踪注视停留触发器](#eyetracking-fixation-trigger)时，可以在处理某些操作时调用以下特定于触发器的值：```
| Trigger&nbsp;(Eyetracking Fixation) Options | Description |
| :---: | ---|
| **`Fixation Centroid X`** | 注视中心点的X值。 |
| **`Fixation Centroid Y`** | 注视中心点的Y值。 |
| **`Fixation Duration`** | 检测到的注视的持续时间。 |
| **`Fixation Start Time`** | 检测到的注视的开始时间。 |
| **`Fixation End Time`** | 检测到的注视的结束时间。 |
| **`Fixation Dispersion`** | 指的是在检测到的注视内，注视值的分散程度。 |
| **`Stimulus Name`** | 触发事件的按钮对象名称。 |
| **`Stimulus Info`** | 触发事件的按钮对象的刺激信息。 |
| **`[X, Y, Dur, Start, End, Disp]`** | 包含以下内容的数组：注视质心的x和y值，注视的持续时间，开始时间，结束时间和分散值。 |
| **`Trigger Timestamp (Unixtime)`** | 注视触发发生时的Unix时间格式的时间戳，精确到毫秒。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到注视触发发生所测量的经过时间，单位为毫秒。 |

#### Trigger (Head Tracking) Values

当使用[头部追踪触发器](#headtracking-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger&nbsp;(Head&nbsp;Tracking) Options | Description |
| :---: | ---|
| **`Camera Capture Time T`** | 当相机捕获帧时的时间，即帧捕获发生时的unix时间戳。这是图像/帧在任何处理发生之前被捕获的时间。 |
| **`Head Turn`** | 从左向右转动的头部，这在文献中称为偏航。 |
| **`Head Tilt`** | 从上到下倾斜的头部，在文献中称为头部俯仰。 |
| **`Head Roll`** | 捕捉头部从一侧滚动到另一侧的运动。 |
| **`Head Position [X,Y, T] Array`** | 该数组捕捉与头部位置相关的数值，包括头部中心的x和y坐标以及时间戳变量（T）。 |
| **`Nose Position [X,Y, T] Array`** | 该数组捕捉与鼻子位置相关的数值，包括鼻子位置的x和y坐标以及测量发生时的时间戳变量（T）。 |
| **`Nose Vector [X,Y, Z, T] Array`** | 此测量通过从鼻尖投射一个向量来工作，有助于测试参与者是否在关注屏幕（这在未启用眼动追踪的研究中尤为重要）。因此，如果鼻子指向屏幕外（即参与者没有关注实验），Z值从1减少并向0靠近。 |
| **`Trigger Timestamp (Unixtime)`** | 实验中触发事件发生的时间点，在检测到头部追踪时记录触发在系统中发生的时间。本质上，这是处理图像/帧的时间，这个值在很大程度上受到参与者图形卡的影响。从理论上讲，它应该尽可能接近值T。 |
| **`Trigger Time from Frame Onset`** | 这是触发发生时的时间值，相对于帧开始时的时间。 |

#### Trigger (On Task Initialization) Values

当使用[任务初始化触发器](#task-init-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (On Task Initialization) Options | Description |
| :---: | ---|
| **`Trigger Timestamp (Unixtime)`** | 触发器发生的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 触发发生时与帧开始的时间（毫秒）。 |

#### Trigger (On Frame Init) Values

当使用[帧初始化触发器](#frame-init-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (On Frame Init) Options | Description |
| :---: | ---|
| **`TrialNr`** | 帧初始化触发器发生时的试验编号。 |
| **`Trigger Timestamp (Unixtime)`** | 触发器的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 触发发生时与帧开始的时间（毫秒）。 |


#### Trigger (on Frame Start) Values

当使用[帧开始触发器](#frame-start-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (on Frame Start) Options | Description |
| :---: | ---|
| **`Trigger Timestamp (Unixtime)`** | 触发器的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 触发发生时与帧开始的时间（毫秒）。 | 


#### Trigger (On Frame End) Values

当使用[帧结束触发器](#frame-end-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (On Frame End) Options | Description |
| :---: | ---|
| **`Total Frame Time`** | 在帧上花费的总时间（毫秒）。 | 
| **`Trigger Timestamp (Unixtime)`** | 触发器的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 触发发生时与帧开始的时间（毫秒）。 | 


#### Trigger (Variable Value Changed) Values

当使用[变量值改变触发器](#variable-value-changed-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (Variable Value Changed) Options | Description |
| :---: | ---|
| **`New Value in Variable`** | 指新变量的值。 |
| **`Trigger Timestamp (Unixtime)`** | 变量值改变触发发生时的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到变量值改变发生所测量的经过时间（毫秒）。 |


#### Trigger (Media Object Trigger) Values

当使用[媒体对象触发器](#media-object-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (Media Object Trigger) Options | Description |
| :---: | ---|
| **`Trigger Timestamp (Unixtime)`** | 媒体对象触发发生时的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到媒体对象触发发生所测量的经过时间（毫秒）。 |


#### Trigger (Websocket Trigger) Values

当使用[Websocket 触发器](#websocket-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (Websocket Trigger) Options | Description |
| :---: | ---|
| **`Message`** | 可用于描述和标记的消息，让你（在接收端）可以在不同类型的数据之间进行过滤。  |
| **`Data`** | 可以保存不同类型数据的值，例如参与者的选择、时间戳、鼠标x/y坐标等。  |
| **`Trigger Timestamp (Unixtime)`** | Websocket触发发生时的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到WebSocket触发发生所测量的经过时间（毫秒）。 |


#### Trigger (OpenAI Trigger) Values

当使用[OpenAI 触发器](#openai-trigger)时，可以在某些操作中调用以下特定的触发值：
| Trigger (OpenAI Trigger) Options | Description |
| :---: | ---|
| **`Chat GPT Answer`** | ChatGPT的回答值。 |
| **`Trigger Timestamp (Unixtime)`** | OpenAI触发发生时的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到OpenAI触发发生所测量的经过时间（毫秒）。 |


#### Trigger (PostMessage Received) Values

当使用[接收PostMessage触发器](#postmessage-received-trigger)时，可以在某些操作中调用以下特定的触发值：

| Trigger (PostMessage Received) Options | Description |
| :---: | ---|
| **`Message Content`** | 接收的postMessage的数据载荷，由外部来源发送。 |
| **`Trigger Timestamp (Unixtime)`** | PostMessage Received触发发生时的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到触发发生所测量的经过时间（毫秒）。 |


#### Trigger (Global Experiment Event) Values

当使用[暂停/恢复实验触发器](#pause-resume-experiment)时，可以在某些操作中调用以下特定的触发值：

| Trigger (Global Experiment Event) Options | Description |
| :---: | ---|
| **`Total Frame Time`** | 指触发之前分配的总帧时间。 |
| **`Reason for Global Event`** | 声明触发原因的字符串值，例如参与者离开研究。 |
| **`Trigger Timestamp (Unixtime)`** | 全局事件触发发生时的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到全局事件触发发生所测量的经过时间（毫秒）。 |


#### Trigger (User Leaves Experiment) Values

当使用[参与者离开多用户研究触发器](#participant-left-multiuser-study)时，可以在某些操作中调用以下特定的触发值：

| Trigger&nbsp;(User&nbsp;Leaves Experiment) Options | Description |
| :---: | ---|
| **`Remaining Number of Participants `** | 研究中仍然参与者的数量。 |
| **`Trigger Timestamp (Unixtime)`** | 用户离开实验触发发生时的Unix时间戳（毫秒）。 |
| **`Trigger Time (From Frame Onset)`** | 从帧开始到用户离开实验触发发生所测量的经过时间（毫秒）。 |
```