Skip to content
阿晴最好看! edited this page May 25, 2025 · 13 revisions

为本地/全局快捷方式提供优雅实现,且后期可快速生成支持自动注册/修改全局快捷方式的控件

Ⅰ 全局快捷方式

1. 激活

在你的MainWindow中,重写两个函数,或者添加对应的事件以激活全局快捷方式。有一个特殊情况可以省去这一步骤,那就是你的MainWindow使用了本库提供的View功能扩展,这种情况下会在初始化时将对应事件添加进MainWindow。

        protected override void OnSourceInitialized(EventArgs e)
        {
            base.OnSourceInitialized(e);

            GlobalHotKey.Awake();
        }

        protected override void OnClosed(EventArgs e)
        {
            GlobalHotKey.Destroy();

            base.OnClosed(e);
        }

2. 注册

即便焦点位于程序外,仍然可以触发

        [Constructor]
        private void SetHotKey()
        {
            GlobalHotKey.Register(VirtualModifiers.Ctrl | VirtualModifiers.Alt, VirtualKeys.F1, (s, e) =>
            {
                var modifiers = HotKeyHelper.GetModifiers(e.Modifiers); // 修饰符Ctrl+Alt
                var key = e.Keys; // 键F1 ( 全局快捷方式可以有多个修饰符,但具体的Key仅存在一个有效值 )
            });
        }

3. 注销

            GlobalHotKey.Unregister(VirtualModifiers.Ctrl, VirtualKeys.F1);

            GlobalHotKey.Unregister(0x01, 0x7A);

Ⅱ 本地快捷方式

1. 注册

仅焦点位于元素时能够触发

        [Constructor]
        private void SetHotKey()
        {
            LocalHotKey.Register(this, [Key.LeftCtrl, Key.F1], (s, e) =>
            {
                // 本地快捷方式可以有多个修饰符,也可以有多个非修饰符,仅焦点位于控件时可被触发
            });
        }

2. 注销

            LocalHotKey.Unregister(this);

            LocalHotKey.Unregister(this, [Key.LeftCtrl, Key.A]);

Ⅲ 组件生成

1. C#部分

标注控件为 [HotKeyComponent] ,于是一些属性和方法被自动生成,我们只需要实现两个基本的分部方法,就可以用这个控件来接收用户输入并自动注册快捷方式了

    [HotKeyComponent]
    public partial class HotKeyBox : UserControl
    {
        partial void OnHotKeyUpdated() // 热键更新后,文本也更新
        {
            if (CanDefaultHotKeyText)
            {
                Text = key == 0x0000 ?
                    string.Join(" > ", [.. HotKeyHelper.GetNames(modifiers)]) :
                    string.Join(" > ", [.. HotKeyHelper.GetNames(modifiers), key.ToString()]);
            }
        }
        partial void OnHotKeyCovered() // 如果其它Box内出现与此Box相同的热键,此Box注册的热键会被覆盖,此时清空文本
        {
            Text = string.Empty;
        }
    }

2. XAML部分

XAML中需要设定KeyDown事件来允许接收键盘事件,需要注意的是,如果元素不可聚焦,需要为元素标注 [Focusable] 或设置 Focusable = true

 KeyDown="OnHotKeyReceived"

3. 组件内容一览

用于自动注册/修改快捷方式的组件将具备以下内容,你可依据需求将其定制

分类 成员/事件/方法 说明
事件 HotKeyRegisterSuccessed 热键注册成功时触发的事件
HotKeyRegisterFailed 热键注册失败时触发的事件
HotKeyInvoking 热键即将触发时触发的事件(带HotKeyEventArgs参数)
HotKeyInvoked 热键触发完成后触发的事件(带HotKeyEventArgs参数)
HotKeyCovering 热键即将被覆盖(清除)时触发的事件
HotKeyCovered 热键已被覆盖(清除)后触发的事件
HotKeyUpdating 热键即将更新时触发的事件
HotKeyUpdated 热键更新完成后触发的事件
ModifiersChanged 修饰键(如Ctrl、Shift等)发生变化时触发的事件(带新旧值参数)
KeyChanged 主键(如A、B等)发生变化时触发的事件(带新旧值参数)
属性 IsHotKeyRegistered 表示当前热键是否已注册(protected set,仅限内部修改)
RecordedModifiers 当前记录的修饰键(DependencyProperty,修改时会触发ModifiersChanged)
RecordedKey 当前记录的主键(DependencyProperty,修改时会触发KeyChanged)
方法 InvokeHotKey() 手动触发热键事件(调用HotKeyInvoking和HotKeyInvoked)
CoverHotKey() 清除当前热键(触发HotKeyCovering和HotKeyCovered)
OnHotKeyReceived() 处理键盘输入事件,更新modifiers和key缓存
UpdateHotKey() 更新RecordedModifiers和RecordedKey(触发HotKeyUpdating和HotKeyUpdated)
UpdateHotKeyCache() 直接更新热键缓存(不触发事件)
依赖属性 RecordedModifiersProperty RecordedModifiers的DependencyProperty,变更时调用Inner_OnModifiersChanged
RecordedKeyProperty RecordedKey的DependencyProperty,变更时调用Inner_OnKeyChanged
内部逻辑 modifiers(HashSet<VirtualModifiers>) 存储当前按下的修饰键(如Ctrl、Alt等)
key(VirtualKeys) 存储当前按下的主键(如A、B等)
部分方法 OnHotKeyRegisterSuccessed() 热键注册成功时的扩展点(可由部分类实现)
OnHotKeyRegisterFailed() 热键注册失败时的扩展点
OnModifiersChanged() 修饰键变化时的扩展点
OnKeyChanged() 主键变化时的扩展点
OnHotKeyInvoking() / OnHotKeyInvoked() 热键触发前/后的扩展点
OnHotKeyCovering() / OnHotKeyCovered() 热键覆盖前/后的扩展点
OnHotKeyUpdating() / OnHotKeyUpdated() 热键更新前/后的扩展点

Clone this wiki locally