按键收集器组件

key_collector 组件从诸如 矩阵键盘、Wiegand 键盘 或 LVGL 按钮矩阵、键盘 等组件的小部件收集按键。它允许你将按键序列作为一个整体来处理，例如 用于输入 PIN 码或密码。该组件将按键序列的结果以变量形式输出， 可在自动化中使用，并可将结果发布到 text_sensor。

组件

# 示例配置条目
key_collector:
  - id: pincode_reader
    source_id: mykeypad
    start_keys: "*"
    min_length: 4
    max_length: 4
    start_keys: "A"
    end_keys: "#"
    end_key_required: true
    back_keys: "*"
    clear_keys: "C"
    allowed_keys: "0123456789"
    timeout: 5s
    on_progress:
      - logger.log:
          format: "input progress: '%s', started by '%c'"
          args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ]
    on_result:
      - logger.log:
          format: "input result: '%s', started by '%c', ended by '%c'"
          args: [ 'x.c_str()', "(start == 0 ? '~' : start)", "(end == 0 ? '~' : end)" ]
    on_timeout:
      - logger.log:
          format: "input timeout: '%s', started by '%c'"
          args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ]

配置变量

• id (可选, ID): 设置此条目的 ID，供在 lambda 中使用。
• source_id (可选, ID): 按键输入设备的 ID。
• min_length (可选, integer): 所需按键序列的最小长度。低于此限制时， 即使按下任何 end_keys 中的键，on_result 自动化也不会触发。
• max_length (可选, integer): 所需按键序列的最大长度。达到此限制 后，收集器将根据 end_key_required 的设置，要么忽略额外的按键，要么触发 on_result 自动化。
• start_keys (可选, string): 用于开始按键序列的键；设置后，在按下其中一个开始键之前， 不会接受任何按键。
• end_keys (可选, string): 用于结束按键序列并触发 on_result 自动化的键。
• end_key_required (可选, boolean): 仅当按下 end_keys 中的某个键时才触发 on_result 自动化，而不在输入达到 max_length 个字符时触发。默认为 false。
• back_keys (可选, string): 用于删除上次按下按键的键。就像键盘上的退格键一样。
• clear_keys (可选, string): 用于取消构建按键序列的键。
• allowed_keys (可选, string): 允许使用的键。如果未指定，则任何其他 未使用的键都将被允许。
• timeout (可选, Time): 之后取消构建 按键序列的超时时间。
• enable_on_boot (可选, boolean): 启用后，此按键收集器将在启动时启用。默认为 true。

必须至少指定 end_keys 或 max_length 之一。其余均为可选。 当按键序列被取消时（因超时或按下了某个 clear_keys），也必须重新按下 start_keys（如果配置了）中的某个键。

触发器

• on_progress (可选, Automation): 当按下按键时执行的自动化。 当前按键序列存放在一个 vector<uint8_t> 变量 x 中， start 保存启动此按键序列的开始键，否则为 0。 如果你想让显示屏显示当前值或按键次数， 或者在按键按下时让扬声器发出提示音，这会很有用。

• on_result (可选, Automation): 当按键序列完成时执行的自动化 （例如已达到 max_length 或按下了某个 end_keys 中的键）。最终确定的按键序列存放在一个 vector<uint8_t> 变量 x 中，start 保存启动此按键序列的开始键或 0，而 end 保存终止此按键序列的结束键或 0。

• on_timeout (可选, Automation): 如果发生超时则执行的自动化。 当前按键序列存放在一个 vector<uint8_t> 变量 x 中， start 保存启动此按键序列的开始键，否则为 0。

操作

key_collector.enable 操作

此操作启用一个 key_collector。它将开始接受按键。 如果存在多个按键收集器，你需要提供要启用的那个收集器的 id。

on_...:
  then:
    - key_collector.enable:

key_collector.disable 操作

此操作停用一个 key_collector。它将停止接受按键并清除任何已收集的按键。 如果存在多个按键收集器，你需要提供要停用的那个收集器的 id。

on_...:
  then:
    - key_collector.disable:

Lambdas

• clear(bool progress_update=true): 取消构建按键序列。将 progress_update 设为 false 可跳过触发 on_progress 自动化。
• send_key(uint8_t key): 直接将一个按键发送给收集器。

文本传感器

key_collector 组件支持一个 文本传感器， 当产生成功的结果时，它会发布收集到的按键序列。

另请参阅

• 按键收集器文本传感器
• 矩阵键盘
• Wiegand 键盘和标签读取器
• LVGL 按钮矩阵小部件
• LVGL 键盘小部件
• API 参考：key_collector.h