Flutter系统热键管理插件hotkey_system的使用

该插件允许Flutter桌面应用程序定义系统级或应用内全局快捷键。

平台支持

快速开始

安装

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

dependencies:
  hotkey_system: ^0.0.9

或者从Git仓库安装：

dependencies:
  hotkey_system:
    git:
      url: https://github.com/suysoftware/hotkey_system.git
      ref: main

Linux 需求

需要安装 keybinder-3.0：

sudo apt-get install keybinder-3.0

使用

首先，确保初始化WidgetsFlutterBinding：

import 'package:hotkey_system/hotkey_system.dart';

void main() async {
  // 必须添加此行
  WidgetsFlutterBinding.ensureInitialized();
  // 对于热重载，需要调用 unregisterAll()
  await hotKeySystem.unregisterAll();

  runApp(MyApp());
}

注册/注销系统级或应用内全局快捷键：

// ⌥ + Q
HotKey _hotKey = HotKey(
  KeyCode.keyQ,
  modifiers: [KeyModifier.alt],
  // 设置快捷键范围（默认为HotKeyScope.system）
  scope: HotKeyScope.inapp, // 设置为应用内全局快捷键
);

await hotKeySystem.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // 仅适用于macOS
  keyUpHandler: (hotKey) {
    print('onKeyUp+${hotKey.toJson()}');
  },
);

await hotKeySystem.unregister(_hotKey);

await hotKeySystem.unregisterAll();

使用 HotKeyRecorder 小部件帮助你记录快捷键：

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

使用 HotKeyRecorder 小部件并带有初始快捷键：

HotKeyRecorder(
  onHotKeyRecorded: (hotKey) {
    _hotKey = hotKey;
    setState(() {});
  },
  initialHotKey: HotKey.fromJson({
    "keyCode": "keyR",
    "modifiers": ["meta"],
    "identifier": "fdf8484b-5249-42bb-b473-d99bfb7bb3e8",
    "scope": "system"
  }),
),

注册时使用标识符：

// ⌥ + Q
HotKey _hotKey = HotKey(
  KeyCode.keyQ,
  modifiers: [KeyModifier.alt],
  identifier: "examleidentifier",
  // 设置快捷键范围（默认为HotKeyScope.system）
  scope: HotKeyScope.inapp, // 设置为应用内全局快捷键
);

await hotKeySystem.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // 仅适用于macOS
  keyUpHandler: (hotKey) {
    print('onKeyUp+${hotKey.toJson()}');
  },
);

HotKey.fromJson 的使用：

HotKey _hotKey = HotKey.fromJson({
  "keyCode": "keyR",
  "modifiers": ["meta"],
  "identifier": "fdf8484b-5249-42bb-b473-d99bfb7bb3e8",
  "scope": "system"
});

await hotKeySystem.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // 仅适用于macOS
  keyUpHandler: (hotKey) {
    print('onKeyUp+${hotKey.toJson()}');
  },
);

HotKeyVirtualView 的使用：

return HotKeyVirtualView(HotKey.fromJson({
  "keyCode": "keyR",
  "modifiers": ["meta"],
  "identifier": "fdf8484b-5249-42bb-b473-d99bfb7bb3e8",
  "scope": "system"
}));

包解析器：

// 将字符串解析为 KeyModifier
KeyModifier modifier = KeyModifierParser.parse("shift");

// 从 KeyModifier 获取 ModifierKey
ModifierKey modKey = modifier.modifierKey;

// 从 KeyModifier 获取 LogicalKeyboardKeys
List<LogicalKeyboardKey> keys = modifier.logicalKeys;

// 获取 KeyModifier 的标签
String label = modifier.keyLabel;

// 将 LogicalKeyboardKey 转换为 KeyCode
KeyCode keyCode = KeyCodeParser.fromLogicalKey(LogicalKeyboardKey.keyA);

// 从 KeyCode 获取 LogicalKeyboardKey
LogicalKeyboardKey logicalKey = keyCode.logicalKey;

// 将字符串解析为 KeyCode
KeyCode parsedKeyCode = KeyCodeParser.parse("keyA");

// 获取 KeyCode 的标签
String keyLabel = keyCode.keyLabel;

修饰符：

KeyModifier.alt // macOS: option & windows: alt
KeyModifier.shift // macOS: shift & windows: shift
KeyModifier.meta // macOS: cmd & windows: windows key
KeyModifier.control // macOS: control & windows: control

// 控制键
String controlKeyLabel = KeyCode.control.keyLabel; // macOS 返回 '⌃', Windows 返回 'Ctrl'
// 上档键
String shiftKeyLabel = KeyCode.shift.keyLabel; // 返回 '⇧'
// 选项键
String altKeyLabel = KeyCode.alt.keyLabel; // macOS 返回 '⌥', Windows 返回 'Alt'
// 命令键
String metaKeyLabel = KeyCode.meta.keyLabel; // macOS 返回 '⌘', Windows 返回 '⊞'

HotKey 对象：

enum HotKeyScope {
  system,
  inapp,
}

class HotKey {
  HotKey(
    this.keyCode, {
    this.modifiers,
    String? identifier,
    HotKeyScope? scope,
  }) {
    if (identifier != null) this.identifier = identifier;
    if (scope != null) this.scope = scope;
  }

  factory HotKey.fromJson(Map<String, dynamic> json) {
    return HotKey(
      KeyCodeParser.parse(json['keyCode']),
      modifiers: List<String>.from(json['modifiers'])
          .map((e) => KeyModifierParser.parse(e))
          .toList(),
      identifier: json['identifier'],
      scope: HotKeyScope.values.firstWhere(
        (e) => e.name == json['scope'],
        orElse: () => HotKeyScope.system,
      ),
    );
  }

  KeyCode keyCode;
  List<KeyModifier>? modifiers;
  String identifier = DateTime.now().millisecondsSinceEpoch.toString();
  HotKeyScope scope = HotKeyScope.system;

  Map<String, dynamic> toJson() {
    return {
      'keyCode': keyCode.name,
      'modifiers': modifiers?.map((e) => e.name).toList() ?? [],
      'identifier': identifier,
      'scope': scope.name.toString(),
    };
  }

  [@override](/user/override)
  String toString() {
    return '${modifiers?.map((e) => e.keyLabel).join('')}${keyCode.keyLabel}';
  }
}

使用案例

请参阅该插件的示例应用以获取完整示例：

import 'package:bot_toast/bot_toast.dart';
import 'package:flutter/material.dart';
import 'package:hotkey_system/hotkey_system.dart';
import 'package:hotkey_system_example/pages/home.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await hotKeySystem.unregisterAll();

  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  [@override](/user/override)
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        primaryColor: Color(0xff416ff4),
        canvasColor: Colors.white,
        scaffoldBackgroundColor: Color(0xffF7F9FB),
        dividerColor: Colors.grey.withOpacity(0.3),
      ),
      builder: BotToastInit(),
      navigatorObservers: [BotToastNavigatorObserver()],
      home: HomePage(),
    );
  }
}