这个软件包让您在几分钟内为您的 macOS 应用程序添加用户可自定义的全局键盘快捷键支持。它完全兼容沙盒和 Mac App Store。并且已被 Dato、Jiffy、Plash 和 Lungo 在生产环境中使用。

我乐于接受更多的可配置性和功能。欢迎提交 PR！您在这里看到的是我自己的应用程序所需要的。

macOS 10.15+

在 Xcode 的 “Swift Package Manager”选项卡中添加 https://github.com/sindresorhus/KeyboardShortcuts。

首先，为键盘快捷键注册一个名称。

Constants.swift

import KeyboardShortcuts

extension KeyboardShortcuts.Name {
	static let toggleUnicornMode = Self("toggleUnicornMode")
}

然后您可以在其他地方引用这个强类型名称。

您将需要创建一个视图，让用户可以在其中选择键盘快捷键。

SettingsScreen.swift

import SwiftUI
import KeyboardShortcuts

struct SettingsScreen: View {
	var body: some View {
		Form {
			KeyboardShortcuts.Recorder("Toggle Unicorn Mode:", name: .toggleUnicornMode)
		}
	}
}

还有对 Cocoa 而不是 SwiftUI 的支持。

KeyboardShortcuts.Recorder 负责将键盘快捷键存储在 UserDefaults 中，并在用户选择的键盘快捷键已被系统或应用程序主菜单使用时发出警告。

为用户按下他们选择的键盘快捷键时添加一个监听器。

App.swift

import SwiftUI
import KeyboardShortcuts

@main
struct YourApp: App {
	@State private var appState = AppState()

	var body: some Scene {
		WindowGroup {
			// …
		}
		Settings {
			SettingsScreen()
		}
	}
}

@MainActor
@Observable
final class AppState {
	init() {
		KeyboardShortcuts.onKeyUp(for: .toggleUnicornMode) { [self] in
			isUnicornMode.toggle()
		}
	}
}

您也可以使用 .onKeyDown() 监听按键按下事件

就是这样！✨

您可以在“Example”目录中找到完整的示例。

您还可以在我的 Plash 应用程序中找到一个 真实世界的示例。

使用 KeyboardShortcuts.RecorderCocoa 而不是 KeyboardShortcuts.Recorder

import AppKit
import KeyboardShortcuts

final class SettingsViewController: NSViewController {
	override func loadView() {
		view = NSView()

		let recorder = KeyboardShortcuts.RecorderCocoa(for: .toggleUnicornMode)
		view.addSubview(recorder)
	}
}

此软件包支持本地化。欢迎提交更多 PR！

1. Fork 这个仓库。
2. 创建一个目录，其名称使用 ISO 639-1 语言代码和可选的指示符，后跟 .lproj 后缀。更多信息请点击这里。
3. 在新语言目录下创建一个名为 Localizable.strings 的文件，然后将 KeyboardShortcuts/Localization/en.lproj/Localizable.strings 的内容复制到您刚刚创建的新文件中。
4. 进行本地化，并确保多次检查您的本地化内容。检查错别字。
5. 尝试找一位会说您的语言的人来审核翻译。
6. 提交 PR。

请参阅 API 文档。

请参阅 NSMenuItem#setShortcut。

您的应用程序可能需要支持用户自定义操作的键盘快捷键。通常，您会在 extension KeyboardShortcuts.Name {} 中预先静态注册键盘快捷键。但是，这不是必需的。这只是为了方便您在调用各种 API 时可以使用点语法（例如，.onKeyDown(.unicornMode) {}）。您可以动态创建 KeyboardShortcut.Name 并自行存储它们。您可以在示例项目中看到实际操作。

如果您要从不同的软件包迁移，或者只是为自己制作一些东西，设置默认键盘快捷键可能很有用。但是，请不要为公开发布的应用程序设置此项。当随机应用程序窃取他们现有的键盘快捷键时，用户会觉得很烦人。通常最好在首次启动应用程序时显示一个欢迎屏幕，让用户设置快捷键。

import KeyboardShortcuts

extension KeyboardShortcuts.Name {
	static let toggleUnicornMode = Self("toggleUnicornMode", default: .init(.k, modifiers: [.command, .option]))
}

要获取所有键盘快捷键 Name，请使 KeyboardShortcuts.Name 符合 CaseIterable。

import KeyboardShortcuts

extension KeyboardShortcuts.Name {
	static let foo = Self("foo")
	static let bar = Self("bar")
}

extension KeyboardShortcuts.Name: CaseIterable {
	public static let allCases: [Self] = [
		.foo,
		.bar
	]
}

// …

print(KeyboardShortcuts.Name.allCases)

要获取所有已设置键盘快捷键的 Name

print(KeyboardShortcuts.Name.allCases.filter { $0.shortcut != nil })

此软件包

• 用 Swift 编写，具有 Swift 风格的 API。
• 更原生外观的 UI 组件。
• 包含 SwiftUI 组件。
• 支持监听按键按下事件，而不仅仅是按键抬起事件。
• 支持 Swift Package Manager。
• 将快捷键连接到 NSMenuItem。
• 当 NSMenu 打开时（例如，菜单栏应用程序）也可以工作。

MASShortcut:

• 更成熟。
• 更多本地化。

HotKey 非常适合添加硬编码的键盘快捷键，但它不提供任何 UI 组件供用户选择自己的键盘快捷键。

大多数 Carbon API 多年前已被弃用，但仍有一些 Apple 从未推出现代替代品。这包括注册全局键盘快捷键。但是，您不必担心这一点。Apple 肯定会在弃用此处使用的 Carbon API 之前发布新的 API。

不会。

这超出了本软件包的范围。您可以选择使用 NSEvent.addLocalMonitorForEvents、带有键盘快捷键的 NSMenuItem（甚至可以隐藏），或 SwiftUI 的 View#keyboardShortcut() 修饰符。

不支持，因为它不适用于沙盒应用程序。如果您的应用程序未沙盒化，则可以使用 MediaKeyTap。

不可以。但是，即使您通常使用 CocoaPods 或 Carthage，也没有什么可以阻止您仅为此软件包使用 Swift Package Manager。

• Defaults - Swift 风格的现代 UserDefaults
• LaunchAtLogin - 为您的 macOS 应用程序添加“开机启动”功能
• 更多…