RSFormView 2.1.6

RSFormView 2.1.6

×

由 German Stabile 维护。

RSFormView 2.1.6

Build Status Maintainability Test Coverage License

RSFormView

它是做什么的？

RSFormView 是一个库，它帮助您在几分钟内构建可完全定制的表单用于数据输入。

安装

RSFormView 可通过 CocoaPods 获取。要安装它，只需将以下行添加到 Podfile 中

pod 'RSFormView', '~> 2.1.1'

用法

  1. 将 FormView 添加到您的视图控制器中，您可以这样做，无论是通过编程方式还是在 Storyboards 中。

编程方式

let formView = FormView(frame: frame)
view.addSubview(formView)

Storyboards：将 UIView 添加到您的视图控制器中，并将类名更改为 FormView，模块更改为 RSFormView。

  1. 将您的视图控制器设置为 FormView 代理
import RSFormView

class YourViewController: UIViewController, FormViewDelegate { ... }

并实现

func didUpdateFields(in formView: FormView, allFieldsValid: Bool)

此函数将在用户在任何表单中输入数据时被调用，因此这是一个更新依赖输入数据的其他视图的好地方。

  1. 将您的视图控制器设置为 FormView 代理
formView.delegate = self
  1. 设置 FormViewModel 到您的 formView

FormViewModel 可以是任何实现了 FormViewModel 协议的类。为了使一个类实现 FormViewModel 协议，您只需定义一个 FormItem 数组。每个 FormItem 将确定表单中每个文本字段的特性和验证。默认情况下，RSFormView 提供以下 FormItem 子类

  • TextCellItem：单个标签或“部分标题”
  • TextFieldCellItem：一个单项文本字段。
  • TwoTextFieldCellItem：两个文本字段。

您可以根据需要添加自己的FormItem，更多信息请参阅自定义项部分。

字段类型

fieldType是FormField的一个属性，用于确定所表示文本字段的这种行为。

情况

  • 电子邮件：当字段被选中时，将显示电子邮件键盘，并验证文本输入是否为电子邮件格式
  • 日期：当字段被选中时，将显示本地日期选择器，并验证输入不为空
  • 整数：当字段被选中时，将显示数字键盘，并验证文本输入可以转换为Int类型
  • 双精度浮点数：当字段被选中时，将显示小数键盘，并验证文本输入可以转换为Double类型，可以通过此枚举情况的参数传递最大小数位数
  • 密码：在UI中掩盖文本输入，并验证文本输入不为空
  • 美式电话：将斜杠 （111-111-1111）装饰到文本输入，并根据有效的美式电话号码格式验证文本输入

查看字段类型定义了解更多受支持的案例。

验证类型

validationType是FormField的一个属性，用于确定所表示文本字段的验证行为。不同的字段类型提供了不同的默认验证，但是可以通过设置一个ValidationType来覆盖验证。

情况

  • 非空：如果文本输入为空，将标记字段无效
  • 无：不执行任何验证，除非手动标记为无效，字段将始终不标记为无效
  • 整数：如果文本输入不是整数，则标记字段无效
  • 双精度浮点数：如果文本输入不是双精度浮点数，则标记字段无效，最多两位小数
  • 美州州名：验证文本输入是否匹配美国各州名称或缩写
  • 自定义：为该案例提供一个包含自定义验证的块

自定义示例

yourFormField.validationType = .custom(evaluator: { [weak self] updatedValue in
  let otherFormField = self?.fields().first { $0.name == "OtherFormFieldName" }
  let otherFormFieldValue = otherFormField?.value ?? ""
  return updatedValue.count > 5 && updatedValue == otherFormFieldValue
})
//In this example the field will be marked valid if the text entry has mora characters than 5 and its text entry is the same as the field with identifier "OtherTextFieldName"

表单项

一个FormItem定义了行的基本行为，然后通过子类化它来专门化。您不应直接使用FormItem的实例，RSFormView提供了以下FormItem的内置子类

TextCellItem：单个标签，或“节标题”TextFieldCellItem：单个文本字段。TwoTextFieldCellItem：两个文本字段。

  1. 一个文本字段项
let birthdateField = FormField(name: "Birthdate field", // the identifier of the field, use this to collect the data later
                               initialValue: "", // the inital value of the field, if its in a date formate it will auto select that date in the picker
                               placeholder: FieldName.birthdate.rawValue, // The placeholder when there's no value and text field title when there is
                               fieldType: .date, //The Type of the field, .date will present a native picker view when tapping on the text field
                               isValid: false, //The initial validation state. The field won't be marked invalid until data is entered or removed
                               errorMessage: "Please enter a birthdate") //The error message to be displayed when the entry is invalid or empty

let formItem = TextFieldCellItem(with: birthdateField)
  1. 两个文本字段项
let firstFormField = FormField(...)
let secondFormField = FormField(...)

let formItem = TwoTextFieldCellItem(firstField: firstFormField, secondField: secondFormField)
  1. 文本单元格项（可用作节标题或文本提示）
let attributedString = NSAttributedString(...)
let formItem = TextCellItem()
formItem.attributedString = attributedString

为了方便测试 Pod，我们提供了 BasaicFormViewModel 类。它接收一个项目列表并显示表单而不需要额外设置。

//  birthdateField defined above
        
formView.viewModel = BasicFormViewModel(items: [TextFieldCellItem(with: birthdateField)])

您可以在本存储库的 VanillaExample 文件夹中看到这种方法。

  1. 配置您的表单外观

创建一个 FormConfigurator，更改任何您需要的颜色或字体，并将其设置到您的表单视图中。

let configurator = FormConfigurator()
configurator.textColor = UIColor.lightGray
configurator.validTitleColor = UIColor.blue
configurator.titleFont = UIFont.systemFont(withSize: 13)
...
formView.formConfigurator = configurator

使用 UIColor 扩展 formColor(red: Int, green: Int, blue: Int) 创建新的 UIColor。

let configurator = FormConfigurator()
...
let darkPurple = UIColor.formColor(red: 140, green: 20, blue: 252)
configurator.editingTitleColor = darkPurple
...
formView.formConfigurator = configurator

通过设置底部线条颜色为透明（默认设置为有颜色）来选择是否隐藏底部线条。

let configurator = FormConfigurator()
...
configurator.validLineColor = UIColor.clear
configurator.invalidLineColor = UIColor.clear
configurator.editingLineColor = UIColor.clear
...
formView.formConfigurator = configurator

通过设置边框颜色为您期望的值来选择是否显示边框（默认设置为透明）。还可以设置边框宽度和圆角半径。

let configurator = FormConfigurator()
...
configurator.validBorderColor = UIColor.gray
configurator.invalidBorderColor = UIColor.orange
configurator.editingBorderColor = UIColor.darkPurple
configurator.borderCornerRadius = 20
configurator.borderWidth = 2
...
formView.formConfigurator = configurator

禁用 tableView 滚动，默认情况下是启用的。

let configurator = FormConfigurator()
...
configurator.isScrollEnabled = false
...
formView.formConfigurator = configurator
  1. 收集数据

在您的表单中输入的任何文本都将收集在您的 FormViewModel 的 items 中。由于您可能每个项目有多于一个文本字段，收集数据的一个更好方法是利用 FormViewModel 的 fields() 函数，如下

var user = User()
formViewModel.fields().forEach {
  switch $0.name {
  case "First Name":
    user.firstName = $0.value
  case "Birthdate":
    user.birthdate = $0.value
  default:
    print("\($0.name): \($0.value)")
  }
}

自定义表单项

如果您需要自定义字段，而 FormConfigurator 的自定义可能性不够，您可以实现自己的字段。为此，请按照以下步骤操作：1- 创建与任何 tableView 一样正常的自定义 UITableViewCell。2- 不要从 UITableViewCell 继承，而是将 FormTableViewCell 作为基类。3- 重写 update 和 updateErrorState 以实现字段的自定义 UI 更新。4- 创建 FormItem 的子类，重写 cellIdentifier 并返回一个有效的重用ID。5- 在您的 formViewModel 实现中，重写 customCellSetup 回调并在 tableView 上注册您的新单元格。

如果您需要示例，可以在 Example 项目中查看 StepperCell 和 StepperCellItem 类。

服务端验证

要手动标记字段无效（例如在服务端验证之后），您可以简单地进行

yourFormView.markItemInvalid(fieldName: "EmailFieldName", errorMessage: "Oops, This email is already taken")

用户对无效字段进行任何编辑之后，该字段将不再被标记为无效，除非实时验证失败。

示例应用程序

克隆此仓库并运行示例应用程序，了解 RSFormView 的一些功能。

贡献

要为此库做出贡献：将此仓库分叉并从您的分叉创建 Pull Request，详细说明您要改进/扩展的内容，所采取的方法以及功能的截图以证明所添加的功能。

您也可以在此仓库中提出问题，我们的团队将尽快解决。

许可

RSFormView 在 MIT 许可证下可用。有关更多信息，请参阅 LICENSE 文件。

致谢

RSFormView 由 Rootstrap 和 German Stabile 编写和维护，并在我们的 贡献者 的帮助下完成。