KeyboardShortcuts

<div align="center"> <img width="900" src="https://github.com/sindresorhus/KeyboardShortcuts/raw/main/logo-light.png#gh-light-mode-only" alt="KeyboardShortcuts"> <img width="900" src="https://github.com/sindresorhus/KeyboardShortcuts/raw/main/logo-dark.png#gh-dark-mode-only" alt="KeyboardShortcuts"> <br> </div>

这个包让您可以在几分钟内为您的 macOS 应用添加用户自定义全局键盘快捷键支持。它完全兼容沙盒和 Mac App Store。它已在 Dato、Jiffy、Plash 和 Lungo 等产品中使用。

我很乐意接受更多的配置和功能。欢迎提交 PR！这里看到的只是我自己的应用所需要的功能。

<img src="https://yellow-cdn.veclightyear.com/ab5030c0/0175298a-1fca-4dc3-b568-560f10683bcd.png" width="532">

要求

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("切换独角兽模式:", name: .toggleUnicornMode)
		}
	}
}

也有支持 Cocoa 而非 SwiftUI 的版本。

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

为用户按下所选键盘快捷键时添加监听器。

App.swift

import SwiftUI
import KeyboardShortcuts

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

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

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

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

就是这么简单！✨

您可以在"Example"目录中找到一个完整的示例。

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

Cocoa

使用 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

查看 API 文档。

提示

在 NSMenuItem 中显示已记录的键盘快捷键

<!-- TODO: 当 DocC 支持显示类型扩展时，链接到文档。 -->

参见 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 })

常见问题

它与 MASShortcut 有何不同？

本包：

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

MASShortcut：

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

它与 HotKey 有何不同？

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

为什么这个包导入了 Carbon？这不是已经废弃了吗？

大多数 Carbon API 多年前就被废弃了，但还有一些 Apple 从未提供现代替代品的 API。这包括注册全局键盘快捷键。但是，您不需要担心这个。在废弃这里使用的 Carbon API 之前，Apple 肯定会提供新的 API。

这个包会导致任何权限对话框吗？

不会。

我如何添加一个只在应用处于活动状态时有效的应用特定键盘快捷键？

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

它支持媒体键吗？

不支持，因为这对沙盒应用不起作用。如果您的应用不是沙盒应用，可以使用 MediaKeyTap。

你能支持 CocoaPods 或 Carthage 吗？

不能。但是，即使您通常使用 CocoaPods 或 Carthage，也没有什么阻止您仅为这个包使用 Swift Package Manager。

相关

• Defaults - Swift 风格的现代 UserDefaults
• LaunchAtLogin - 为您的 macOS 应用添加"登录时启动"功能
• 更多……