Skip to content
Slint Docs

键盘输入总览

要在 Slint 中处理键盘输入，请使用带有 KeyBinding 元素的 FocusScope，或各种元素中的单独 key-pressed 和 key-released 回调。 键盘输入通过 KeyEvent 数据结构传递。 该数据结构的主要字段是 text 属性，它以字符串形式保存所有受影响的键。 使用 Key 命名空间 来识别已知的命名键。

有关如何使用 Slint 的 KeyBinding 元素以及由 @keys 宏构造的内置 keys 类型以声明方式处理按键绑定的内容，请参见按键绑定部分。

KeyEvent

Section titled “KeyEvent”

此结构被生成并传递给 FocusScope 元素的按键按下和释放回调。

  • text（string）：所按下键的 Unicode 表示。
  • modifiers（KeyboardModifiers）：按键按下事件发生时处于活动状态的键盘修饰键。
  • repeat（bool）：对于重复的按键按下事件（即按住键不放），此字段设置为 true。对于按键释放事件，它始终为 false。

按键绑定

Section titled “按键绑定”

在 FocusScope 内使用 KeyBinding 元素 来声明按键绑定（或键盘快捷键）。 KeyBinding 的 keys 属性接受 keys 类型 的实例，并在检测到该键组合时调用 activated 回调。

keys 类型表示一个键与修饰键的组合，并使用 @keys 宏构造。

Slint 中的按键绑定基于逻辑键——按键在当前键盘布局上产生的字符——而不是键的物理位置。 这意味着，例如 @keys(Control + Z) 在用户按下其布局上产生 z 的键时激活，无论该键位于键盘上的何处。 因此，小键盘数字键与主行数字键不作区分，并且 AltGr 不能作为修饰键使用（它会被操作系统消耗以产生字符）。

@keys(..) 宏接受来自 Key 命名空间 的键，并结合以下任一修饰键：

  • Meta（macOS 上为 ⌃ control，PC 上为 Windows 键）
  • Control（macOS 上为 ⌘ command）
  • Shift
  • Alt（macOS 上为 ⌥ option）
export component Example inherits Window {
    forward-focus: scope;


    scope := FocusScope {
        KeyBinding {
            keys: @keys(Control + Q);
            activated => { debug("Quit shortcut activated"); }
        }


        KeyBinding {
            keys: @keys(Control + S);
            activated => { debug("Save shortcut activated"); }
        }


        Text {
            text: scope.has-focus ? "Press Control + Q or Control + S" : "Click to focus";
        }
    }
}
slint

不同的键盘布局

Section titled “不同的键盘布局”

对于来自 Key 命名空间 的键，@keys(..) 宏会自动处理不同的键盘布局。 例如，@keys(Control + Plus) 在用户按下其布局上产生 + 的键时触发——在 US 布局上这需要 Shift + =，而在 German 布局上 + 有自己的键，无需 Shift。

@keys(..) 内的命名键是逻辑的：A 表示字符 a，而不是特定的物理键位置。这意味着 @keys(Control + A) 会在用户布局上产生 a 的键上激活，无论该键位于键盘上的何处。

如果你需要定义涉及 Key 命名空间 之外键的按键绑定，请继续阅读下一节，其中介绍了高级键定义。

高级按键绑定

Section titled “高级按键绑定”

如果可能，优先在 @keys(..) 内使用来自 Key 命名空间 的键。 如果你确实需要定义到其他键的绑定，可以在 @keys(..) 宏内使用字符串字面量。 例如：@keys(Control + "ä")。

但请注意，在这种情况下，@keys(..) 宏不再自动处理不同的键盘布局和 Shift 行为。 提供的字符串只会与小写化的 text 以及给定 KeyEvent 的修饰键进行匹配

为避免在应用 Shift（有时在 macOS 上是 Alt）时完全改变键码的字符出现问题，你可以用尾随的 ? 将这些修饰键标记为可选，例如：

  • Shift?
  • Alt?

当修饰键被标记为可选时，keys 在匹配时会忽略相应修饰键的状态。

例如，要支持产生欧元符号 (€) 的按键绑定，同时添加 Shift? 和 Alt?：@keys(Control + Shift? + Alt? + "€")。 这将允许你的用户在几乎所有带有此标签键的键盘布局上使用该绑定。

再举一个例子，@keys(Control + Plus) 等价于 @keys(Control + Shift? + "+")。

Key 命名空间

Section titled “Key 命名空间”

Key 命名空间包含一个众所周知的逻辑键码列表（包括任何不可打印字符）。 此命名空间中的键名根据它们产生的字符来标识键，而不是根据它们在键盘上的物理位置。 例如，Key.A 表示字符 a，而不是 QWERTY 键盘左上角的字母键。

请注意，字母键（例如 Key.A-Key.Z）以小写表示（例如 “a”-“z”）。 确保根据需要转换 KeyEvent text 或 Key 的大小写。

The Key namespace contains the well-known logical key codes. The upstream Slint documentation generator emits this table; this port does not ship the generator, so the table below is a hand-maintained stub.

Key Description
Key.Backspace Backspace
Key.Tab Tab
Key.Return Enter / Return
Key.Escape Escape
Key.Space Space
Key.Delete Delete
Key.UpArrow Up arrow
Key.DownArrow Down arrow
Key.LeftArrow Left arrow
Key.RightArrow Right arrow
Key.Home Home
Key.End End
Key.PageUp Page up
Key.PageDown Page down
Key.Shift Shift modifier
Key.Control Control modifier
Key.Alt Alt modifier
Key.Meta Meta / Command modifier
Key.F1 … Key.F12 Function keys
Key.a … Key.z Alphabetic keys (lowercase)
Key.0 … Key.9 Digit keys

© 2026 SixtyFPS GmbH