M5Keyboard

M5Keyboard是一个用于在用户界面中创建虚拟键盘的小组件。它提供屏幕键盘，可用于文本输入，支持不同的键盘模式和布局。

UiFlow2 应用示例

基础键盘

在UiFlow2中打开|cores3_keyboard_basic_example.m5f2|项目。

此示例演示如何创建虚拟键盘并将其连接到文本输入区域。

UiFlow2 代码块：

示例输出：

None

MicroPython 应用示例

基础键盘

此示例演示如何创建虚拟键盘并将其连接到文本输入区域。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
import m5ui
import lvgl as lv


page0 = None
textarea0 = None
keyboard0 = None


def textarea0_focused_event(event_struct):
    global page0, textarea0, keyboard0
    keyboard0.set_flag(lv.obj.FLAG.HIDDEN, False)


def textarea0_defocused_event(event_struct):
    global page0, textarea0, keyboard0
    keyboard0.set_flag(lv.obj.FLAG.HIDDEN, True)


def textarea0_event_handler(event_struct):
    global page0, textarea0, keyboard0
    event = event_struct.code
    if event == lv.EVENT.FOCUSED and True:
        textarea0_focused_event(event_struct)
    if event == lv.EVENT.DEFOCUSED and True:
        textarea0_defocused_event(event_struct)
    return


def setup():
    global page0, textarea0, keyboard0

    M5.begin()
    Widgets.setRotation(1)
    m5ui.init()
    page0 = m5ui.M5Page(bg_c=0xFFFFFF)
    textarea0 = m5ui.M5TextArea(
        text="textarea0",
        placeholder="Placeholder...",
        x=10,
        y=30,
        w=300,
        h=70,
        font=lv.font_montserrat_14,
        bg_c=0xFFFFFF,
        border_c=0xE0E0E0,
        text_c=0x212121,
        parent=page0,
    )
    keyboard0 = m5ui.M5Keyboard(
        x=0,
        y=120,
        w=320,
        h=120,
        mode=lv.keyboard.MODE.TEXT_LOWER,
        target_textarea=textarea0,
        parent=page0,
    )

    textarea0.add_event_cb(textarea0_event_handler, lv.EVENT.ALL, None)

    page0.screen_load()


def loop():
    global page0, textarea0, keyboard0
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            m5ui.deinit()
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

None

API参考

M5Keyboard

class m5ui.keyboard.M5Keyboard(*args, **kwargs)

基类：keyboard

Create a keyboard widget.

参数:

• x (int) – 键盘的 x 位置。

• y (int) – 键盘的 y 位置。

• w (int) – 键盘的宽度。

• h (int) – 键盘的高度。

• mode (int) – 键盘模式，默认为“lv.keyboard.MODE.TEXT_LOWER”。

• target_textarea (lv.obj) – 与键盘链接的目标文本区域。

• parent (lv.obj) – 父对象，默认为活动屏幕。

UiFlow2 代码块：

None

MicroPython 代码块：

import m5ui
import lvgl as lv

m5ui.init()
keyboard = m5ui.M5Keyboard(x=0, y=120, w=320, h=100, target_textarea=None, parent=page0)

set_flag(flag, value)

在对象上设置标志。如果``value``为True，则添加标志；如果为False，则移除标志。

参数:

• flag (int) – 要设置的标志。

• value (bool) – 如果为True，则添加标志；如果为False，则移除标志。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_flag(lv.obj.FLAG.HIDDEN, True)

toggle_flag(flag)

切换对象上的标志。如果标志已设置，则移除；如果未设置，则添加。

参数:

flag (int) – 要切换的标志。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.toggle_flag(lv.obj.FLAG.HIDDEN)

set_state(state, value)

设置键盘的状态。如果``value``为True，则设置状态；如果为False，则取消设置状态。

参数:

• state (int) – 要设置的状态。

• value (bool) – 如果为True，则设置状态；如果为False，则取消设置状态。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_state(lv.STATE.PRESSED, True)

toggle_state(state)

切换键盘状态。如果状态已设置，则取消设置；如果状态未设置，则设置状态。

参数:

state (int) – 要切换的状态。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.toggle_state(lv.STATE.PRESSED)

add_event_cb(handler, event, user_data)

为键盘添加事件回调。当指定事件发生时，将调用回调函数。

参数:

• handler (function) – 要调用的回调函数。

• event (int) – 要监听的事件。

• user_data (Any) – 传递给回调函数的可选用户数据。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

def keyboard_0_value_changed_event(event_struct):
    global page0, textarea0
    print("Key pressed")

def keyboard_0_ready_event(event_struct):
    global page0, textarea0
    print("Ready")

def keyboard_0_event_handler(event_struct):
    event = event_struct.code
    if event == lv.EVENT.VALUE_CHANGED:
        keyboard_0_value_changed_event(event_struct)
    elif event == lv.EVENT.READY:
        keyboard_0_ready_event(event_struct)
    return

keyboard_0.add_event_cb(keyboard_0_event_handler, lv.EVENT.ALL, None)

set_textarea(textarea)

设置此键盘应控制的文本输入区域。当按下按键时，文本将输入到指定的文本区域中。

参数:

textarea (lv.textarea) – 要连接到键盘的文本输入区域对象。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_textarea(textarea_0)

get_textarea()

获取当前连接到此键盘的文本输入区域。

返回:

已连接的文本输入区域对象，如果没有连接文本区域则为None。

返回类型:

lv.textarea or None

UiFlow2 代码块：

MicroPython 代码块：

ta = keyboard_0.get_textarea()

set_mode(mode)

设置键盘模式以显示不同的键盘布局。

参数:

mode (int) – 设置的键盘模式。

返回:

None

可用的模式包括:

• lv.keyboard.MODE.TEXT_LOWER：0。

• lv.keyboard.MODE.TEXT_UPPER：1。

• lv.keyboard.MODE.SYMBOL：2。

• lv.keyboard.MODE.NUMBER：3。

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_mode(lv.keyboard.MODE.TEXT_LOWER)

get_mode()

获取当前的键盘模式。

返回:

当前的键盘模式。

返回类型:

int

键盘模式包括

• lv.keyboard.MODE.TEXT_LOWER：0。

• lv.keyboard.MODE.TEXT_UPPER：1。

• lv.keyboard.MODE.SYMBOL：2。

• lv.keyboard.MODE.NUMBER：3。

UiFlow2 代码块：

MicroPython 代码块：

mode = keyboard_0.get_mode()

set_popovers(en)

启用或禁用键盘的弹出窗口。弹出窗口是按下某些按键时显示的附加 UI 元素。

参数:

en (bool) – 如果为 True，则启用弹出窗口；如果为 False，则禁用弹出窗口。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_popovers(True)

get_selected_button()

获取最后释放的按钮的索引。这有助于确定最后按下的键。

返回:

最后释放的按钮的索引。

返回类型:

int

UiFlow2 代码块：

MicroPython 代码块：

btn = keyboard_0.get_selected_button()

get_button_text(btn_id)

根据索引获取按钮的文本。

参数:

btn (int) – 按钮的索引。

返回:

按钮的文本。

返回类型:

str

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.get_button_text(3)

set_pos(x, y)

设置键盘的位置。

参数:

• x (int) – 键盘的x坐标。

• y (int) – 键盘的y坐标。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_pos(100, 100)

set_x(x)

设置键盘的x坐标。

参数:

x (int) – 键盘的x坐标。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_x(100)

set_y(y)

设置键盘的y坐标。

参数:

y (int) – 键盘的y坐标。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_y(100)

set_size(width, height)

设置键盘的大小。

参数:

• width (int) – 键盘的宽度。

• height (int) – 键盘的高度。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_size(300, 200)

set_width(width)

设置键盘的宽度。

参数:

width (int) – 键盘的宽度。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_width(300)

get_width()

获取键盘的宽度。

返回:

键盘的宽度。

返回类型:

int

UiFlow2 代码块：

MicroPython 代码块：

width = keyboard_0.get_width()

set_height(height)

设置键盘的高度。

参数:

height (int) – 键盘的高度。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.set_height(200)

get_height()

获取键盘的高度。

返回:

键盘的高度。

返回类型:

int

UiFlow2 代码块：

MicroPython 代码块：

height = keyboard_0.get_height()

align_to(obj, align, x, y)

将键盘与另一个物体对齐。

参数:

• obj (lv.obj) – 要对齐的对象。

• align (int) – 对齐类型。

• x (int) – 与对齐对象的 x 偏移量。

• y (int) – 与对齐对象的 y 偏移。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

keyboard_0.align_to(page_0, lv.ALIGN.BOTTOM_MID, 0, -10)