事件系统

描述

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

• 有关完整的触发器列表
• 有关完整的动作列表
• 有关设置值的更多信息，请参阅值选择菜单

事件系统由触发器和动作组成。在这里你可以设置规则，比如“当发生这个（触发器）”然后“做这个（动作）”。例如：如果参与者点击特定图像（触发器），则显示不同的随机图像（动作）。

有关事件在Labvanced中如何工作的介绍，请参阅此快速视频：

创建事件 - 概述

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

无论如何，事件始终为指定帧的试验组中的所有试验定义。然而，自定义逻辑允许用户仅在某些试验、条件或其他情况下执行事件。

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

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

触发器

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

触发器类别	触发器选项	描述
用户输入触发器	鼠标触发器 键盘触发器 按钮点击 在输入时按下Enter 滚动触发器 游戏手柄/操纵杆触发器	用户输入触发器指任何可以通过用户/参与者手动激活的触发器，例如移动鼠标、点击键盘元素、滚动等。
生理信号触发器	眼动追踪注视 眼动追踪定点 头部追踪	生理信号触发器是在有指定生理输入时发生的，例如盯着特定元素或头部运动的变化。
试验和帧触发器	任务初始化 帧初始化 帧开始 帧结束	这些触发器与实验试验和帧相关，例如帧开始或结束时。
变量值改变触发器	变量（值改变）	当特定变量值发生改变时，事件的触发器。
媒体对象触发器	媒体对象触发器	该触发器与媒体对象相关，例如视频/音频文件暂停、录音完成等。
API触发器	Websocket触发器 Open AI触发器	这些是在有来自API的输入数据时发生的触发器。
全局触发器	暂停/恢复实验 参与者离开多人研究	全局触发器是指任何对实验的重大变化，例如实验被暂停或参与者在多人研究中离开。

用户输入触发器

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

下表提供了Labvanced中所有用户输入触发器的简介概述。每个触发器在后续部分将有更详细的描述。

用户输入触发器选项	概述
鼠标触发器	任何鼠标移动都可以用作触发器来启动事件，例如：滚动、点击、悬停等。你也可以将特定元素或目标与触发器关联。例如，只有在点击特定图像时，鼠标点击才将用作触发器。
键盘触发器	任何键盘按键都可以用作触发器来启动事件。你可以指定特定的字母或数字作为触发器。
按钮点击	在Labvanced中创建的按钮对象可以用作启动事件的触发器。
在输入时按下Enter	该触发器通常用于当参与者在实验中按下'Enter'时，作为提交其书面响应或文本框输入的手段。
滚动触发器	当参与者滚动时发生此触发器。你可以指定x轴或y轴的滚动方向，以及在哪些元素上滚动以用作事件触发器。
游戏手柄/操纵杆触发器	该触发器允许你在实验设计中使用游戏手柄和操纵杆控制器作为记录数据的输入设备。

鼠标触发器

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

下面的例子展示了一个‘鼠标触发器’，当在名为‘Image_1’的目标对象上执行‘左’鼠标点击时将发生：

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

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

• **注意：**选择鼠标触发器后，您可以使用和引用特定于触发器的鼠标值，通过值选择菜单在各种动作中。

键盘触发器

‘键盘触发器’选项是另一种流行的触发事件方式。基本上，来自键盘的任何输入都可以作为触发器。这包括：按下、保持或释放一个键。

以下示例设置了一个键盘按键触发器，在按下指定目标数字值（0、2或6）时发生：

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

菜单项	菜单区域	键盘触发器选项
动作 下拉列表：		这些是可用的键盘动作选项： **按下键：**通过按下键触发（键处于下压状态） **按下或保持键：**在键被按下或保持时触发 **释放键：**通过释放键触发 **注意：**键需要被释放才能再次作为触发器“触发”。
键 哪个键触发事件		通过在这里点击**+添加:来指定哪个键用作触发器的选项 箭头：四个方向键 数字：从0到9的数字 字母：所有英文字母 特殊：特殊键（Enter、空格、控制、Tab、Shift） F键：F1到F10 任意键：接受这些键中的任何键 你可以通过再次点击**+添加：**按钮添加多个键盘触发器
其他选项		启用数字键盘按钮选项允许在实验中使用数字键作为触发器。 允许事件传播选项，如果多个事件具有相同的键盘触发器，则所有事件/触发器都将触发。只有第一个事件会触发，事件执行会在第一个事件完成后停止。

• **注意：**选择键盘触发器后，您可以使用和引用特定于触发器的键盘值通过值选择菜单在各种动作中。

按钮点击触发器

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

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

以下是所包含项目的详细信息：

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

• **注意：**选择按钮点击触发器后，您可以使用和引用特定于触发器的按钮点击值通过值选择菜单在各种动作中。

在输入时按下Enter触发器

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

参数：

• 添加目标：将输入元素添加到事件中。

• **注意：**选择在输入时按下Enter触发器后，您可以使用和引用特定于触发器的Enter输入值通过值选择菜单在各种动作中。

滚动触发器

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

参数：

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

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

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

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

游戏手柄/操纵杆触发器

游戏手柄/操纵杆触发器允许您在实验设计中使用游戏手柄和操纵杆控制器作为记录数据的输入设备。**注意：**请记得在设置选项卡下启用此选项。

了解更多。

生理信号触发器

这些触发器仅在已为任务启用眼动追踪和/或头部追踪时适用。

眼动追踪注视触发器

触发条件：

• 总体来说，当已启用眼动追踪时，该触发器将生效。
• 只有在看特定元素时触发。

参数：

• 如果您选择仅在特定元素上触发，则将这些元素作为目标添加。

• **注意：**选择眼动追踪注视触发器后，您可以使用和引用特定于触发器的注视值通过值选择菜单在各种动作中。

眼动追踪定点触发器

该触发器仍处于BETA阶段。

• **注意：**选择键盘触发器后，您可以使用和引用特定于触发器的定点值通过值选择菜单在各种动作中。

头部追踪触发器

触发条件：

• 头部方向或头部运动的变化。

• **注意：**选择头部追踪触发器后，您可以使用和引用特定于触发器的头部追踪值通过值选择菜单在各种动作中。

试验和帧触发器

任务初始化触发器

触发条件：

• 任务的第一次试验的第一帧。尽管在“事件”选项卡中显示为该帧的所有实例，但每个任务仅执行一次。

该触发器与混洗和从操作结合使用时效果很好。通过这些组合，您可以在任务开始时混洗数组条目或数据帧，并将受试者分配到刺激集，而无须创建多个事件以读取刺激或数据。

参数：无

• **注意：**选择任务初始化触发器后，您可以使用和引用特定于触发器的任务初始化值通过值选择菜单在各种动作中。

帧初始化触发器

触发条件：

• 帧的初始化，在显示给参与者之前。

该触发器与混洗、读取和绘制随机数操作结合使用时效果很好。通过这些组合，这些操作可以在帧出现之前完成，从而为其他操作开始提供清晰的路径。

**注意：**不要将帧初始化触发器与记录变量的事件或涉及系统变量（例如试验号或条件号）的事件一起使用。这是因为帧初始化触发器发生在试验之间，因此对于即将显示的试验或条件没有完全准确的计数。

参数：无

• **注意：**选择帧初始化触发器后，您可以使用和引用特定于触发器的帧初始化值通过值选择菜单在各种动作中。

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

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

帧开始触发器

触发条件：

• 帧开始

参数：无

• **注意：**选择帧开始触发器后，您可以使用和引用特定于触发器的帧开始值通过值选择菜单在各种动作中。

帧结束触发器

触发条件：

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

参数：无

• **注意：**选择帧结束触发器后，您可以使用和引用特定于触发器的帧结束值通过值选择菜单在各种动作中。

变量值改变触发器

变量值改变

触发条件：

• 变量的值从其起始值改变。

参数：

• 变量：选择一个或多个您想要“监听”的变量。任何这些变量的值发生改变将立即触发相应的动作。

• **注意：**选择变量值改变触发器后，您可以使用和引用特定于触发器的变量值改变值通过值选择菜单在各种动作中。

媒体对象触发器

媒体对象触发器

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

触发条件：

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

参数：

• 目标：选择在帧上存在的对象元素

• 执行操作：选择触发的子类型

  • 音频或视频对象选项：
    • 播放开始：当元素开始播放时触发
    • 播放停止：当元素暂停时触发
    • 播放结束：当元素停止播放时触发
  • 视频、音频或屏幕录制对象选项：
    • 录音完成：当音频录音停止时触发
    • 上传完成：当文件上传完成时触发
  • 文件上传对象选项：
    • 文件选择：当文件被选择时触发
    • 上传完成：当文件上传完成时触发
  • 相机快照对象选项：
    • 快照完成：当相机成功拍摄快照时触发
    • 上传完成：当快照完成上传时触发

• **注意：**选择媒体对象触发器后，您可以使用和引用特定于触发器的媒体对象值通过值选择菜单在各种动作中。

API触发器

如果您需要将数据从外部服务器发送或传输到Labvanced，则可以使用“API触发器”和“API动作”。以下可以用作触发器：

• Websocket触发器
• OpenAI触发器

Websocket触发器

Websocket触发器用于接收来自websocket/API的消息，并将其处理为动作的触发器。

单击此选项后，将显示以下项目。

• **接受/接收自：**自动检测本地主机的IP地址。可以在设置选项卡下手动更改。
• **触发器/消息：**输入将用作触发器的消息。输入“任何”以接受多条消息作为触发器。

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

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

• **注意：**选择Websocket触发器后，您可以使用和引用特定于触发器的Websocket值通过值选择菜单在各种动作中。

OpenAI触发器

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

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

**注意：**请参考此流程，在其中我们一步一步构建一个研究，将ChatGPT集成到研究中并利用此触发器。

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

如果您还使用“发送到OpenAI”动作，则需在此处指明与您在这里指定的相同数据框。

• **注意：**选择OpenAI触发器后，您可以使用和引用特定于触发器的OpenAI值通过值选择菜单在各种动作中。

全局触发器

全局触发器在实验内部发生重大变化时触发，例如，暂停实验或参与者离开多人研究！以下选项被列为全局触发器：

• 暂停/恢复实验
• 参与者离开多人研究

暂停/恢复实验

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

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

• **实验暂停：**参与者暂停（退出全屏）研究。

• **实验继续：**参与者恢复研究。此触发器在眼动追踪研究中效果很好。如果参与者离开虚拟下巴支撑，可以将其送回之前的试验或帧。

• **注意：**选择暂停/恢复实验触发器后，您可以使用和引用特定于触发器的值通过值选择菜单在各种动作中。

参与者离开多人研究

如果参与者离开多人研究，也可以作为事件的触发器。如果参与者离开多人研究，这将对实验产生全局影响，因其阻止其他参与者继续研究。

选择此触发器后，您可以指定如果参与者离开多人研究时将发生什么样的动作。

• **注意：**选择参与者离开多人研究触发器后，您可以使用和引用特定于触发器的值通过值选择菜单在各种动作中。

动作

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

下面的表格提供了Labvanced中可用动作的介绍性概述：

动作类别	动作选项	描述
对象动作	设置对象属性 控制媒体对象 复制对象 对每个对象	对象动作指针对存在于任务内的对象所做的任何操作。
变量动作	设置/记录变量 复制到剪贴板 绘制随机数 获取URL参数 从设备读取/写入 从/写入共享变量 数学和统计 瞬时记录变量 移动平均滤波器 分发变量	任何从变量中读取或记录变量值的动作。
数组动作	从数组选择（读取） 添加/移除数组条目 更改数组条目（替换） 数组条目混洗	数组操作涉及选择、添加、移除、更改和混洗数组及其条目。
数据框操作	从/写入数据框 混洗数据框条目	这些动作在您在实验中使用.csv文件（数据框）时相关。
跳转动作	跳转到 接受/结束会话 拒绝/结束会话 重定向到URL	允许通过跳转到特定部分来导航实验，以及接受和拒绝参与者部分。
控制动作	需求动作（如果…那么） 重复动作（while循环） 延迟动作（时间回调） 动作组	控制动作用于执行特定的事件序列，比如if/then逻辑、循环（如播放重复的声音或闪烁图像），以及设置延迟以确定何时执行动作。
API动作	发送到Websocket 发送到OpenAI	指API特定的发送数据到API的动作。
代码动作	运行JavaScript 设置全局CSS	代码动作允许您使用JavaScript或CSS。
粘贴动作	粘贴动作	允许您粘贴您以前复制的动作。
对象操作是指在任务中对存在的对象进行的任何操作。 有几种对象操作选项：

• 设置对象属性
• 控制媒体对象
• 复制对象
• 对每个对象执行操作

设置对象属性操作

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

了解更多

控制媒体对象操作

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

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

参数：

• 目标：选择一个媒体对象
• 效果：选择一个子操作
  • 音频或视频对象选项：
    • 开始播放：开始播放视频/音频文件
    • 停止播放：停止视频/音频文件
    • 暂停播放：暂停视频/音频文件
    • JumpToTime：允许您指定在音频/视频文件中跳转的毫秒时间
    • 静音：关闭对象的声音
    • 取消静音：恢复对象的声音
  • 音频、视频或屏幕录制对象选项：
    • 开始录制：开始新的（音频）录制
    • 停止录制：停止（音频）录制
    • 开始上传：开始上传文件
    • 清除录制：删除（音频）录制数据。
    • 开始播放：开始播放录制的文件
    • 停止播放：停止播放录制的文件
    • 暂停录制：暂停对象的录制
    • 继续录制：继续对象的录制
  • 文件上传对象选项：
    • 开始上传：开始所选文件的上传过程
    • 清除文件：删除所选文件
    • 选择文件：允许参与者选择所需的文件
  • 相机快照对象选项：
    • 开始相机：打开参与者的相机
    • 停止相机：关闭参与者的相机
    • 开始上传：开始将快照上传到实验中
    • 拍摄快照：使用参与者的相机拍照

复制对象操作

效果：复制一个对象，替代多个单独的对象和重复事件的需要。

参数：

• 源：选择要复制的框架中的对象。
• 复制数量：输入要制作的源对象的复制数量。
• 设置新元素名称：从几个参数中选择以确定副本的名称。
• 用递增后缀分配名称：在新元素名称的末尾添加一个数字标签以区分副本。
• 动作序列：允许您选择（从通常的动作列表中）将对所有副本应用的操作。选择“CurrentObject”作为目标以对所有副本应用此操作。

对每个对象操作

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

参数：

• 过滤器：选择要目标的元素类型。
• 允许额外名称过滤器：输入要目标的对象名称。对于框架中的多个对象且某些对象名称相同，这非常有效。
• 动作序列：允许您选择（从通常的动作列表中）将对所选元素应用的操作。选择“CurrentObject”作为目标以对满足上述指定条件的所有元素应用此操作。

变量操作

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

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

变量操作选项	描述
设置/记录变量	写入或设置变量值
复制到剪贴板	将变量值复制到计算机的内部剪贴板。
随机抽取数字	抽取一个或多个随机数并将其保存到变量中
获取URL参数	从参与者的唯一URL中保存一个值
从设备读取/写入	从本地设备的存储中读取或写入变量。此操作将数据保存到参与者的设备，而不是发送到Labvanced服务器。
从/写入共享变量	从会话之间共享的变量中读取或写入。变量可以与所有参与者共享或专属于每个参与者。
数学与统计	对某个输入变量（数组）执行数学操作并将结果保存到输出变量中。
即时记录变量	创建所有变量值的快照并将其发送到Labvanced服务器。
移动平均滤波器	计算某个输入的移动平均（数据的持续更新平均值），并将结果存储到新变量中。
分配变量	将值发送给其他参与者。该值存储在一个变量中。

设置/记录变量操作

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

点击此操作后，将出现以下对话框，您可以在其中指定应记录的变量和感兴趣的值：

菜单项	菜单区域	描述
选择		点击选择后，您指明哪个变量应存储值。在此，您还可以创建一个新变量。
笔图标		笔图标象征着值选择菜单，用于定义和指定应分配给所选变量的确切值（如等号（=）左侧的绿色按钮所示）。

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

下图记录鼠标X，Y坐标，以捕捉研究期间的鼠标跟踪。下图显示了如何使用三种操作使变量值记录成为可能。左侧的变量是手动创建的，而等号（=）右侧的值是系统提供的鼠标触发特定值，您可以在记录值时引用它。

注意： “设置/记录变量”操作也常用于控制操作的上下文中，在这种情况下，可以基于变量值指定条件，使用‘如果/那么’和‘循环’。

复制到剪贴板操作

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

随机抽取数字操作

效果：抽取一个或多个随机数并将其保存到变量中。

参数：

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

获取URL参数操作

效果：从参与者的唯一URL中保存一个值。

参数：

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

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

从设备读取/写入操作

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

参数：

• 选择从本地设备读取或写入。
• 选择要读取或写入的变量。

用例：纵向/多会话研究

• 使用此操作，可以在会话之间携带设备特定数据，前提是同一参与者在每个会话中使用相同的设备。
• 例如，您可以使用此操作记录在会话1中向每个参与者展示了哪些图像，并确保在会话2中向他们展示不同的图像。
  • 创建一个图像数组并随机选取一些在每个会话中展示。
  • 写入设备：在会话1中呈现的图像的索引号。
  • 从设备读取：在会话2中读取会话1中的图像索引，并包括一个JavaScript操作，以防止这些索引在第二次会话中被选中。

从/写入共享变量操作

效果：从研究的会话之间共享的变量中读取或写入。变量可以与所有参与者共享或专属每个参与者。

参数：

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

用例：纵向/多会话研究

• 使用此操作，可以在会话之间携带特定参与者的数据，并在会话之间共享。
• 例如，您可以使用此操作记录测试得分，然后允许参与者将其分数与完成测试的其他参与者的平均得分进行比较。
• 另一个类似的例子（类似于从设备读取/写入操作）是让参与者从数组中挑选5张他们喜欢的图像，执行一项任务，然后在以后的会话中再展示这5张图像。不同之处在于，此操作可用于向其他参与者展示所选图像，或从另一个参与者的可用选项中排除这些图像。

数学与统计操作

效果：对某个输入变量（数组）执行数学操作并将结果保存到输出变量中。

参数：

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

即时记录变量操作

效果：创建所有变量值的快照并将其发送到Labvanced服务器。

参数：无

移动平均滤波器操作

效果：计算某个输入的移动平均（数据的持续更新平均值），并将结果存储到新变量中。

参数：

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

分配变量操作

分配变量操作对于Labvanced中的多用户研究非常重要。 使用此操作，变量值可以在参与者之间共享，基本上允许信息（包括刺激位置和任何更改）在参与者的屏幕上反映。

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

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

请查看这个演示，其中结合了分配变量和聊天框功能：带聊天附加的图像描述任务。

以下是对话菜单项的完整说明：

菜单项	菜单区域	分配变量操作选项和描述
分配值到		选择将值发送到的其他参与者。 **所有参与者：**将此值发送给所有参与者 **选定参与者：**将值发送给选定参与者。
选择目标变量和值		**目标变量：**选择要存储值的目标变量。 **值：**确定应发送给其他参与者的值。
阻止		如果启用，目标变量在当前值分配完成之前不能更改。
速率限制策略		速率限制策略是一种保护您的实验，防止服务器过载的方法，并作为控制请求发送速率（即通过分配变量的更新）的一种预防策略。以下策略选项可用： **去抖动：**当此操作在100毫秒时间窗口内执行超过一次时，则新的服务器消息将被“去抖动”（仅在未执行此操作的间隔为100毫秒后发送最近的消息）。 **节流：**当此操作在100毫秒时间窗口内执行超过一次时，则新消息将被节流（即，在上一次消息发送后的100毫秒过去后，仅分配最近的消息）。 **丢弃：**当此操作在100毫秒时间窗口内执行超过一次时，则该100毫秒窗口内的新消息将被丢弃。 **排队：**当此操作在100毫秒时间窗口内执行超过一次时，则新的变量值将被排队（最多排队10条消息）。

数组操作

从数组选择（读取）操作

效果：将从数组中读取一个变量，并将此值存储在标量变量中。

参数：

• 数组变量：输入数组用于读取值。
• 索引类型：确定使用何种类型的索引。
  • 固定：使用固定索引进行读取操作。在此情况下，输入应读取信息的位置（基于1）。
  • 变量：使用数值变量作为读取操作的索引。在此情况下，选择一个标量数值变量以确定读取的位置。
  • 数组末端：从数组末端读取。
• 输出变量：选择一个标量变量以存储读取的值。

添加/删除数组条目操作

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

参数：

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

更改（替换）数组条目操作

效果：将替换/更改数组中的一个值。

参数：

• 数组变量：应修改一个值的数组变量。
• 索引类型：确定使用何种类型的索引。
  • 固定：使用固定索引进行替换操作。在此情况下，输入应更改的数组位置（基于1）。
  • 变量：使用数值变量作为替换操作的索引。在此情况下，选择一个标量数值变量以确定替换操作的位置。
  • 数组末端：替换数组中的最后一个条目。
• 输入变量：选择一个（标量）变量以存储新值。

随机打乱数组条目操作

效果：将重新打乱数组中的条目/顺序。

参数：无

数据框操作

从/写入数据框操作

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

参数：

• 数据框变量：选择要读取的数据框的变量。
• 读取或写入：选择从所选数据框读取或写入所选数据框。
• 按行或列：选择数据应如何读取。
• 索引类型：选择将用于读取数据框的索引变量类型。可以是固定、变量或最后一行。
• 索引变量：选择将用作索引以读取数据框的变量。
• 输出变量：选择一个变量以存储读取/写入的数据作为输出。必须是数组变量。

随机打乱数据框条目操作

效果：打乱数据框中条目的顺序。

参数：

• 选择要打乱的数据框。
• 选择数据框是按行还是按列打乱。

跳转操作

跳转到操作

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

参数：

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

接受/结束会话操作

效果：接受参与者的数据，结束记录会话，并显示众包代码。

参数：

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

拒绝/结束会话操作

效果：结束记录会话，不标记参与者的数据为完成，也不显示带有补偿代码的默认结束屏幕。

使用此操作拒绝参与者的数据时，用户应向参与者显示适当的消息，解释他们将不因参与时间获得奖励的原因。

参数：无

重定向到URL操作

效果：将参与者重定向到特定URL。

注意：URL必须以https://开头，以便此操作有效。

控制操作

需求操作（如果...那么...否则如果）操作

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

参数：

• 添加需求：向语句添加新需求。两侧将出现“值选择”菜单以进行逻辑比较。在语句中间，您可以选择如何比较两侧（例如，等于、小于、不等于等）。
• 添加或组：在或组中的所有需求只需一个为真，则整个组即为真。如果需要以多种情况执行子操作，请添加或组。
• 添加和组：在和组中的所有需求都必须为真，则整个组即为真。如果仅当满足多个需求时才执行子操作，请添加和组。
• 动作序列：每个如果/否则如果语句都有一系列在“则”下定义的操作。动作序列列出了特定如果/否则如果语句的所有操作。可以通过“添加操作”图标添加新操作。仅当关联的如果/否则如果语句的要求满足时，将执行动作序列。
• 添加else-if情况：需求操作可以由多个单独的如果/else-if --> 则语句组成。但是，只能执行一个语句。如果一个如果/else-if语句评估为正（返回真），则将在“则”块中执行操作，其他需求操作将被跳过。
• 添加否则情况（真/假）：如果启用，默认/回退选项将添加到需求操作。如果没有执行任何如果/else-if语句（返回真），则将执行在else情况下定义的操作。

重复操作（循环）操作

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

参数：

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

延迟操作（时间回调）操作

效果：在特定时间延迟后执行一系列操作。

参数：

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

动作组

操作还可以组织成动作组。 动作组允许您将某些操作组合在一起，以便更容易的视觉结构，以及在您想要一次复制、重复或删除多个操作时。

了解更多

API 操作

如果您需要将数据从外部服务器发送或通信到Labvanced，则可以使用“API操作”和“API触发器”。在此类别下可用以下操作：

• 发送到Websocket
• 发送到OpenAI

为了使这些操作“可用”或可用，您必须在设置选项卡中输入API密钥。

发送到Websocket操作

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

上述示例和完整事件结构可以在这里访问：https://www.labvanced.com/page/library/51053，点击‘检查’。

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

发送到OpenAI操作

“发送到OpenAI”操作允许您将信息（例如字符串输入值）发送给OpenAI。请注意，要使用此选项，您必须在设置选项卡中的特殊功能下列出您的API密钥。

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

以下是提供所有必要信息时该事件的功能示例：

要详细了解如何利用此功能并查看其运作示例，欢迎随时通过提交此联系表单与我们联系以获取演示。

注意： 还请参阅此指南，我们将逐步构建一个研究，将ChatGPT集成到研究中并利用此操作。

以下是“发送到OpenAI”操作中包含字段的更详细解释：

菜单项	菜单区域	“发送到OpenAI”操作选项
模型类型		指定将使用的AI模型。
聊天历史数据框		链接到具有两列的数据框变量。第一列将表示“角色”，第二列表示“聊天消息”。操作中的值将自动附加到此处链接的数据框中。 数据框也可以通过数据框操作进行操作。有关更多参考，请查看OpenAI的文档。
插入消息‘+’		单击此项后，将出现变量对话框。您需要指明要发送到OpenAI的“变量”值以及关联消息的“角色”： **系统：**指的是高级ChatGPT系统 **用户：**参与者 **助手：**指的是系统中创建的特定子角色

随着OpenAI的不断发展，请查看OpenAI的文档以获取进一步阐明。

代码操作

在某些情况下，您的实验可能需要使用自定义代码。通过这些操作，您可以实现这一点！ “代码操作”菜单下可用以下选项：

• 运行JavaScript
• 设置全局CSS

运行JavaScript操作

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

选择上述“运行JavaScript”操作时，您将看到一个输入区域（代码编辑器），在此可以撰写JavaScript代码，以及如何使用它的说明：

设置全局CSS操作

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

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

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

粘贴操作

此选项允许您粘贴之前创建和复制的操作。它使您在设计实验时更快，以便您不必反复选择相同的项目。例如，如果您有一个事件与已存在的相似，您可以简单地复制它，粘贴并修改，而无需从头开始构建。

值选择菜单

在处理某些事件时，您会注意到出现一个钢笔图标。这被称为值选择菜单，因为它允许您选择和指示要记录或跟踪什么样的值。这是一个非常强大和重要的选项，您必定会在实验设计和设置中使用。

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

点击钢笔图标会弹出一个下拉菜单，您可以指定要读取或写入的值。 下拉菜单总是以列出特定触发器的值选项开头，然后继续到其他5个类别（当前时间、常量值、变量、框架/任务/选项和操作），所有这些都有自己的选项。 这些将在下面进一步描述。

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

菜单选项

下面的表进一步解释了类别和选项：

当前时间值

使用“当前时间”选项，您可以记录或引用与时间相关的值。

以下选项可用：

• UNIX时间戳
• 从帧开始的时间

当前时间：UNIX时间戳

该值以毫秒捕获UNIX格式的时间戳。

当前时间：从帧开始的时间

该值捕获从帧开始经过的时间。通常这相当于反应时间。

常量值

根据您需要的变量类型（如字符串或数字）分配常量值。这些有时与其他选项组合使用，例如算术以创建计数器。

以下选项可用：

• 字符串
• 数字
• 布尔值
• 类别
• 日期
• 时间
• 颜色

常量：字符串

分配字符串/文本值。

常量：数字

分配数字/数值。

常量：布尔值

分配一个真或假的值。

常量：类别

分配一个等级值（主要用于因子）。

常量：日期

分配日期值。

常量：时间

分配时间值。

常量：颜色

分配颜色（十六进制字符串）值。

变量值

指定或引用一个变量，或从数组或数据框中选择一个值。以下选项可用：

• 选择变量
• 从数组中选择值
• 从数据框中选择值

选择变量

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

从数组中选择值

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

从数据框中选择值

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

框架/任务/对象值

允许您获取与对象属性、框架、眼动追踪（如果已激活）和设备（屏幕刷新率）相关联的值。

• 对象属性
• 框架
• 眼动追踪
• 设备

对象属性

读取一个对象属性。

框架

眼动追踪

设备

• 刷新率： 参与者设备的刷新率值。

操作

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

以下选项可用：

• 算术
• 字符串操作
• 数学操作

算术

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

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

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

这些值可以通过使用这5种不同的操作进行处理：

• (+) 加法
• (-) 减法
• (/) 除法
• (*) 乘法
• (%) 取模

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

新的变量值（'intermediateVar'）是通过将多个算术操作与之前创建的变量（即'userChatName'和'chatInput'）组合，以及常量字符串值，即分号:和换行符<br>来定义的。这个操作创建了一个可以在多用户研究中使用的用户聊天效果。

字符串操作

数学操作

对标量值执行数学操作。

触发器特定值

触发器特定值指的是与特定事件中定义的触发器相关联的值。例如，如果您的事件使用鼠标触发器，那么在某些指定操作的区域（例如使用设置/记录变量操作或设置对象属性操作时），您可以在值选择菜单中引用鼠标触发器特定值。

在下面的示例中，使用鼠标触发器的触发器特定值用于记录x和y值以及[XY]数组，使用设置/记录变量操作。

下面是Labvanced中可以找到的所有类型的触发器特定值的表格，后面是每个选项的详细解释。

名称	值选项 - 概述
触发器（鼠标）	鼠标X 鼠标Y 鼠标[X,Y]数组 刺激名称 刺激信息 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（键盘）	键的ID 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（按钮栏）	刺激名称 刺激信息 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（输入时按下回车）	键的ID 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（滚动）	刺激名称 刺激信息 滚动位置X 滚动位置Y 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（游戏手柄/操纵杆）	游戏手柄设备ID 按下的按键（数组） 按下或按住的按键（数组） 释放的按键（数组） 轴（数组） 游戏手柄时间戳（Unix时间） 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（眼动追踪凝视）	坐标X 坐标Y 坐标[X,Y]数组 刺激名称 刺激信息 摄像机捕获时间T 凝视置信度C 带时间的坐标[X,Y, T]数组 带时间和置信度的坐标[X,Y, T,C]数组 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（眼动追踪注视）	注视质心X 注视质心Y 注视持续时间 注视开始时间 注视结束时间 注视分散 刺激名称 刺激信息 [X,Y, Dur, Start, End, Disp] 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（头部追踪）	摄像机捕获时间T 头部转动 头部倾斜 头部滚动 头部位置[X,Y, T]数组 鼻子位置[X,Y, T]数组 鼻子向量[X,Y, Z, T]数组 触发时间戳（Unix时间） 从帧开始的触发时间
触发器（任务初始化时）	触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（帧初始化时）	试验编号 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（帧开始时）	触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（帧结束时）	总帧时间 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（变量值已改变）	变量的新值 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（媒体对象触发）	触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（Websocket触发）	消息 数据 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（OpenAI触发）	Chat GPT答案 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（全局实验事件）	总帧时间 全局事件的原因 触发时间戳（Unix时间） 触发时间（从帧开始）
触发器（用户离开实验）	剩余的参与者人数 触发时间戳（Unix时间） 触发时间（从帧开始）

触发器（鼠标）值

当使用鼠标触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（键盘）值

当使用键盘触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（按钮栏）值

当使用按钮点击触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（输入时按下回车）值

当使用输入时回车触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（滚动）值

当使用滚动触发器时，以下触发器特定值可在处理某些操作时调用：

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

当使用游戏手柄/操纵杆触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（眼动追踪凝视）值

当使用眼动追踪凝视触发器时，以下触发器特定值可在处理某些操作时调用：

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

当使用眼动追踪注视触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（头部追踪）值

当使用头部追踪触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（任务初始化时）值

当使用任务初始化触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（帧初始化时）值

当使用帧初始化触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（帧开始时）值

当使用帧开始触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（帧结束时）值

当使用帧结束触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（变量值已改变）值

当使用变量值改变触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（媒体对象触发）值

当使用媒体对象触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（Websocket触发）值

当使用Websocket触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（OpenAI触发）值

当使用OpenAI触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（全局实验事件）值

当使用暂停/恢复实验触发器时，以下触发器特定值可在处理某些操作时调用：

触发器（用户离开实验）值

当使用参与者离开多用户研究触发器时，以下触发器特定值可在处理某些操作时调用：