Flutter全局热键管理插件hotkey_manager的使用

hotkey_manager 是一个允许Flutter桌面应用程序定义系统范围或应用内全局热键（快捷键）的插件。它支持Linux、macOS和Windows平台。

平台支持

快速开始

安装

在您的项目的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  hotkey_manager: ^0.2.3

或者通过Git安装最新版本：

dependencies:
  hotkey_manager:
    git:
      path: packages/hotkey_manager
      url: https://github.com/leanflutter/hotkey_manager.git
      ref: main

Linux要求

对于Linux用户，需要安装keybinder-3.0，可以通过以下命令安装：

sudo apt-get install keybinder-3.0

使用方法

首先确保初始化了Flutter绑定，并且为了支持热重载，需要调用unregisterAll()来注销所有已注册的热键。

import 'package:hotkey_manager/hotkey_manager.dart';

void main() async {
  // 确保Flutter绑定已经初始化
  WidgetsFlutterBinding.ensureInitialized();
  // 注销所有已注册的热键以支持热重载
  await hotKeyManager.unregisterAll();

  runApp(MyApp());
}

接下来可以注册一个系统级或应用内的全局热键：

// 定义热键 ⌥ + Q
HotKey _hotKey = HotKey(
  key: PhysicalKeyboardKey.keyQ,
  modifiers: [HotKeyModifier.alt],
  // 设置热键作用域 (默认是系统级)
  scope: HotKeyScope.inapp, // 设置为应用内全局热键
);

await hotKeyManager.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // 仅在macOS上有效
  keyUpHandler: (hotKey){
    print('onKeyUp+${hotKey.toJson()}');
  } ,
);

如果要注销某个热键或全部热键，可以分别调用unregister()和unregisterAll()方法：

await hotKeyManager.unregister(_hotKey);

await hotKeyManager.unregisterAll();

此外，还可以使用HotKeyRecorder小部件来帮助记录用户输入的热键：

HotKeyRecorder(
  onHotKeyRecorded: (hotKey) {
    _hotKey = hotKey;
    setState(() {});
  },
),

请参考插件提供的完整示例程序以了解更详细的用法。

API

以下是hotkey_manager提供的主要API接口及其说明：

示例代码

下面是一个完整的示例代码，演示如何使用hotkey_manager插件创建一个简单的Flutter应用程序并设置全局热键：

import 'package:flutter/material.dart';
import 'package:hotkey_manager/hotkey_manager.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await hotKeyManager.unregisterAll(); // 注销所有热键以支持热重载

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Hotkey Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late HotKey _hotKey;

  @override
  void initState() {
    super.initState();
    
    // 初始化热键
    _hotKey = HotKey(
      key: PhysicalKeyboardKey.keyQ,
      modifiers: [HotKeyModifier.alt],
      scope: HotKeyScope.system,
    );

    // 注册热键
    hotKeyManager.register(
      _hotKey,
      keyDownHandler: (hotKey) {
        print('Alt + Q pressed!');
      },
    );
  }

  @override
  void dispose() {
    // 清理资源
    hotKeyManager.unregister(_hotKey);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Flutter Hotkey Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text('Press Alt + Q to see the effect.'),
          ],
        ),
      ),
    );
  }
}

此示例展示了如何在Flutter应用程序中注册和处理全局热键事件。当用户按下Alt + Q时，控制台将打印一条消息。在实际应用中，您可以根据需求修改这些逻辑。