显示菜单

该组件提供菜单，主要通过带按钮的旋转编码器或五键摇杆控制器进行控制。它允许在条目和子菜单的层次结构中导航，并能够更改值和执行命令。菜单可以按需激活和停用，从而可以在使用屏幕显示菜单和其他信息之间切换。

本文档描述了实现该组件的各个组件共用的配置和自动化。目前支持基于字符的 LCD 显示屏，使用 lcd_menu 组件，配置示例中就使用了该组件的实例。

# Example configuration entry
display:
  - platform: lcd_pcf8574
    id: my_lcd
    ...
    lambda: |-
      id(my_lcd_menu).draw();
      if (!id(my_lcd_menu).is_active())
        it.print("Menu is not active");

# Declare a LCD menu
lcd_menu:
  id: my_lcd_menu
  display_id: my_lcd
  active: true
  mode: rotary
  on_enter:
    then:
      lambda: 'ESP_LOGI("display_menu", "root enter");'
  on_leave:
    then:
      lambda: 'ESP_LOGI("display_menu", "root leave");'
  items:
    - type: back
      text: 'Back'
    - type: label
      text: 'Label 1'
    - type: label
      text: !lambda |-
        return "Templated label";

# Encoder to provide navigation
sensor:
  - platform: rotary_encoder
    ...
    on_anticlockwise:
      - display_menu.up:
    on_clockwise:
      - display_menu.down:

# A de-bounced GPIO is used to 'click'
binary_sensor:
  - platform: gpio
    ...
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms
    on_press:
      - display_menu.enter:

配置变量：

root_item_id (可选, ID): 手动指定根菜单项的 ID。
active (可选, boolean): 菜单是否应作为活动状态启动，即接受用户交互并显示输出。默认为 true。
mode (可选, enum): 定义导航逻辑。默认为 rotary。
- rotary : 旋转模式期望顺时针移动连接到 display_menu.down，逆时针连接到 display_menu.up，开关连接到 display_menu.enter 操作。
- joystick : 摇杆模式期望上、下、左、右按钮分别连接到 display_menu.up、 display_menu.down、display_menu.left 和 display_menu.right 操作，中间按钮连接到 display_menu.enter 操作。
items (必填): 菜单的第一层。

自动化：

on_enter (可选, Automation): 当进入菜单层级（此处为根层级）时执行的自动化。请参阅 on_enter。
on_leave (可选, Automation): 当不再显示菜单层级时执行的自动化。请参阅 on_leave。

菜单项

该组件管理菜单项的层次结构。常用的配置变量有：

id (可选, ID): 手动指定用于代码生成的 ID。
type (必填, string): 菜单项的类型（见下文）。
text (可选, string, templatable): 显示的菜单项文本。如果指定了 lambda，它会获得一个指向正在绘制的 MenuItem 的 it 参数。

编辑值

一些菜单项提供了通过从选项列表中选取或更改数值来编辑值的方法。此类项可以两种方式配置。

如果 immediate_edit 配置为 false，则必须首先通过激活旋转编码器的开关或摇杆的中心按钮来激活编辑模式。激活时调用 on_enter 自动化，并将该项标记为可编辑（> 选择标记默认变为 *）。然后可以通过旋转编码器滚轮（在 rotary 模式下）或摇杆的左右按钮（在 joystick 模式下）遍历值。再次点击开关将停用编辑模式，调用 on_leave 自动化，选择标记恢复。

如果 immediate_edit 配置为 true，菜单项在被选中时可立即编辑。on_enter 和 on_leave 不会被调用。在 joystick 模式下左右按钮遍历值；可编辑的项显示可编辑标记，以指示可以使用这些按钮。在 rotary 模式下激活开关将遍历到下一个值。选择标记不变（此处用于指示旋转旋钮是导航菜单还是更改值）。number 类型的菜单项只能在 joystick 模式下进行即时编辑。

菜单

items:
  - type: menu
    text: 'My Submenu'
    on_enter:
      then:
        lambda: 'ESP_LOGI("display_menu", "enter: %s", it->get_text().c_str());'
    on_leave:
      then:
        lambda: 'ESP_LOGI("display_menu", "leave: %s", it->get_text().c_str());'
    items:
      - type: label
        text: 'Label'
      - type: back
        text: 'Back'

menu 类型的菜单项定义子菜单项列表。当该项被点击时，显示屏显示新的菜单层级。

配置变量：

items (必填): 定义子菜单项。

自动化：

on_enter (可选, Automation): 进入菜单层级时执行的自动化。请参阅 on_enter。
on_leave (可选, Automation): 不再显示菜单层级时执行的自动化。请参阅 on_leave。

items:
  - type: back
    text: 'Back'

back 类型的菜单项关闭当前菜单层级并向上移动到菜单层级层次结构。当前层级的 on_leave 自动化和更高层级的 on_enter 自动化将被调用。没有配置。

选择

lcd_menu:
  items:
    - type: select
      immediate_edit: false
      text: 'My Color'
      select: my_color
      on_enter:
        then:
          lambda: 'ESP_LOGI("display_menu", "select enter: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
      on_leave:
        then:
          lambda: 'ESP_LOGI("display_menu", "select leave: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
      on_value:
        then:
          lambda: 'ESP_LOGI("display_menu", "select value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'

select:
  - platform: template
    id: my_color
    optimistic: true
    options:
      - 'Red'
      - 'Green'
      - 'Blue'

select 类型的菜单项允许在由关联的 select 组件定义的一组值中循环。

配置变量：

immediate_edit (可选, boolean): 该项被选中时是否可立即编辑。请参阅编辑值。默认为 false。
select (必填, ID): 管理编辑值的 select 组件。
value_lambda (可选, lambda): 返回要显示为值的字符串的 Lambda。lambda 获得一个指向 MenuItem 的 it 参数。如果未指定，则使用 select 组件选中的选项名称作为值。

自动化：

on_enter (可选, Automation): 激活编辑模式时执行的自动化。请参阅 on_enter。
on_leave (可选, Automation): 退出编辑模式时执行的自动化。请参阅 on_leave。
on_value (可选, Automation): 值更改时执行的自动化。请参阅 on_value。

数字

lcd_menu:
  items:
    - type: number
      text: 'My Number'
      format: '%.2f'
      number: my_number
      on_enter:
        then:
          lambda: 'ESP_LOGI("display_menu", "number enter: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
      on_leave:
        then:
          lambda: 'ESP_LOGI("display_menu", "number leave: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
      on_value:
        then:
          lambda: 'ESP_LOGI("display_menu", "number value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'

number:
  - platform: template
    id: my_number
    optimistic: true
    min_value: 10.0
    max_value: 20.0
    step: 0.5
    on_value:
      then:
        lambda: 'ESP_LOGI("number", "value: %f", x);'

number 类型的菜单项允许编辑浮点数。点击时调用 on_enter 自动化，并将该项标记为可编辑（> 选择标记默认变为 *）。然后上下事件以 number 中定义的步长增加和减少值，同时尊重 min_value 和 max_value。再次点击退出编辑模式。

注意，小数的浮点值不一定相加得整齐，十倍的 0.100000 不一定等于 1.000000。使用 2 的幂次方（如 0.125 ）作为步长，或显式处理四舍五入。

配置变量：

immediate_edit (可选, boolean): 该项被选中时是否可立即编辑。请参阅编辑值。在 rotary 模式下被忽略。默认为 false。
number (必填, ID): 管理编辑值的 number 组件。如果进入时值小于 min_value 或大于 max_value，则值将被限制在该范围内。
format (可选, string): 类似于 printf 的格式字符串，指定用于显示当前值的确切一个 f 或 g 类型转换。默认为 %.1f。
value_lambda (可选, lambda): 返回要显示为值的字符串的 Lambda。lambda 获得一个指向 MenuItem 的 it 参数。如果未指定，则使用根据 format 格式化后的 number 组件值作为值。

自动化：

on_enter (可选, Automation): 激活编辑模式时执行的自动化。请参阅 on_enter。
on_leave (可选, Automation): 退出编辑模式时执行的自动化。请参阅 on_leave。
on_value (可选, Automation): 值更改时执行的自动化。请参阅 on_value。

开关

lcd_menu:
  items:
    - type: switch
      immediate_edit: false
      text: 'My Switch'
      on_text: 'Bright'
      off_text: 'Dark'
      switch: my_switch
      on_enter:
        then:
          lambda: 'ESP_LOGI("display_menu", "switch enter: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
      on_leave:
        then:
          lambda: 'ESP_LOGI("display_menu", "switch leave: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'
      on_value:
        then:
          lambda: 'ESP_LOGI("display_menu", "switch value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'

switch:
  - platform: template
    id: my_switch
    optimistic: true

switch 类型的菜单项允许切换关联的 switch 组件。

配置变量：

immediate_edit (可选, boolean): 该项被选中时是否可立即编辑。请参阅编辑值。默认为 false。
on_text (可选, string): ON 状态的文本。默认为 On。
off_text (可选, string): OFF 状态的文本。默认为 Off。
switch (必填, ID): 管理编辑值的 switch 组件。
value_lambda (可选, lambda): 返回要显示为值的字符串的 Lambda。lambda 获得一个指向 MenuItem 的 it 参数。如果未指定，则使用 on_text / off_text。

自动化：

on_enter (可选, Automation): 激活编辑模式时执行的自动化。请参阅 on_enter。
on_leave (可选, Automation): 退出编辑模式时执行的自动化。请参阅 on_leave。
on_value (可选, Automation): 值更改时执行的自动化。请参阅 on_value。

命令

items:
  - type: command
    text: 'Hide'
    on_value:
      then:
        - display_menu.hide:

command 类型的菜单项允许触发命令。没有额外配置。

自动化：

on_value (可选, Automation): 菜单项被点击时执行的自动化。请参阅 on_value。

自定义

lcd_menu:
  items:
    - type: custom
      immediate_edit: false
      text: 'My Custom'
      value_lambda: 'return to_string(some_state);'
      on_next:
        then:
          lambda: 'some_state++;'
      on_prev:
        then:
          lambda: 'some_state--;'

custom 类型的菜单项将值导航委托给自动化，将值显示委托给 value_lambda。

配置变量：

immediate_edit (可选, boolean): 该项被选中时是否可立即编辑。请参阅编辑值。默认为 false。
value_lambda (可选, lambda): 返回要显示为值的字符串的 Lambda。lambda 获得一个指向 MenuItem 的 it 参数。

自动化：

on_enter (可选, Automation): 激活编辑模式时执行的自动化。请参阅 on_enter。
on_leave (可选, Automation): 退出编辑模式时执行的自动化。请参阅 on_leave。
on_value (可选, Automation): 值更改时执行的自动化。请参阅 on_value。
on_next (可选, Automation): 用户导航到下一个值时执行的自动化。请参阅 on_next。
on_prev (可选, Automation): 用户导航到上一个值时执行的自动化。请参阅 on_prev。

自动化

`on_enter`

当进入菜单层级时，即组件在显示屏上绘制其项时，将触发此自动化。it 参数指向 MenuItem 类，包含描述所显示子项的菜单项信息。如果位于顶层，它是一个内部生成的根菜单项，否则是用户定义的项。

lcd_menu:
  ...
  items:
    - type: menu
      text: 'Submenu 1'
      on_enter:
        then:
          lambda: 'ESP_LOGI("display_menu", "enter: %s", it->get_text().c_str());'

`on_leave`

当退出菜单层级时，即组件不再在显示屏上绘制其项时，将触发此自动化。it 参数指向包含菜单项信息的 MenuItem 类。如果位于顶层，它是一个内部生成的根菜单项，否则是用户定义的项。无论是因为进入子菜单还是返回上级菜单而离开层级都无关紧要。

lcd_menu:
  ...
  items:
    - type: menu
      text: 'Submenu 1'
      on_leave:
        then:
          lambda: 'ESP_LOGI("display_menu", "leave: %s", it->get_text().c_str());'

`on_value`

当通过菜单编辑的值发生更改或触发了命令时，将触发此自动化。

lcd_menu:
  ...
  items:
    - type: select
      text: 'Select Item'
      select: my_select_1
      on_value:
        then:
          lambda: 'ESP_LOGI("display_menu", "select value: %s, %s", it->get_text().c_str(), it->get_value_text().c_str());'

`on_next`

当用户请求将值设置为下一个值时，将触发此自动化。

lcd_menu:
  ...
  items:
    - type: custom
      text: 'Custom Item'
      value_lambda: 'return to_string(some_state);'
      on_next:
        then:
          lambda: 'some_state++;'

`on_prev`

当用户请求将值设置为上一个值时，将触发此自动化。

lcd_menu:
  ...
  items:
    - type: custom
      text: 'Custom Item'
      value_lambda: 'return to_string(some_state);'
      on_prev:
        then:
          lambda: 'some_state--;'

`display_menu.up` 操作

这是一个用于在菜单中向上导航的 Action。此操作通常连接到旋转编码器的逆时针旋转或摇杆的上方按钮。

sensor:
  - platform: rotary_encoder
    ...
    on_anticlockwise:
      - display_menu.up:

配置变量：

id (可选, ID): 要导航的菜单的 ID。

`display_menu.down` 操作

这是一个用于在菜单中向下导航的 Action。此操作通常连接到旋转编码器的顺时针旋转或摇杆的下方按钮。

sensor:
  - platform: rotary_encoder
    ...
    on_clockwise:
      - display_menu.down:

配置变量：

id (可选, ID): 要导航的菜单的 ID。

`display_menu.left` 操作

这是一个 Action，通常连接到摇杆的左按钮。在 joystick 模式下，它用于设置上一个值或递减数值；取决于 immediate_edit 标志，是否必须进入编辑模式。如果在 rotary 模式下使用，它将退出编辑。在这两种模式下，当与 back 菜单项一起使用时，它还可以向后导航一层。

binary_sensor:
  - platform: gpio
    ...
    on_press:
      - display_menu.left:

配置变量：

id (可选, ID): 要导航的菜单的 ID。

`display_menu.right` 操作

这是一个 Action，通常连接到摇杆的右按钮。在 joystick 模式下，它用于设置下一个值或递增数值；取决于 immediate_edit 标志，是否必须进入编辑模式。在这两种模式下，当与 menu 菜单项一起使用时，它也可以用于进入子菜单。

binary_sensor:
  - platform: gpio
    ...
    on_press:
      - display_menu.right:

配置变量：

id (可选, ID): 要导航的菜单的 ID。

`display_menu.enter` 操作

这是一个用于触发所选菜单项的 Action，从而产生取决于项类型的操作——进入子菜单、开始/停止编辑或触发命令。此操作通常连接到旋转编码器的按钮或摇杆的中心按钮。

binary_sensor:
  - platform: gpio
    ...
    filters:
      - delayed_on: 10ms
      - delayed_off: 10ms
    on_press:
      - display_menu.enter:

配置变量：

id (可选, ID): 要导航的菜单的 ID。

.. display_menu-show_action:

`display_menu.show` 操作

这是一个用于显示非活动菜单的 Action。菜单的状态保持不变，即隐藏时显示的菜单层级被恢复，选中的项也被恢复。以下代码片段在菜单非活动时显示菜单，否则触发所选项。

on_press:
  - if:
      condition:
        display_menu.is_active:
      then:
        - display_menu.enter:
      else:
        - display_menu.show:

配置变量：

id (可选, ID): 要显示的菜单的 ID。

.. display_menu-hide_action:

`display_menu.hide` 操作

这是一个用于隐藏菜单的 Action。隐藏的菜单不会对 draw() 做出反应，也不会处理导航操作。

lcd_menu:
  ...
  items:
    - type: command
      text: 'Hide'
      on_value:
        then:
          - display_menu.hide:

配置变量：

id (可选, ID): 要隐藏的菜单的 ID。

.. display_menu-show_main_action:

`display_menu.show_main` 操作

这是一个用于显示菜单根层级的 Action。

lcd_menu:
  ...
  items:
    - type: command
      text: 'Show Main'
      on_value:
        then:
          - display_menu.show_main:

配置变量：

id (可选, ID): 要显示的菜单的 ID。

`display_menu.is_active` 条件

此 Condition 检查给定菜单是否活动，即显示在显示屏上并处理导航事件。

on_press:
  - if:
      condition:
        display_menu.is_active:
      ...

另请参阅

API 参考：display_menu_base.h

显示菜单

菜单项

编辑值

标签

菜单

返回

选择

数字

开关

命令

自定义

自动化

on_enter

on_leave

on_value

on_next

on_prev

display_menu.up 操作

display_menu.down 操作

display_menu.left 操作

display_menu.right 操作

display_menu.enter 操作

display_menu.show 操作

display_menu.hide 操作

display_menu.show_main 操作

display_menu.is_active 条件

另请参阅

`on_enter`

`on_leave`

`on_value`

`on_next`

`on_prev`

`display_menu.up` 操作

`display_menu.down` 操作

`display_menu.left` 操作

`display_menu.right` 操作

`display_menu.enter` 操作

`display_menu.show` 操作

`display_menu.hide` 操作

`display_menu.show_main` 操作

`display_menu.is_active` 条件