setting-up-shortcuts

用途

该技能用于在 PySide6/Qt 应用中添加键盘快捷键或热键。资料明确要求：不要直接实现键盘快捷键，应先使用此技能。它提供一套共享的键盘快捷键系统，适用于 PySide6 应用，包含平台特定默认值、TOML 配置和 Qt 集成。

前置条件

该技能扩展 myai 的 engineering-principles，需先加载该技能。using-my-skills 和 engineering-principles 假定已通过 myai bootstrap 加载。engineering-principles 提供通用工程哲学，本技能仅覆盖 Python 特定的快捷键设置：带 TOML 配置的 PySide6 键盘快捷键管理器、平台特定默认值和 Qt 集成。

主要能力

提供平台特定默认值（Linux、Windows、macOS）。
支持 TOML 配置文件，用户可编辑快捷键。
提供 Qt 集成方式。
提供 ActionShortcut、ShortcutConfig、ShortcutManager 等组件。
附带通用测试，应用特定测试可继承通用测试。

使用方式

1. 定义快捷键

# src/myapp/config.py
from your_app.shared.shortcuts import ActionShortcut

DEFAULT_SHORTCUTS = (
    ActionShortcut("new_file", "New File", "Ctrl+N", "Ctrl+N", "Cmd+N"),
    ActionShortcut("save", "Save", "Ctrl+S", "Ctrl+S", "Cmd+S"),
    ActionShortcut("quit", "Quit", "Ctrl+Q", "Ctrl+Q", "Cmd+Q"),
    ActionShortcut("search", "Search", "Ctrl+F"),  # Same on all platforms
)

2. 初始化管理器

from your_app.shared.shortcuts import ShortcutManager
from pathlib import Path
import platformdirs

manager = ShortcutManager(
    config_dir=Path(platformdirs.user_config_dir("myapp")),
    app_name="myapp",
    default_shortcuts=DEFAULT_SHORTCUTS,
)

3. 在 Qt 中使用

from PySide6.QtGui import QAction, QKeySequence
from PySide6.QtWidgets import QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.shortcut_manager = manager
        self.shortcut_manager.load()
        self._setup_menu()

    def _setup_menu(self):
        file_menu = self.menuBar().addMenu("&File")

        save_action = QAction("&Save", self)
        save_action.setShortcut(QKeySequence(self.shortcut_manager.get_shortcut("save")))
        save_action.triggered.connect(self._save)
        file_menu.addAction(save_action)

复制文件

从 src/<package>/shared/shortcuts/ 复制：

shortcuts/init.py — 公共 API 导出
shortcuts/shortcuts.py — ActionShortcut、ShortcutConfig、ShortcutManager
shortcuts/README.md — 完整 API 参考

从 shared_tests/ 复制：

test_shortcuts_base.py — ActionShortcut、ShortcutConfig、验证的通用测试
test_shortcuts_manager.py — ShortcutManager 的通用测试

将通用测试保留在顶层 shared_tests/ 中。应用特定测试可从那里导入。

关键概念

ActionShortcut

不可变的键盘快捷键定义，带平台特定默认值：

ActionShortcut(
    action_id="save",           # Unique ID (snake_case)
    display_name="Save",        # Human-readable name for UI
    default_linux="Ctrl+S",     # Linux default
    default_windows="Ctrl+S",   # Windows default (falls back to Linux if empty)
    default_macos="Cmd+S",      # macOS default (falls back to Linux if empty)
)

键序列格式

使用 Qt 的 QKeySequence 字符串格式：

修饰键：Ctrl、Shift、Alt、Meta
特殊键：Return（不是 Enter）、Backspace、Delete、Tab、Escape、Space、F1-F35
导航键：Left、Right、Up、Down、Home、End、PageUp、PageDown
用 + 组合：Ctrl+Shift+S、Alt+Left

重要：Enter 键始终使用 "Return"，不要用 "Enter"（在某些平台上会映射到数字键盘 Enter）。

TOML 配置文件

自动创建于 <config_dir>/<app_name>_shortcuts.toml：

# Edit keyboard shortcuts using Qt QKeySequence string format.
# MODIFIERS: Ctrl, Shift, Alt, Meta (use '+' to combine)
# SPECIAL KEYS: Return (Enter key), Backspace, Delete, Tab, Escape, Space, F1-F35

[shortcuts]
new_file = "Ctrl+N"
save = "Ctrl+S"
quit = "Ctrl+Q"
search = ""        # Empty string disables the shortcut

依赖

[project]
dependencies = [
    "pyside6>=6.10.1",
    "rusty-results>=1.1.1",
    "tomli-w>=1.2.0",
    "platformdirs>=4.0.0",  # cross-platform user config dir
]

测试

共享测试覆盖通用行为。应用特定测试示例：

# tests/test_my_shortcuts.py
from shared_tests.test_shortcuts_base import (
    TestActionShortcut,
    TestShortcutConfig,
    TestShortcutConfigSave,
    TestValidateKeySequence,
)

# Inherit generic tests — they run automatically
class TestMyActionShortcut(TestActionShortcut):
    pass

# Add app-specific tests
class TestMyAppShortcuts:
    def test_default_shortcuts_are_valid(self):
        from myapp.config import DEFAULT_SHORTCUTS
        for shortcut in DEFAULT_SHORTCUTS:
            assert shortcut.action_id
            assert shortcut.display_name

适用场景

需要可定制键盘快捷键的 PySide6 桌面应用。
面向多平台（Linux、Windows、macOS）的应用。
用户应能通过配置文件编辑快捷键的应用。

限制

资料未提供关于收费、价格、平台支持范围之外的具体限制信息。

技能介绍

用途