SwiftUI — SubmitLabel

SubmitLabel 是 SwiftUI 提供的一个枚举类型，用于自定义和改变 TextField 的 Return 键 或 提交按钮的样式。通过设置 submitLabel，你可以控制键盘上的提交按钮显示的标签文字（如 “Done”、“Go”、“Search” 等）以及它的行为。

它成为了 SwiftUI 中的一种优化体验的手段，尤其在处理表单和输入框场景时，让用户清楚键盘操作的目的。

1. SubmitLabel 的定义 #

SubmitLabel 是 SwiftUI 提供的一个枚举（enum），包含以下几个选项：

值描述
.done用于完成任务（如提交表单），键盘上显示“完成”按钮。
.go用于开始某个任务（如跳转或启动操作），键盘上显示“前往”按钮。
.send用于发送信息（如消息或数据），键盘上显示“发送”按钮。
.join用于与某个任务相关的操作（如加入会议），键盘上显示“加入”按钮。
.route用于指导或导航（如获取导航路线），键盘上显示“路线”按钮。
.search用于执行搜索操作，键盘上显示“搜索”按钮。
.return表示简单的换行，在键盘上显示“Return”按钮（默认行为）。
.next移动到下一个输入框，当有多个输入字段时使用“下一项”按钮。
.continue用于继续操作，例如填写表单的下个步骤，键盘上显示“继续”按钮。

2. 基本使用方法 #

submitLabel 通常和 TextField 搭配，以自定义其键盘上的提交按钮。它的配置非常简单，只需在 TextField 上使用 .submitLabel() 修饰符即可。

简单示例 #

以下是一个简单的例子，展示如何改变 TextField 的 Return 键样式，并响应提交按钮的点击：

struct SubmitLabelExample: View {
    @State private var text = ""

    var body: some View {
        VStack {
            TextField("Enter some text", text: $text)
                .textFieldStyle(RoundedBorderTextFieldStyle())
                .padding()
                .submitLabel(.done)  // 设置提交按钮标签为 "完成"
                .onSubmit {
                    print("Text submitted: \(text)") // 响应提交事件
                }

            Text("You entered: \(text)")
                .padding()
        }
    }
}

代码运行结果：

  • TextField 上的键盘显示 Return 键，标签变为 “完成”（Done）。
  • 用户点击 “完成” 后会触发 onSubmit，执行提交逻辑。

不同样式效果对比 #

你可以通过更改 submitLabel 的值，来控制键盘上按钮的标签样式。例如：

TextField("Search something", text: $text)
    .submitLabel(.search) // 显示“搜索”

可选的 SubmitLabel 样式： #

以下是不同 SubmitLabel 的样式和对应的用户场景：

样式场景/用途键盘按钮效果
.done用于完成任务，提交表单、完成输入显示“完成”按钮
.go用于跳转类任务，比如 URL 前往显示“前往”按钮
.search用于执行搜索，比如搜索框应用显示“搜索”按钮
.send发送类显式任务，比如发送文本或邮件、即时消息显示“发送”按钮
.next移动到下个输入框，当有多个输入框需要用户连续填写时使用显示“下一项”按钮
.return默认行为，通常表示换行/返回。显示“Return”按钮（英文）

3. 结合多个输入框 #

在表单中，通常会有多个 TextField。你可以通过 submitLabel 设置当前输入框的行为，同时搭配 .onSubmit 来定义用户提交一个输入框后的事件逻辑，比如跳转到下一个输入框。

示例：表单输入跳转到下一个输入框 #

struct MultiFieldForm: View {
    @State private var firstName = ""
    @State private var lastName = ""
    @FocusState private var focusedField: Field? // 跟踪当前正在被聚焦的输入框

    enum Field {
        case firstName, lastName
    }

    var body: some View {
        Form {
            TextField("First Name", text: $firstName)
                .submitLabel(.next) // 显示“下一项”按钮
                .focused($focusedField, equals: .firstName) // 设置焦点状态
                .onSubmit {
                    focusedField = .lastName // 跳转到“Last Name”
                }

            TextField("Last Name", text: $lastName)
                .submitLabel(.done) // 显示“完成”按钮
                .focused($focusedField, equals: .lastName)
                .onSubmit {
                    print("Form submitted: \(firstName) \(lastName)")
                }
        }
    }
}

工作机制： #

  1. FocusedState 跟踪字段焦点。
  2. 设置 submitLabel(.next) 和 submitLabel(.done)：
    • 实现从姓名字段跳转到姓氏字段的键盘行为。
    • 用户完成输入后最后一个输入框触发提交逻辑。

4. 注意事项 #

  1. Return 键或提交按钮的标签仅是视觉上的改变：

    • 即使 Return 键显示为“搜索”、“发送”等不同名字，其功能都需要结合 onSubmit 实现。submitLabel 本身不会自动绑定提交动作。

  2. 注意兼容性：

    • submitLabel 于 iOS 15.0+ 和 macOS 12.0+ 中引入。如果你的 App 需要兼容更低的 iOS 版本，可以用传统方式代替，如监听 TextField 的绑定值变化或者其他变通方案。

  3. 键盘类型冲突：

    • 如果你同时设置了 keyboardType 和 submitLabel，请确保它们的组合不会产生冲突。例如，keyboardType(.numberPad) 通常没有 Return 键，所以 submitLabel 无效。

5. 嵌套示例：完整用户表单 #

为了展示 SubmitLabel 的更复杂用法，这里有一个完整的用户表单：

struct UserForm: View {
    @State private var username = ""
    @State private var email = ""
    @State private var submitted = false
    @FocusState private var focusedField: Field?

    enum Field {
        case username, email
    }

    var body: some View {
        VStack {
            TextField("Username", text: $username)
                .submitLabel(.next)
                .focused($focusedField, equals: .username)
                .onSubmit {
                    focusedField = .email
                }
                .padding()

            TextField("Email", text: $email)
                .keyboardType(.emailAddress) // 设置键盘类型
                .submitLabel(.done)
                .focused($focusedField, equals: .email)
                .onSubmit {
                    submitted = true
                    print("Form submitted with username: \(username), email: \(email)")
                }
                .padding()

            if submitted {
                Text("User submitted: \(username), \(email)")
            }
        }
        .padding()
        .onAppear {
            focusedField = .username // 默认打开时自动聚焦到用户名
        }
    }
}

6. 总结 #

SubmitLabel 的作用： #

  1. 自定义输入键盘上的提交按钮，明确操作功能（如“完成”、“搜索”、“前往”）。
  2. 提高用户体验，使键盘行为与实际需求一致。
  3. 搭配 onSubmit 实现提交动作逻辑。

适用场景： #

  • 输入框（TextField）的单元格式交互。
  • 表单提交时的按键行为调整。
  • 配合焦点状态 @FocusState 管理输入框切换。
本文共 1791 字，上次修改于 Jan 4, 2025