SwiftUI — KeyboardShortcut

你提到的 cancelAction: KeyboardShortcut 是 SwiftUI 中的一个静态属性，它定义了标准化的键盘快捷键（KeyboardShortcut），用于取消当前操作或关闭弹框（prompt）。这个属性主要用于 macOS 和支持键盘交互的平台（比如 iPad 上连接键盘，或 macOS Catalyst）。

这与我们在上面讨论的“手动定义一个闭包 cancelAction”是完全不同的概念。cancelAction 在这里指向的是一个标准的键盘快捷键，而不是一个行为逻辑。

1. 官方文档中 cancelAction 的定义 #

文档定义中提到的内容如下：

static let cancelAction: KeyboardShortcut

  • 类型：
    KeyboardShortcut 是 SwiftUI 中的一个结构体，用于定义键盘输入的快捷操作。

  • 功能：
    这个快捷键默认设定为 Escape (⎋) 键，用于触发“取消操作”或关闭当前上下文界面。例如，你在某个弹窗、模态视图或表单输入框中，按下 Escape 键，即相当于“取消”或“关闭”。

  • 适用场景：

  • Mac 应用（macOS），键盘的取消操作通常通过 Escape (⎋) 实现。

  • Catalyst 应用（Mac Catalyst），也是标准快捷键行为。

  • visionOS 和 iPadOS 中，当设备使用物理键盘时同样可以使用这个快捷键。

2. 示例用法 #

在 SwiftUI 中，你可以使用 cancelAction 来绑定 Escape 键的快捷操作，与按钮或表单中的取消操作逻辑相结合。

以下是如何使用 cancelAction 的示例：

2.1. 使用 KeyboardShortcut.cancelAction 与按钮绑定 #

示例代码：

import SwiftUI

struct CancelKeyboardShortcutExample: View {
    @State private var showPrompt = false

    var body: some View {
        VStack {
            Button("Show Prompt") {
                showPrompt = true
            }

            .sheet(isPresented: $showPrompt) {
                VStack {
                    Text("This is a prompt")
                    
                    // 提供一个 "取消操作" 的按钮
                    Button("Cancel") {
                        showPrompt = false
                    }
                    // 绑定键盘快捷键 "ESC" 来取消
                    .keyboardShortcut(.cancelAction)
                }
                .frame(width: 300, height: 200)
            }
        }
    }
}

功能：

  • 添加了一个快捷键（KeyboardShortcut.cancelAction）绑定到“取消”按钮。
  • 在 macOS 或其他支持 Escape 按键的设备上，用户可以按下 ESC 键，自动触发 “取消操作”，关闭弹窗。

2.2. 在自定义视图中全局监听快捷键 #

如果你希望 KeyboardShortcut.cancelAction 直接作为页面的取消键，可以这样使用：

示例代码：

struct CancelGlobalExample: View {
    @State private var isCancelled = false

    var body: some View {
        VStack {
            Text(isCancelled ? "Cancelled!" : "Press ESC to Cancel")
                .font(.largeTitle)
            
            Button("Simulate Cancel") {
                isCancelled = true
            }
            // 将这个按钮使用标准的 "Cancel Action"
            .keyboardShortcut(.cancelAction)
        }
        .padding()
    }
}

在这里，你可以通过全局按 ESC 键触发取消动作，并更新状态。

2.3. 在复杂应用中统一定义取消逻辑 #

当应用中有多个地方都有“取消”操作时，你可以利用 .cancelAction 快捷键提高一致性，与具体逻辑绑定。

示例代码：

struct CancelInProgressAction: View {
    @State private var inProgress = true // 模拟一个任务状态

    var body: some View {
        VStack {
            if inProgress {
                ProgressView("Task is in progress...")
            } else {
                Text("Task has been cancelled.")
            }

            // 提供"取消任务"的按钮
            Button("Cancel Task") {
                inProgress = false
            }
            // 按 ESC 键时触发取消行为
            .keyboardShortcut(.cancelAction)
        }
        .padding()
    }
}

用户可以通过点击按钮 或按 ESC 键 来取消任务，简单明快。

3. cancelAction 的适用场景 #

适合的使用场景 #

cancelAction 的快捷键适用于以下情况：

  1. 模态视图（sheet）的关闭
  • 当用户看到一个模态对话框时，Escape 键通常用来关闭对话框。
  • 示例：登录页面、提示弹窗等。
  1. 表单的取消
  • 当用户在填写表单数据时，按下 ESC 键可以取消数据输入并恢复默认状态。
  • 示例：用于放弃表单编辑。
  1. 非模态流程中的中断
  • 比如任务执行、下载处理或类似进度任务，允许用户按 ESC 键取消任务。
  1. 统一的用户体验
  • 在 macOS、iPadOS 或 visionOS 等支持键盘的环境中，使用 cancelAction 统一处理键盘快捷键，有助于在整个系统中提供一致的用户体验。

4. 示例背后的 API 和 SwiftUI 文档解析 #

4.1. KeyboardShortcut 的基本结构： #

  • KeyboardShortcut 是 SwiftUI 使用的键盘绑定结构体。你可以用它定义按键（如 Esc, Command+Q, Option+Key, 等）。
  • 苹果提供的一些 预定义键盘快捷键，如 .cancelAction，可以直接绑定到用户界面控件上。

相关文档：KeyboardShortcut - Apple Documentation

4.2. 取消快捷键的预定义： #

  • .cancelAction 是 KeyboardShortcut 的静态属性。
  • 为 cancelAction 提供了标准化行为，设定为 Escape 键 (⎋)，无修饰键符号。

5. 总结 #

static let cancelAction: KeyboardShortcut 是 SwiftUI 提供的一个标准快捷键，用于取消当前操作或关闭某些 UI 组件，主要作用如下：

  1. 默认与键盘的 ESC 键绑定，支持跨平台���标准化取消行为（适用于 macOS、iPad 附带键盘等场景）。
  2. 是 KeyboardShortcut 的一种简化方案，开发者可以用它来替代自定义的快捷键定义（无需手动指定键码和修饰键）。
  3. 在不同的控件中，与 SwiftUI 的 .sheet、.alert 或单独的 Button 等控件结合，实现一致的“取消”交互体验。
本文共 1562 字，上次修改于 Jan 4, 2025