keyboard - PythonIDE Docs

脚本编辑器键盘工具栏：自定义快捷键按钮、插入文本与代码片段。

边界：作用于 PythonIDE 脚本编辑器键盘上方工具栏，不是 AppUI 小应用内键盘。配置代码应在编辑器中运行的脚本里执行；AppUI 示例仅演示配置写法。

#模块概览

项	说明
导入	`import keyboard`
适合做什么	Tab 缩进、常用关键字、代码片段、光标跳转
调用时机	编辑器打开前或脚本开头注册按钮
推荐顺序	`clear()`（可选）→ `add_button` / `add_group` → 回调里 `insert_text`
回调	`action` 为 Python 函数，点击时在当前编辑器执行

#快速开始

在编辑器脚本中注册工具栏按钮：

python

import keyboard


def insert_tab():
    keyboard.insert_text("    ")


def insert_print():
    keyboard.insert_text("print()")


def insert_def_snippet():
    keyboard.insert_snippet("def ${1:name}(${2:args}):\n    ${0:pass}")


keyboard.clear()
keyboard.add_button("Tab", action=insert_tab)
keyboard.add_button("print", action=insert_print)
keyboard.add_button("def", action=insert_def_snippet)

分组按钮：

python

import keyboard


def insert_import():
    keyboard.insert_text("import ")


def insert_if():
    keyboard.insert_text("if :\n    ", offset=-6)


keyboard.add_group("常用", buttons=[
    keyboard.Button("import", action=insert_import),
    keyboard.Button("if", action=insert_if),
])

#AppUI 示例

说明：以下界面展示推荐配置；实际生效需在编辑器中运行同等 keyboard 代码。

python

import appui

state = appui.State(
    config_status="未应用",
    snippet_preview="def name(args):\n    pass",
)


def show_config_hint():
    state.config_status = (
        "请在编辑器脚本中执行 keyboard.add_button；"
        "AppUI 内不会修改编辑器工具栏。"
    )


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("说明", [
                appui.Text(
                    "keyboard 模块自定义脚本编辑器键盘工具栏，"
                    "不作用于本 AppUI 界面内的输入框。"
                ).foreground_color("secondaryLabel"),
                appui.Button("查看配置说明", action=show_config_hint)
                .button_style("bordered_prominent"),
            ]),
            appui.Section("推荐配置示例", [
                appui.LabeledContent("Tab", value='insert_text("    ")'),
                appui.LabeledContent("print", value='insert_text("print()")'),
                appui.Text(state.snippet_preview)
                .font("caption")
                .foreground_color("secondaryLabel"),
            ]),
            appui.Section("状态", [
                appui.Text(state.config_status).foreground_color("secondaryLabel"),
            ], footer="在编辑器新建脚本，粘贴「快速开始」代码后运行一次即可。"),
        ]).navigation_title("键盘工具栏")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`add_button(label, action=None, icon=None)`	添加单个按钮
`add_group(name, buttons)`	添加按钮组
`set_buttons(buttons)`	替换全部按钮
`remove_button(label)`	移除按钮
`clear()`	清空自定义按钮
`insert_text(text, offset=0)`	插入文本，可选光标偏移
`insert_snippet(template)`	插入片段（`$1`、`$0` 占位）
`move_cursor(offset)`	移动光标
`Button(label, action=None, icon=None)`	按钮描述类

#insert_text / insert_snippet

python

keyboard.insert_text("    ")  # Tab
keyboard.insert_text("if :\n    ", offset=-6)  # 光标回到条件处
keyboard.insert_snippet("def ${1:name}():\n    ${0:pass}")
keyboard.move_cursor(-3)

icon 可选 SF Symbol 名称。

#生命周期

同一 label 对应稳定 btn_{label} ID；remove_button / clear 会注销回调。

#常见错误

错误写法	后果	修正
在 AppUI 里期望改工具栏	不生效	在编辑器脚本中注册
重复 `add_button` 同名	覆盖或重复	先 `clear()` 或 `remove_button`
`action` 未调用 `insert_*`	按钮无效果	回调里写插入逻辑
与系统键盘混淆	概念错误	本模块仅编辑器 accessory 工具栏

#相关文档

文档	用途
console	控制台弹窗
appui	小应用界面（非编辑器工具栏）

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。