Companion模块开发：预设按钮中的延时动作组配置指南

概述

在Companion模块开发过程中，预设按钮(Preset)的配置是一个重要功能。本文将深入介绍如何在模块代码中为预设按钮配置延时动作组(Duration Groups)，这种高级功能允许开发者定义按钮在不同按压时长下触发的不同动作序列。

延时动作组的基本概念

延时动作组是Companion提供的一项强大功能，它允许用户通过长按按钮触发不同的动作。在UI界面中，用户可以直观地设置这些延时动作，但在模块开发中需要通过特定的代码结构来实现。

代码实现方式

在模块的预设定义中，可以通过steps数组中的特殊属性来配置延时动作：

1. 基本延时触发： 在steps数组中，除了常见的down和up属性外，可以使用毫秒数值作为键名来定义延时动作：

steps: [
    {
        down: [
            // 按下时立即执行的动作
            {
                actionId: 'immediate-action',
                options: { param1: 'value1' }
            }
        ],
        up: [], // 松开按钮时的动作
        2000: [ // 长按2秒后触发的动作
            {
                actionId: 'delayed-action',
                options: { param2: 'value2' }
            }
        ]
    }
]

2. 持续执行动作： 对于需要持续执行的动作，可以设置runWhileHeld选项：

steps: [
    {
        down: [
            // 立即执行的动作
        ],
        up: [],
        2000: {
            options: { runWhileHeld: true }, // 设置持续执行
            action: [
                {
                    actionId: 'continuous-action',
                    options: { param3: 'value3' }
                }
            ]
        }
    }
]

实际应用场景

这种功能特别适用于需要区分短按和长按的场景，例如：

• PTZ摄像机控制：短按调用预设，长按覆盖当前预设
• 灯光控制：短按开关灯，长按调光
• 媒体控制：短按播放/暂停，长按停止

开发建议

1. 明确的延时时间：为每个延时动作设置合理的延时阈值，通常2000毫秒(2秒)是一个常用值
2. 用户反馈：考虑在延时动作触发前提供视觉或听觉反馈
3. 动作冲突处理：确保延时动作不会与即时动作产生冲突
4. 文档说明：在模块文档中明确说明每个按钮的延时功能

总结

通过合理使用延时动作组，开发者可以为用户提供更丰富、更直观的控制体验。这种功能特别适合需要区分不同操作时长的专业控制场景，能够显著提升模块的实用性和用户体验。