1. 项目概述与核心价值在iOS应用开发中处理文本输入是一个高频且容易出错的环节。无论是用户注册、登录还是填写复杂的表单我们都需要对用户输入的内容进行格式化比如手机号加空格、信用卡号分组、验证比如邮箱格式、密码强度以及友好的错误提示。更棘手的是当我们在输入过程中动态格式化文本时例如输入“13800138000”时实时显示为“138 0013 8000”光标的定位往往会错乱导致糟糕的用户体验。手动处理这些逻辑不仅代码冗长重复而且极易引入bug。SmartText这个Swift库正是为了解决这些痛点而生。它不是一个简单的工具函数集合而是一套完整的、面向SwiftUI和UIKit双平台的文本处理解决方案。我把它理解为一个“文本输入管家”它把格式化、验证、错误处理和光标定位这些脏活累活都包揽了让我们开发者可以专注于业务逻辑本身。经过在实际项目中的多次使用和打磨我发现它极大地提升了开发效率和代码的可维护性特别是对于那些表单密集型的应用效果立竿见影。2. 核心架构与设计思路拆解2.1 模块化设计格式化器与验证器的分离SmartText最核心的设计哲学是关注点分离。它将文本处理流程清晰地拆分为两个独立且可组合的模块TextFormatter格式化器和TextValidator验证器。TextFormatter 职责是“美化”文本。它只关心文本的表现形式不关心其内容是否正确。例如.phoneNumber格式化器会在用户输入数字时自动插入空格或连字符.stripLeadingAndTrailingSpaces会默默移除用户不小心输入的首尾空格。它的操作是“单向”的旨在提升输入体验和展示一致性。TextValidator 职责是“检查”文本。它只关心文本内容的有效性不改变其表现形式。例如.email()验证器会检查字符串是否符合邮箱格式.minLengthLimited(8)会检查密码长度是否达标。验证器会返回一个包含验证结果成功/失败和可选错误信息的对象。这种分离的好处显而易见。你可以像搭积木一样自由组合它们。比如一个手机号输入框可以先应用.phoneNumber格式化器让输入更顺畅再应用一个自定义的验证器来检查号码是否属于特定运营商。这种灵活性是硬编码逻辑无法比拟的。2.2 光标位置管理的黑科技动态格式化文本时光标乱跳是老大难问题。想象一下你在中间位置删除一个字符整个文本的格式变了光标却跑到了末尾这体验有多崩溃。SmartText内部巧妙地解决了这个问题。它的原理是在每次格式化操作前后会精确计算原始文本用户实际输入的字符与格式化后文本之间的字符映射关系。当UITextField的代理方法如textField(_:shouldChangeCharactersIn:replacementString:)被触发时库会介入获取当前光标位置在格式化后字符串中的索引。根据映射关系计算出这个位置在原始字符串中对应的索引。执行用户实际的插入或删除操作。应用格式化器生成新的字符串。再根据反向映射计算出新字符串中光标应该出现的位置并精准设置。这个过程对开发者完全透明。你只需要声明使用哪个格式化器库就会自动保证光标行为的正确性这是它相比许多同类库的高明之处。2.3 双平台适配SwiftUI与UIKit的统一API苹果生态正在向SwiftUI迁移但大量存量项目仍基于UIKit。SmartText为此提供了两套UI组件但底层核心逻辑是共享的。对于SwiftUI 提供了SmartTextField。这是一个遵循View协议的结构体可以直接在SwiftUI视图中使用并支持通过Binding与状态数据双向绑定。它完美融入了SwiftUI的声明式范式。对于UIKit 提供了UISmartTextField。它是UITextField的子类可以通过传统的.configure(with:)方法进行设置。它通过闭包Closure或委托Delegate的方式来回调事件符合UIKit的命令式编程习惯。尽管UI层实现不同但它们背后的格式化引擎、验证逻辑和光标管理代码是同一套。这意味着你为其中一个平台编写的业务逻辑如自定义验证规则可以很容易地迁移到另一个平台学习成本减半。3. 核心组件深度解析与实操要点3.1 TextFormatter不止于内置更要精通自定义SmartText提供了一系列开箱即用的格式化器例如.email、.phoneNumber、.creditCard等。但在实际项目中标准格式往往不够用。自定义格式化器实战 假设我们需要一个格式化器将用户输入的数字格式化为带有千位分隔符的金额例如“1234567” - “1,234,567”。我们可以通过实现TextFormatter协议来创建。import SmartText struct CurrencyFormatter: TextFormatter { // 此格式化器是幂等的即多次格式化同一字符串结果不变 let isIdentity: Bool false func formatString(_ string: String) - String { // 1. 移除非数字字符 let digits string.filter { $0.isNumber } // 2. 从右向左每三位插入逗号 let reversed String(digits.reversed()) let chunks reversed.chunked(into: 3) let formattedReversed chunks.joined(separator: ,) return String(formattedReversed.reversed()) } } // 扩展String方便分组 extension String { func chunked(into size: Int) - [String] { return stride(from: 0, to: count, by: size).map { let start index(startIndex, offsetBy: $0) let end index(start, offsetBy: size, limitedBy: endIndex) ?? endIndex return String(self[start..end]) } } } // 使用方式 let config SmartTextField.Configuration( placeholder: 金额, textFormatter: .custom(CurrencyFormatter()) )注意 在实现自定义格式化器时必须特别注意isIdentity属性的设置。如果格式化操作是幂等的例如仅去除空格应设为true库会进行优化。对于会改变字符顺序或数量的格式化器如上述金额格式化必须设为false以确保光标位置计算正确。3.2 TextValidator构建复杂的验证逻辑链验证器可以单个使用也可以组成数组形成验证链。验证链会按顺序执行直到第一个验证失败为止。这种设计非常适合实现“先必填再格式最后强度”的渐进式验证。组合验证示例 下面我们为“用户名”创建一个验证链不能为空、长度在3-20字符之间、只能包含字母数字和下划线。let usernameValidator: [TextValidator] [ .notEmpty(errorText: 用户名不能为空), .minMaxLengthLimited(min: 3, max: 20, errorText: 用户名长度需在3-20位之间), .regex(pattern: ^[a-zA-Z0-9_]$, errorText: 用户名只能包含字母、数字和下划线) ] // 在配置中使用 let config SmartTextField.Configuration( placeholder: 用户名, textValidator: usernameValidator )高级技巧异步验证 有时验证需要调用网络API例如检查用户名是否已被注册。SmartText的验证器本质上是同步的但我们可以通过结合Combine框架或异步闭包在UI层实现异步验证的体验。import Combine class ViewModel: ObservableObject { Published var username: String Published var usernameError: String? private var cancellables SetAnyCancellable() init() { $username .debounce(for: .milliseconds(500), scheduler: RunLoop.main) // 防抖 .removeDuplicates() .flatMap { username - AnyPublisherString?, Never in // 先进行本地同步验证 let localValidators: [TextValidator] [.notEmpty(), .minLengthLimited(3)] let result localValidators.validate(username) if let firstError result.first(where: { !$0.isValid }) { // 本地验证失败直接返回错误 return Just(firstError.errorText).eraseToAnyPublisher() } // 本地验证通过发起网络请求进行异步验证 return self.checkUsernameAvailability(username) .map { isAvailable - String? in return isAvailable ? nil : “该用户名已被占用” } .replaceError(with: “网络验证失败请重试”) .eraseToAnyPublisher() } .assign(to: $usernameError) } private func checkUsernameAvailability(_ username: String) - AnyPublisherBool, Error { // 发起网络请求... // 返回一个 Publisher } } // 在SwiftUI中可以将usernameError绑定到SmartTextField的errors参数。3.3 Configuration一站式文本字段配置中心SmartTextField.Configuration或UISmartTextField.Configuration是一个值类型Struct它集中管理了文本字段的所有行为。这种设计模式非常清晰易于复用和测试。关键配置项解析textFormatter 可以接受单个格式化器或一个数组。当传入数组时它们会按顺序执行。这在处理复杂格式时很有用例如先去除空格再格式化电话号。textValidator 同上支持验证链。keyboardTypetextContentType 这些是原生UITextField的属性SmartText将其暴露在配置中。正确设置它们不仅能调出合适的键盘如.emailAddress调出带的键盘还能启用iOS系统的自动填充和强密码建议显著提升用户体验。onEvent/Eventier(UIKit) 这是处理文本字段生命周期事件的枢纽。你可以在这里处理开始编辑、结束编辑、内容改变等事件并访问到格式化、验证的中间结果实现高度自定义的交互逻辑。4. 实战集成从零构建一个登录表单让我们用一个完整的SwiftUI登录表单示例串联起所有知识点。这个表单包含邮箱和密码输入框并实现字段间导航。4.1 定义表单字段与导航逻辑首先我们定义一个枚举来代表表单中的不同字段并实现TextFieldsFormContract协议以支持导航。import SwiftUI import SmartText // 1. 定义表单字段枚举 enum LoginField: Int, TextFieldsFormContract, CaseIterable { case email case password // 2. 实现协议要求的导航方法协议扩展已提供默认实现这里仅为清晰展示 func next() - LoginField? { return LoginField(rawValue: rawValue 1) } func previous() - LoginField? { return LoginField(rawValue: rawValue - 1) } // 3. 为每个字段提供对应的配置 ViewBuilder var fieldView: some View { switch self { case .email: SmartEmailField() case .password: SmartPasswordField() } } } // 4. 构建邮箱输入组件 struct SmartEmailField: View { Binding var text: String Binding var errors: [TextValidationResult] FocusState.Binding var focus: LoginField? var body: some View { SmartTextField( text: $text, errors: $errors, configuration: .init( placeholder: 请输入邮箱, textFormatter: [.email, .stripLeadingAndTrailingSpaces], textValidator: [ .notEmpty(errorText: 邮箱不能为空), .email(errorText: 邮箱格式不正确) ], textContentType: .emailAddress, keyboardType: .emailAddress, // 配置工具栏 inputAccessoryView: UIToolbar( with: .email, focus: $focus ) ) ) .focused($focus, equals: .email) .submitLabel(.next) // iOS 15键盘上的“回车”键显示为“下一步” .onSubmit { // 当用户点击键盘上的“下一步”时焦点切换到密码框 focus .password } } } // 5. 构建密码输入组件类似省略部分重复代码 struct SmartPasswordField: View { Binding var text: String Binding var errors: [TextValidationResult] FocusState.Binding var focus: LoginField? State private var isSecure true var body: some View { HStack { // 使用ZStack和条件修饰符来切换明文/密文显示是一个常见技巧 // 但SmartTextField本身可能不支持动态切换secureTextEntry。 // 更稳健的做法是使用两个独立的SmartTextField根据状态切换显示。 if isSecure { SmartTextField( text: $text, errors: $errors, configuration: .init( placeholder: 请输入密码, textFormatter: .stripLeadingAndTrailingSpaces, textValidator: [ .notEmpty(errorText: 密码不能为空), .minLengthLimited(8, errorText: 密码至少8位), .includesLowerAndUppercase(errorText: 需包含大小写字母) ], textContentType: .password, isSecureTextEntry: true, inputAccessoryView: UIToolbar( with: .password, focus: $focus ) ) ) } else { SmartTextField( text: $text, errors: $errors, configuration: .init( placeholder: 请输入密码, textFormatter: .stripLeadingAndTrailingSpaces, // 明文状态下不需要重复验证绑定同一个errors即可 textValidator: [], inputAccessoryView: UIToolbar( with: .password, focus: $focus ) ) ) } Button(action: { isSecure.toggle() }) { Image(systemName: isSecure ? eye.slash : eye) } } .focused($focus, equals: .password) .submitLabel(.go) // 最后一个字段键盘显示“前往” } }4.2 实现智能工具栏上述代码中引用的UIToolbar(with:focus:)需要实现。这是一个生成带有“上一步”、“下一步”、“完成”按钮工具栏的工厂方法。import SwiftUI extension UIToolbar { static func toolbarFocusType: TextFieldsFormContract( with type: FocusType, focus: FocusStateFocusType?.Binding ) - UIToolbar { let doneButton BlockBarButtonItem( barButtonSystemItem: .done, actionHandler: { // 点击完成收起键盘 UIApplication.shared.sendAction(#selector(UIResponder.resignFirstResponder), to: nil, from: nil, for: nil) focus.wrappedValue nil } ) let prev type.previous() let prevButton BlockBarButtonItem( image: UIImage(systemName: chevron.up)!, actionHandler: { focus.wrappedValue prev } ) prevButton.isEnabled prev ! nil let next type.next() let nextButton BlockBarButtonItem( image: UIImage(systemName: chevron.down)!, actionHandler: { focus.wrappedValue next } ) nextButton.isEnabled next ! nil let flexibleSpace UIBarButtonItem(barButtonSystemItem: .flexibleSpace, target: nil, action: nil) let toolBar UIToolbar(frame: CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 44)) toolBar.items [prevButton, nextButton, flexibleSpace, doneButton] toolBar.sizeToFit() return toolBar } } // BlockBarButtonItem 实现与输入材料中一致此处略4.3 组装主视图最后我们将所有组件组装到主视图中。struct LoginView: View { State private var email State private var password State private var emailErrors: [TextValidationResult] [] State private var passwordErrors: [TextValidationResult] [] FocusState private var focusedField: LoginField? var body: some View { VStack(spacing: 20) { Text(登录) .font(.largeTitle) .padding(.bottom, 30) // 邮箱输入框 VStack(alignment: .leading) { SmartEmailField(text: $email, errors: $emailErrors, focus: $focusedField) .textFieldStyle(.roundedBorder) .autocapitalization(.none) .disableAutocorrection(true) // 显示邮箱验证错误 if let error emailErrors.first(where: { !$0.isValid }) { Text(error.errorText ?? 未知错误) .font(.caption) .foregroundColor(.red) .padding(.leading, 5) } } // 密码输入框 VStack(alignment: .leading) { SmartPasswordField(text: $password, errors: $passwordErrors, focus: $focusedField) .textFieldStyle(.roundedBorder) .autocapitalization(.none) .disableAutocorrection(true) // 显示密码验证错误 if let error passwordErrors.first(where: { !$0.isValid }) { Text(error.errorText ?? 未知错误) .font(.caption) .foregroundColor(.red) .padding(.leading, 5) } } Button(登录) { // 提交前可以手动触发一次最终验证 validateAll() if emailErrors.isEmpty passwordErrors.isEmpty { // 执行登录网络请求... print(开始登录...) } } .buttonStyle(.borderedProminent) .disabled(!formIsValid) // 根据表单有效性禁用按钮 .padding(.top, 20) Spacer() } .padding() .onAppear { // 页面出现时自动聚焦到邮箱框 DispatchQueue.main.asyncAfter(deadline: .now() 0.5) { focusedField .email } } } // 计算属性判断整个表单是否有效 private var formIsValid: Bool { let emailValid emailErrors.allSatisfy { $0.isValid } let passwordValid passwordErrors.allSatisfy { $0.isValid } return !email.isEmpty !password.isEmpty emailValid passwordValid } // 手动验证所有字段 private func validateAll() { // SmartText的验证是实时的errors状态会自动更新。 // 此方法可用于提交前的最终检查或触发错误UI更新。 // 实际上由于errors是State绑定UI会自动响应。 } }5. 常见问题排查与性能优化实录在实际集成SmartText的过程中我遇到并解决了一些典型问题这里分享出来供大家参考。5.1 光标跳动或位置错误问题现象 使用自定义格式化器时在特定输入场景下如快速删除、粘贴光标会跳到末尾或错误位置。排查与解决检查isIdentity属性 这是最常见的原因。如果你的格式化器会改变字符串长度如添加分隔符或字符顺序必须将isIdentity设为false。设为true仅适用于修剪空格、大小写转换这类不改变“字符索引映射关系”的操作。审查格式化逻辑 确保你的formatString(_:)方法是纯函数。即相同的输入永远产生相同的输出且没有副作用。不要在方法内部依赖或修改外部状态。处理边界情况 特别是当输入字符串为空或格式化后为空时。确保你的逻辑能妥善处理这些情况返回合理的字符串。5.2 验证逻辑不触发或错误信息不更新问题现象 文本已经明显不符合规则如空输入但绑定的errors数组没有变化UI不显示错误。排查与解决确认绑定关系 在SwiftUI中确保State或Published属性与SmartTextField的errors参数使用了正确的$符号进行双向绑定。在UIKit中确认设置了UISmartTextField的validationHandler闭包。验证器的执行时机 默认情况下验证可能在文本变化时、编辑结束时或手动调用时触发。检查配置。在SwiftUI中验证通常是实时的。检查验证器组合 如果使用了验证器数组它们是短路执行的。例如如果.notEmpty失败了后面的.email验证器就不会执行。这符合逻辑但需要你了解。线程问题 确保验证逻辑是同步且快速的。如果必须在验证器中执行耗时操作应避免需要确保UI更新回到主线程。5.3 与现有代码或第三方库的集成冲突问题现象 项目中原有的UITextFieldDelegate方法不调用了或者某些第三方库如IQKeyboardManager的行为异常。排查与解决代理链UISmartTextField内部重写了delegate属性以插入自己的逻辑。如果你还需要设置自己的代理可以使用其提供的Eventier闭包onEvent来处理事件这是首选方式。如果必须使用传统代理请查阅SmartText文档看是否提供了设置额外代理的方法有些库会提供externalDelegate这样的属性。IQKeyboardManager 这个流行的库也会干预UITextField。确保SmartText的配置如inputAccessoryView不会与IQKeyboardManager的工具栏冲突。通常的解决方法是在SmartText的配置中设置工具栏并禁用IQKeyboardManager为特定字段添加工具栏的功能。自定义UITextField子类 如果你的项目已有复杂的UITextField子类直接继承UISmartTextField可能会丢失原有功能。考虑使用组合而非继承将UISmartTextField作为视图的一个私有属性并对外暴露必要的接口。5.4 性能考量与优化建议对于绝大多数表单场景SmartText的性能开销可以忽略不计。但在极端情况下如一个单元格内有大量可编辑的、使用复杂正则验证的文本字段仍需注意简化格式化器 避免在formatString方法中进行复杂的字符串操作或正则匹配。如果必须考虑对结果进行缓存。慎用实时验证 对于非常复杂的验证如调用网络请求不要将其放在同步验证器中。采用前面提到的“本地同步验证 异步网络验证”模式并加入防抖Debounce机制。重用Configuration 如果多个字段使用相同的配置例如多个电话号码输入框务必在外部创建并重用同一个Configuration实例而不是在每个视图的初始化器中内联创建。这能避免不必要的重复计算和内存分配。列表中的使用 在List或ForEach中大量使用SmartTextField时确保为其设置稳定的identifier并考虑在非可见区域暂停过于频繁的验证操作以提升滚动流畅度。SmartText库将iOS文本输入处理的复杂性封装在了一个优雅的API之下。通过理解其格式化与验证分离的设计思想掌握自定义组件的创建方法并善用其SwiftUI/UIKit双平台支持你可以为应用构建出体验一致、健壮可靠的文本输入功能。记住好的工具能节省时间但深入理解其原理才能让你在遇到问题时游刃有余。
SmartText：iOS文本输入格式化与验证的Swift解决方案
发布时间：2026/7/9 13:55:14
1. 项目概述与核心价值在iOS应用开发中处理文本输入是一个高频且容易出错的环节。无论是用户注册、登录还是填写复杂的表单我们都需要对用户输入的内容进行格式化比如手机号加空格、信用卡号分组、验证比如邮箱格式、密码强度以及友好的错误提示。更棘手的是当我们在输入过程中动态格式化文本时例如输入“13800138000”时实时显示为“138 0013 8000”光标的定位往往会错乱导致糟糕的用户体验。手动处理这些逻辑不仅代码冗长重复而且极易引入bug。SmartText这个Swift库正是为了解决这些痛点而生。它不是一个简单的工具函数集合而是一套完整的、面向SwiftUI和UIKit双平台的文本处理解决方案。我把它理解为一个“文本输入管家”它把格式化、验证、错误处理和光标定位这些脏活累活都包揽了让我们开发者可以专注于业务逻辑本身。经过在实际项目中的多次使用和打磨我发现它极大地提升了开发效率和代码的可维护性特别是对于那些表单密集型的应用效果立竿见影。2. 核心架构与设计思路拆解2.1 模块化设计格式化器与验证器的分离SmartText最核心的设计哲学是关注点分离。它将文本处理流程清晰地拆分为两个独立且可组合的模块TextFormatter格式化器和TextValidator验证器。TextFormatter 职责是“美化”文本。它只关心文本的表现形式不关心其内容是否正确。例如.phoneNumber格式化器会在用户输入数字时自动插入空格或连字符.stripLeadingAndTrailingSpaces会默默移除用户不小心输入的首尾空格。它的操作是“单向”的旨在提升输入体验和展示一致性。TextValidator 职责是“检查”文本。它只关心文本内容的有效性不改变其表现形式。例如.email()验证器会检查字符串是否符合邮箱格式.minLengthLimited(8)会检查密码长度是否达标。验证器会返回一个包含验证结果成功/失败和可选错误信息的对象。这种分离的好处显而易见。你可以像搭积木一样自由组合它们。比如一个手机号输入框可以先应用.phoneNumber格式化器让输入更顺畅再应用一个自定义的验证器来检查号码是否属于特定运营商。这种灵活性是硬编码逻辑无法比拟的。2.2 光标位置管理的黑科技动态格式化文本时光标乱跳是老大难问题。想象一下你在中间位置删除一个字符整个文本的格式变了光标却跑到了末尾这体验有多崩溃。SmartText内部巧妙地解决了这个问题。它的原理是在每次格式化操作前后会精确计算原始文本用户实际输入的字符与格式化后文本之间的字符映射关系。当UITextField的代理方法如textField(_:shouldChangeCharactersIn:replacementString:)被触发时库会介入获取当前光标位置在格式化后字符串中的索引。根据映射关系计算出这个位置在原始字符串中对应的索引。执行用户实际的插入或删除操作。应用格式化器生成新的字符串。再根据反向映射计算出新字符串中光标应该出现的位置并精准设置。这个过程对开发者完全透明。你只需要声明使用哪个格式化器库就会自动保证光标行为的正确性这是它相比许多同类库的高明之处。2.3 双平台适配SwiftUI与UIKit的统一API苹果生态正在向SwiftUI迁移但大量存量项目仍基于UIKit。SmartText为此提供了两套UI组件但底层核心逻辑是共享的。对于SwiftUI 提供了SmartTextField。这是一个遵循View协议的结构体可以直接在SwiftUI视图中使用并支持通过Binding与状态数据双向绑定。它完美融入了SwiftUI的声明式范式。对于UIKit 提供了UISmartTextField。它是UITextField的子类可以通过传统的.configure(with:)方法进行设置。它通过闭包Closure或委托Delegate的方式来回调事件符合UIKit的命令式编程习惯。尽管UI层实现不同但它们背后的格式化引擎、验证逻辑和光标管理代码是同一套。这意味着你为其中一个平台编写的业务逻辑如自定义验证规则可以很容易地迁移到另一个平台学习成本减半。3. 核心组件深度解析与实操要点3.1 TextFormatter不止于内置更要精通自定义SmartText提供了一系列开箱即用的格式化器例如.email、.phoneNumber、.creditCard等。但在实际项目中标准格式往往不够用。自定义格式化器实战 假设我们需要一个格式化器将用户输入的数字格式化为带有千位分隔符的金额例如“1234567” - “1,234,567”。我们可以通过实现TextFormatter协议来创建。import SmartText struct CurrencyFormatter: TextFormatter { // 此格式化器是幂等的即多次格式化同一字符串结果不变 let isIdentity: Bool false func formatString(_ string: String) - String { // 1. 移除非数字字符 let digits string.filter { $0.isNumber } // 2. 从右向左每三位插入逗号 let reversed String(digits.reversed()) let chunks reversed.chunked(into: 3) let formattedReversed chunks.joined(separator: ,) return String(formattedReversed.reversed()) } } // 扩展String方便分组 extension String { func chunked(into size: Int) - [String] { return stride(from: 0, to: count, by: size).map { let start index(startIndex, offsetBy: $0) let end index(start, offsetBy: size, limitedBy: endIndex) ?? endIndex return String(self[start..end]) } } } // 使用方式 let config SmartTextField.Configuration( placeholder: 金额, textFormatter: .custom(CurrencyFormatter()) )注意 在实现自定义格式化器时必须特别注意isIdentity属性的设置。如果格式化操作是幂等的例如仅去除空格应设为true库会进行优化。对于会改变字符顺序或数量的格式化器如上述金额格式化必须设为false以确保光标位置计算正确。3.2 TextValidator构建复杂的验证逻辑链验证器可以单个使用也可以组成数组形成验证链。验证链会按顺序执行直到第一个验证失败为止。这种设计非常适合实现“先必填再格式最后强度”的渐进式验证。组合验证示例 下面我们为“用户名”创建一个验证链不能为空、长度在3-20字符之间、只能包含字母数字和下划线。let usernameValidator: [TextValidator] [ .notEmpty(errorText: 用户名不能为空), .minMaxLengthLimited(min: 3, max: 20, errorText: 用户名长度需在3-20位之间), .regex(pattern: ^[a-zA-Z0-9_]$, errorText: 用户名只能包含字母、数字和下划线) ] // 在配置中使用 let config SmartTextField.Configuration( placeholder: 用户名, textValidator: usernameValidator )高级技巧异步验证 有时验证需要调用网络API例如检查用户名是否已被注册。SmartText的验证器本质上是同步的但我们可以通过结合Combine框架或异步闭包在UI层实现异步验证的体验。import Combine class ViewModel: ObservableObject { Published var username: String Published var usernameError: String? private var cancellables SetAnyCancellable() init() { $username .debounce(for: .milliseconds(500), scheduler: RunLoop.main) // 防抖 .removeDuplicates() .flatMap { username - AnyPublisherString?, Never in // 先进行本地同步验证 let localValidators: [TextValidator] [.notEmpty(), .minLengthLimited(3)] let result localValidators.validate(username) if let firstError result.first(where: { !$0.isValid }) { // 本地验证失败直接返回错误 return Just(firstError.errorText).eraseToAnyPublisher() } // 本地验证通过发起网络请求进行异步验证 return self.checkUsernameAvailability(username) .map { isAvailable - String? in return isAvailable ? nil : “该用户名已被占用” } .replaceError(with: “网络验证失败请重试”) .eraseToAnyPublisher() } .assign(to: $usernameError) } private func checkUsernameAvailability(_ username: String) - AnyPublisherBool, Error { // 发起网络请求... // 返回一个 Publisher } } // 在SwiftUI中可以将usernameError绑定到SmartTextField的errors参数。3.3 Configuration一站式文本字段配置中心SmartTextField.Configuration或UISmartTextField.Configuration是一个值类型Struct它集中管理了文本字段的所有行为。这种设计模式非常清晰易于复用和测试。关键配置项解析textFormatter 可以接受单个格式化器或一个数组。当传入数组时它们会按顺序执行。这在处理复杂格式时很有用例如先去除空格再格式化电话号。textValidator 同上支持验证链。keyboardTypetextContentType 这些是原生UITextField的属性SmartText将其暴露在配置中。正确设置它们不仅能调出合适的键盘如.emailAddress调出带的键盘还能启用iOS系统的自动填充和强密码建议显著提升用户体验。onEvent/Eventier(UIKit) 这是处理文本字段生命周期事件的枢纽。你可以在这里处理开始编辑、结束编辑、内容改变等事件并访问到格式化、验证的中间结果实现高度自定义的交互逻辑。4. 实战集成从零构建一个登录表单让我们用一个完整的SwiftUI登录表单示例串联起所有知识点。这个表单包含邮箱和密码输入框并实现字段间导航。4.1 定义表单字段与导航逻辑首先我们定义一个枚举来代表表单中的不同字段并实现TextFieldsFormContract协议以支持导航。import SwiftUI import SmartText // 1. 定义表单字段枚举 enum LoginField: Int, TextFieldsFormContract, CaseIterable { case email case password // 2. 实现协议要求的导航方法协议扩展已提供默认实现这里仅为清晰展示 func next() - LoginField? { return LoginField(rawValue: rawValue 1) } func previous() - LoginField? { return LoginField(rawValue: rawValue - 1) } // 3. 为每个字段提供对应的配置 ViewBuilder var fieldView: some View { switch self { case .email: SmartEmailField() case .password: SmartPasswordField() } } } // 4. 构建邮箱输入组件 struct SmartEmailField: View { Binding var text: String Binding var errors: [TextValidationResult] FocusState.Binding var focus: LoginField? var body: some View { SmartTextField( text: $text, errors: $errors, configuration: .init( placeholder: 请输入邮箱, textFormatter: [.email, .stripLeadingAndTrailingSpaces], textValidator: [ .notEmpty(errorText: 邮箱不能为空), .email(errorText: 邮箱格式不正确) ], textContentType: .emailAddress, keyboardType: .emailAddress, // 配置工具栏 inputAccessoryView: UIToolbar( with: .email, focus: $focus ) ) ) .focused($focus, equals: .email) .submitLabel(.next) // iOS 15键盘上的“回车”键显示为“下一步” .onSubmit { // 当用户点击键盘上的“下一步”时焦点切换到密码框 focus .password } } } // 5. 构建密码输入组件类似省略部分重复代码 struct SmartPasswordField: View { Binding var text: String Binding var errors: [TextValidationResult] FocusState.Binding var focus: LoginField? State private var isSecure true var body: some View { HStack { // 使用ZStack和条件修饰符来切换明文/密文显示是一个常见技巧 // 但SmartTextField本身可能不支持动态切换secureTextEntry。 // 更稳健的做法是使用两个独立的SmartTextField根据状态切换显示。 if isSecure { SmartTextField( text: $text, errors: $errors, configuration: .init( placeholder: 请输入密码, textFormatter: .stripLeadingAndTrailingSpaces, textValidator: [ .notEmpty(errorText: 密码不能为空), .minLengthLimited(8, errorText: 密码至少8位), .includesLowerAndUppercase(errorText: 需包含大小写字母) ], textContentType: .password, isSecureTextEntry: true, inputAccessoryView: UIToolbar( with: .password, focus: $focus ) ) ) } else { SmartTextField( text: $text, errors: $errors, configuration: .init( placeholder: 请输入密码, textFormatter: .stripLeadingAndTrailingSpaces, // 明文状态下不需要重复验证绑定同一个errors即可 textValidator: [], inputAccessoryView: UIToolbar( with: .password, focus: $focus ) ) ) } Button(action: { isSecure.toggle() }) { Image(systemName: isSecure ? eye.slash : eye) } } .focused($focus, equals: .password) .submitLabel(.go) // 最后一个字段键盘显示“前往” } }4.2 实现智能工具栏上述代码中引用的UIToolbar(with:focus:)需要实现。这是一个生成带有“上一步”、“下一步”、“完成”按钮工具栏的工厂方法。import SwiftUI extension UIToolbar { static func toolbarFocusType: TextFieldsFormContract( with type: FocusType, focus: FocusStateFocusType?.Binding ) - UIToolbar { let doneButton BlockBarButtonItem( barButtonSystemItem: .done, actionHandler: { // 点击完成收起键盘 UIApplication.shared.sendAction(#selector(UIResponder.resignFirstResponder), to: nil, from: nil, for: nil) focus.wrappedValue nil } ) let prev type.previous() let prevButton BlockBarButtonItem( image: UIImage(systemName: chevron.up)!, actionHandler: { focus.wrappedValue prev } ) prevButton.isEnabled prev ! nil let next type.next() let nextButton BlockBarButtonItem( image: UIImage(systemName: chevron.down)!, actionHandler: { focus.wrappedValue next } ) nextButton.isEnabled next ! nil let flexibleSpace UIBarButtonItem(barButtonSystemItem: .flexibleSpace, target: nil, action: nil) let toolBar UIToolbar(frame: CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 44)) toolBar.items [prevButton, nextButton, flexibleSpace, doneButton] toolBar.sizeToFit() return toolBar } } // BlockBarButtonItem 实现与输入材料中一致此处略4.3 组装主视图最后我们将所有组件组装到主视图中。struct LoginView: View { State private var email State private var password State private var emailErrors: [TextValidationResult] [] State private var passwordErrors: [TextValidationResult] [] FocusState private var focusedField: LoginField? var body: some View { VStack(spacing: 20) { Text(登录) .font(.largeTitle) .padding(.bottom, 30) // 邮箱输入框 VStack(alignment: .leading) { SmartEmailField(text: $email, errors: $emailErrors, focus: $focusedField) .textFieldStyle(.roundedBorder) .autocapitalization(.none) .disableAutocorrection(true) // 显示邮箱验证错误 if let error emailErrors.first(where: { !$0.isValid }) { Text(error.errorText ?? 未知错误) .font(.caption) .foregroundColor(.red) .padding(.leading, 5) } } // 密码输入框 VStack(alignment: .leading) { SmartPasswordField(text: $password, errors: $passwordErrors, focus: $focusedField) .textFieldStyle(.roundedBorder) .autocapitalization(.none) .disableAutocorrection(true) // 显示密码验证错误 if let error passwordErrors.first(where: { !$0.isValid }) { Text(error.errorText ?? 未知错误) .font(.caption) .foregroundColor(.red) .padding(.leading, 5) } } Button(登录) { // 提交前可以手动触发一次最终验证 validateAll() if emailErrors.isEmpty passwordErrors.isEmpty { // 执行登录网络请求... print(开始登录...) } } .buttonStyle(.borderedProminent) .disabled(!formIsValid) // 根据表单有效性禁用按钮 .padding(.top, 20) Spacer() } .padding() .onAppear { // 页面出现时自动聚焦到邮箱框 DispatchQueue.main.asyncAfter(deadline: .now() 0.5) { focusedField .email } } } // 计算属性判断整个表单是否有效 private var formIsValid: Bool { let emailValid emailErrors.allSatisfy { $0.isValid } let passwordValid passwordErrors.allSatisfy { $0.isValid } return !email.isEmpty !password.isEmpty emailValid passwordValid } // 手动验证所有字段 private func validateAll() { // SmartText的验证是实时的errors状态会自动更新。 // 此方法可用于提交前的最终检查或触发错误UI更新。 // 实际上由于errors是State绑定UI会自动响应。 } }5. 常见问题排查与性能优化实录在实际集成SmartText的过程中我遇到并解决了一些典型问题这里分享出来供大家参考。5.1 光标跳动或位置错误问题现象 使用自定义格式化器时在特定输入场景下如快速删除、粘贴光标会跳到末尾或错误位置。排查与解决检查isIdentity属性 这是最常见的原因。如果你的格式化器会改变字符串长度如添加分隔符或字符顺序必须将isIdentity设为false。设为true仅适用于修剪空格、大小写转换这类不改变“字符索引映射关系”的操作。审查格式化逻辑 确保你的formatString(_:)方法是纯函数。即相同的输入永远产生相同的输出且没有副作用。不要在方法内部依赖或修改外部状态。处理边界情况 特别是当输入字符串为空或格式化后为空时。确保你的逻辑能妥善处理这些情况返回合理的字符串。5.2 验证逻辑不触发或错误信息不更新问题现象 文本已经明显不符合规则如空输入但绑定的errors数组没有变化UI不显示错误。排查与解决确认绑定关系 在SwiftUI中确保State或Published属性与SmartTextField的errors参数使用了正确的$符号进行双向绑定。在UIKit中确认设置了UISmartTextField的validationHandler闭包。验证器的执行时机 默认情况下验证可能在文本变化时、编辑结束时或手动调用时触发。检查配置。在SwiftUI中验证通常是实时的。检查验证器组合 如果使用了验证器数组它们是短路执行的。例如如果.notEmpty失败了后面的.email验证器就不会执行。这符合逻辑但需要你了解。线程问题 确保验证逻辑是同步且快速的。如果必须在验证器中执行耗时操作应避免需要确保UI更新回到主线程。5.3 与现有代码或第三方库的集成冲突问题现象 项目中原有的UITextFieldDelegate方法不调用了或者某些第三方库如IQKeyboardManager的行为异常。排查与解决代理链UISmartTextField内部重写了delegate属性以插入自己的逻辑。如果你还需要设置自己的代理可以使用其提供的Eventier闭包onEvent来处理事件这是首选方式。如果必须使用传统代理请查阅SmartText文档看是否提供了设置额外代理的方法有些库会提供externalDelegate这样的属性。IQKeyboardManager 这个流行的库也会干预UITextField。确保SmartText的配置如inputAccessoryView不会与IQKeyboardManager的工具栏冲突。通常的解决方法是在SmartText的配置中设置工具栏并禁用IQKeyboardManager为特定字段添加工具栏的功能。自定义UITextField子类 如果你的项目已有复杂的UITextField子类直接继承UISmartTextField可能会丢失原有功能。考虑使用组合而非继承将UISmartTextField作为视图的一个私有属性并对外暴露必要的接口。5.4 性能考量与优化建议对于绝大多数表单场景SmartText的性能开销可以忽略不计。但在极端情况下如一个单元格内有大量可编辑的、使用复杂正则验证的文本字段仍需注意简化格式化器 避免在formatString方法中进行复杂的字符串操作或正则匹配。如果必须考虑对结果进行缓存。慎用实时验证 对于非常复杂的验证如调用网络请求不要将其放在同步验证器中。采用前面提到的“本地同步验证 异步网络验证”模式并加入防抖Debounce机制。重用Configuration 如果多个字段使用相同的配置例如多个电话号码输入框务必在外部创建并重用同一个Configuration实例而不是在每个视图的初始化器中内联创建。这能避免不必要的重复计算和内存分配。列表中的使用 在List或ForEach中大量使用SmartTextField时确保为其设置稳定的identifier并考虑在非可见区域暂停过于频繁的验证操作以提升滚动流畅度。SmartText库将iOS文本输入处理的复杂性封装在了一个优雅的API之下。通过理解其格式化与验证分离的设计思想掌握自定义组件的创建方法并善用其SwiftUI/UIKit双平台支持你可以为应用构建出体验一致、健壮可靠的文本输入功能。记住好的工具能节省时间但深入理解其原理才能让你在遇到问题时游刃有余。
