如何使用JTForm

JTForm是一个能简单快速的搭建流畅复杂表单的库,灵感来自于XLForm与Texture。JTForm能帮助你像html一样创建表单。不同于XLForm是一个UIViewController的子类,JTFormUIView的子类,也就是说,你可以像使用UIView一样使用JTForm,应用范围更广,更方便。JTForm也可以用来创建列表,而不仅仅是表单。
JTForm使用Texture完成视图的布局与加载,所以集成了Texture的优点:异步渲染,极度流畅。使用JTForm,你可以忘记许多原生控件时需要注意的东西:高度设置,单元行复用等。为了避免ASTableNode重载时图片闪烁的问题,自定义了JTNetworkImageNode代替ASNetworkImageNode
下面是demo运行在公司老旧设备5s的截图,可以看到fps基本保持在60左右。
fps基本保持在60
text输入表单 安装

  • 使用cocoapods:pod 'JTForm', '~> 0.0.1'
注意事项
  • 如果库自带的单元行满足不了需求,需要自定义单元行的时候,需要了解Texture的相关知识。
  • 如果你的项目中有类似?IQKeyboardManager的第三方,请在使用JTForm的时候禁用他们,不然会跟库的键盘弹起相冲突。如果你想禁用JTForm的键盘弹起,你可以设置JTForm的属性showInputAccessoryView为NO
  • 目前该库依赖于SDWebImage(4.4.6), Texture(2.8),使用cocoapods安装时,如果与本地的版本发生冲突,请手动添加该库,或者升级依赖库
简单使用
简单的表单1 下面是构建该表单一部分的代码以及注释
// 构建表描述 JTFormDescriptor *formDescriptor = [JTFormDescriptor formDescriptor]; // 是否在必填行的title前面添加一个红色的* formDescriptor.addAsteriskToRequiredRowsTitle = YES; JTSectionDescriptor *section = nil; JTRowDescriptor *row = nil; #pragma mark - float text // 创建节描述 section = [JTSectionDescriptor formSection]; // 为section创建header title,目前需要手动输入header view的height section.headerAttributedString = [NSAttributedString attributedStringWithString:@"float text" font:nil color:nil firstWordColor:nil]; // 目前需要手动输入header view的height,不然是默认值,可能会出现排版显示问题 section.headerHeight = 30.; // 将节描述添加到表描述中 [formDescriptor addFormSection:section]; // 创建行描述,rowType为必填项,创建单元行时根据rowType来选择创建不同的单元行 row = [JTRowDescriptor formRowDescriptorWithTag:JTFormRowTypeFloatText rowType:JTFormRowTypeFloatText title:@"测试"]; // 是否必填 row.required = YES; // 将行描述添加到表描述中 [section addFormRow:row]; #pragma mark - formatterrow = [JTRowDescriptor formRowDescriptorWithTag:@"20" rowType:JTFormRowTypeNumber title:@"百分比"]; NSNumberFormatter *numberFormatter = [NSNumberFormatter new]; numberFormatter.numberStyle = NSNumberFormatterPercentStyle; // 添加valueFormatter,是NSFormatter的子类,能将value转换成不同的文本。常用的有nsdateformatter // 这里valueFormatter的作用是将数字转换成百分数,例如10->1000% row.valueFormatter = numberFormatter; row.value = https://www.it610.com/article/@(100); row.required = YES; // 在title前面添加图片 row.image = [UIImage imageNamed:@"jt_money"]; [section addFormRow:row]; row = [JTRowDescriptor formRowDescriptorWithTag:@"21" rowType:JTFormRowTypeNumber title:@"人民币"]; NSNumberFormatter *numberFormatter1 = [NSNumberFormatter new]; numberFormatter1.numberStyle = NSNumberFormatterCurrencyStyle; // 这里valueFormatter的作用是将数字转换成货币,例如10->¥10 row.valueFormatter = numberFormatter1; row.value = https://www.it610.com/article/@(100); row.required = YES; row.image = [UIImage imageNamed:@"jt_money"]; [section addFormRow:row]; #pragma mark - common row = [JTRowDescriptor formRowDescriptorWithTag:JTFormRowTypeName rowType:JTFormRowTypeName title:@"JTFormRowTypeName"]; // 占位符 row.placeHolder = @"请输入姓名..."; // 赋值 row.value = https://www.it610.com/article/@"djdjd"; row.required = YES; [section addFormRow:row]; // 创建JTForm,formDescriptor不能为空 JTForm *form = [[JTForm alloc] initWithFormDescriptor:formDescriptor]; form.frame = CGRectMake(0, 0, kJTScreenWidth, kJTScreenHeight-64.); [self.view addSubview:form]; self.form = form;

行描述 JTRowDescriptor
行描述JTRowDescriptor是单元行的数据源,我们通过修改行描述来控制着单元行的行为,例如:是否显示,是否可编辑,高度。
下面是JTRowDescriptor的主要属性和常用方法
configMode 配置模型。
  • titleColor:标题颜色
  • contentColor:详情颜色
  • placeHolderColor:占位符颜色
  • disabledTitleColor:禁用时标题颜色
  • disabledContentColor:禁用时详情颜色
  • bgColor:控件背景颜色
  • titleFont:标题字体
  • contentFont:详情字体
  • placeHlderFont:占位符字体
  • disabledTitleFont:禁用时标题字体
  • disabledContentFont:禁用时详情字体
JTSectionDescriptorJTFormDescriptor同样具有这些属性,作用也类似。优先级JTRowDescriptor > JTSectionDescriptor > JTFormDescriptor
image & imageUrl 用于加载图片,样式类似于UITableViewCell的imageView。image应用于静态图片,imageUrl用于加载网络图片。
rowType 创建表单时,根据rowType来创建不同类型的单元行。目前库自带的rowType都已经添加到了[JTForm cellClassesForRowTypes]字典中,其中rowType为key,单元行类型Class为value。在创建时单元行时,你就可以通过字典根据rowType得到相应单元行的Class。
所以当你自定义单元行时,你需要在+ (void)load中,将相应的rowType以及对应的Class添加到[JTForm cellClassesForRowTypes]字典中。
tag nullable,若不为空,表单将其添加到字典中,其中key为tag,value为JTRowDescriptor实例。所以如果创建表单时有多个行描述tag值一样的话,字典中将只会保存最后添加进去的JTRowDescriptor。
你可以在表单中,根据tag值找到相对应的行描述。且在获取整个表单值的时候也会派上用场。
height 该属性控制着单元行高度。默认值为JTFormUnspecifiedCellHeight,即不指定高度(自动调节高度)。
单元行高度的优先级:
  • JTRowDescriptor的height属性
  • JTBaseCellDelegate的方法+ (CGFloat)formCellHeightForRowDescriptor:(JTRowDescriptor *)row;
  • 自动调节高度
action 响应事件,目前仅用于点击单元行。如果单元行上有多个控件有响应事件时,建议使用- (JTBaseCell *)cellInForm; 得到当前的单元行cell,然后用[cell.button addTarget:self action:action forControlEvents:UIControlEvents]添加响应事件。
hidden & disabled hidden:bool值,控制隐藏或者显示当前单元行
disabled:bool值,控制当前单元行是否接受响应事件
JTSectionDescriptorJTFormDescriptor同样具有这些属性,作用也类似。优先级JTRowDescriptor > JTSectionDescriptor > JTFormDescriptor
cellConfigAfterUpdate & cellConfigWhenDisabled & cellConfigAtConfigure & cellDataDictionary
  • cellConfigAfterUpdate:配置cell,在‘update’方法后使用
  • cellConfigWhenDisabled:配置cell,当'update'方法后,且disabled属性为Yes时被使用
  • cellConfigAtConfigure:配置cell,当cell调用config之后,update方法之前调用
  • cellDataDictionary:预留,你可以选择使用时机
text 文本方面的,属性比较多,统一放到这里讲
  • valueFormatter:文本格式转换,可以将数据格式化为一种易读的格式。‘NSFormatter’是一个抽象类,我们只使用它的子类,类似'NSDateFormatter'和‘NSNumberFormatter’
  • placeHolder:占位符,当value为空时显示该内容
  • maxNumberOfCharacters:文本类单元行能输入最大字符数
  • - (nullable NSString *)displayContentValue; :在未编辑状态时,详情的显示内容
  • - (nullable NSString *)editTextValue; :在编辑状态时,详情的显示内容
验证器 你可以通过- (void)addValidator:(nonnull id)validator; 添加一个或多个验证器,验证器的作用是对单元行的值进行验证,来判断是否符合你的要求,例如:身份证格式,密码的复杂程度,字数长度等。
当然,除了库自带的验证器外,你可以自定义自己的验证器,注意需要实现代理JTFormValidateProtocol
单元行类型
文本类
  • JTFormRowTypeFloatText
  • JTFormRowTypeText
  • JTFormRowTypeName
  • JTFormRowTypeEmail
  • JTFormRowTypeNumber
  • JTFormRowTypeInteger
  • JTFormRowTypeDecimal
  • JTFormRowTypePassword
  • JTFormRowTypePhone
  • JTFormRowTypeURL
  • JTFormRowTypeTextView
  • JTFormRowTypeInfo
主要的区别是键盘不同,需要注意的是:JTFormRowTypeTextViewJTFormRowTypeInfotextview,而其它几种是textfield
text select类
  • JTFormRowTypePushSelect
push到另一个vc中,仅可选择一个
  • JTFormRowTypeMultipleSelect
push到另一个vc中,可选择多个
  • JTFormRowTypeSheetSelect
UIAlertController,样式为UIAlertControllerStyleActionSheet
  • JTFormRowTypeAlertSelect
UIAlertController,样式为UIAlertControllerStyleAlert
  • JTFormRowTypePickerSelect
类似于弹出键盘,inputview为UIPickeraaa
选择项通常会拥有一个展示文本,一个是代表value的id。例如你在选择汽车型号的时候,展示给你的是不同汽车的型号的文本,当你选中之后传给后台的是代表该型号的文本。
在选择类的单元行中,我们使用的选择项类型是JTOptionObject,主要由两个属性formDisplayTextformValue,含义顾名思义。选择项可以通过selectorOptions赋值得到,在单元行选中之后,单元行的value也是JTOptionObject类型(单选)或者为NSArray *类型(多选),你可以使用NSObject类目方法- (id)cellValue; 得到value。
date类
  • JTFormRowTypeDate
  • JTFormRowTypeTime
  • JTFormRowTypeDateTime
  • JTFormRowTypeCountDownTimer
  • JTFormRowTypeDateInline
除了JTFormRowTypeDateInline,其余集中的区别只是UIDatePickertimeStyletimeStyle的区别。JTFormRowTypeDateInline的效果如下:
如何使用JTForm
文章图片
JTFormRowTypeDateInline 其它
  • JTFormRowTypeSwitch
  • JTFormRowTypeCheck
  • JTFormRowTypeStepCounter
  • JTFormRowTypeSegmentedControl
  • JTFormRowTypeSlider
具体样式可以看demo
JTBaseCell
单元行的基类,如果你需要自定义单元行的话需要继承它。JTBaseCell里面的属性和方法都比较简单,需要注意的是JTBaseCellDelegate,下面来我来说明一下它的几个方法:
config required。初始化控件,在这个方法里只需要创建需要的控件,但不需要为控件添加内容,因为这个时候并没有添加进去数据源JTRowDescriptor。在生命周期内该方法只会被调用一次,除非调用JTRowDescriptor的方法reloadCell,该方法会重新创建单元行。
子类中实现时需要调用[super config]
update required。更新视图内容,在生命周期中会被多次调用。在这个方法中,我们可以为已经创建好的内容添加内容。
子类中实现时需要调用[super update]
其它
剩下的几个方法都是@optional
  • + (CGFloat)formCellHeightForRowDescriptor:(JTRowDescriptor *)row
指定单元行的高度
  • - (BOOL)formCellCanBecomeFirstResponder
指示单元行是否能够成为第一响应者, 默认返回NO
  • - (BOOL)formCellBecomeFirstResponder
单元行成为第一响应者
  • - (BOOL)formCellResignFirstResponder
单元行放弃第一响应者
  • - (void)formCellDidSelected
当前的单元行被选中了
  • - (NSString *)formDescriptorHttpParameterName
为单元行设置一个参数名称。若不为空,当调用JTFormDescriptor的方法httpParameters返回的表单字典中,key为该参数名称,value为JTRowDescriptor的value。
  • - (void)formCellHighlight
单元行高亮
  • - (void)formCellUnhighlight
单元行不高亮
自定义单元行
以demo中我自定义的单元行IGCell为例。
+ (void)load 首先,你需要一个rowType来代表该行。然后在+ (void)load方法中[[JTForm cellClassesForRowTypes] setObject:self forKey:JTFormRowTypeIGCell]; 将rowType与单元行关联起来。
config
- (void)config { [super config]; // 你的代码 }

在这里你可以创建好控件,但不需要为控件添加内容。注意需要调用[super config];
update
- (void)update { [super update]; // 你的代码 }

在这个方法中,我们可以为已经创建好的内容添加内容。。注意需要调用[super update];
layoutSpecThatFits - (ASLayoutSpec *)layoutSpecThatFits:(ASSizeRange)constrainedSize。在这个方法中,你需要创建好布局。对此,你需要额外学习Texture(原AsyncDisplayKit)的布局系统。
表单行为控制
hidden 当表单完成之后,你可以通过改变JTRowDescriptor,JTSectionDescriptor,JTFormDescriptor hidden的值来隐藏或者显示相应的单元行,单元节,表单。
disabled 你可以通过改变JTRowDescriptor,JTSectionDescriptor,JTFormDescriptor disabled的值来决定相应的单元行,单元节,表单是否可以被编辑。
delete row
JTSectionDescriptor *section = [JTSectionDescriptor formSection]; section.sectionOptions = JTFormSectionOptionCanDelete;

你可以这样创建节描述,就可以让单元节具有删除单元行功能。
FAQ
如何给section自定义 header/footer 你也可以通过设置JTSectionDescriptorheaderHieghtheaderView或者footerHieghtfooterView属性来自定义header/footer。目前需要手动设置高度...
如何拿到表单的值 你可以通过JTForm- (NSDictionary *)formValues获取表单值。如果设置了验证器或者有必填项,可以先调用- (NSArray *)formValidationErrors来获取错误集合,再获取表单值进行其它操作。
如何给日期行设置最大,最小日期 【如何使用JTForm】你可以通过下面的代码这样设置,虽然丑陋,但是能用...
[row.cellConfigAtConfigure setObject:[NSDate date] forKey:@"minimumDate"]; [row.cellConfigAtConfigure setObject:[NSDate dateWithTimeIntervalSinceNow:(60*60*24*3)] forKey:@"maximumDate"];

如何改变cell的高度 单元行高度的优先级:
  • JTRowDescriptor的height属性
  • JTBaseCellDelegate的方法+ (CGFloat)formCellHeightForRowDescriptor:(JTRowDescriptor *)row;
  • 根据布局来生成高度
如何自定义类似于JTFormRowTypeDateInline的内联行 如果你想要创建类似JTFormRowTypeDateInline的内联行,就意味着你需要自定义两种单元行。拿JTFormRowTypeDateInline举个例子,A:JTFormDateCell,B:JTFormDateInlineCell。当你选中A时,B显示出来,再选中A,B消失。
  • 首先,创建两种单元行A, B
  • B在load方法中,还需要额外添加[[JTForm inlineRowTypesForRowTypes] setObject: A.rowType forKey:B.rowType]
  • 剩下的操作为以下代码,你可以照着写。这里简单说明以下,当你选择A时,会调用formCellCanBecomeFirstResponderformCellBecomeFirstResponder方法。随后调用canBecomeFirstResponderbecomeFirstResponder,注意这里必须调用super的方法,不然当前单元行无法成为第一响应者。在becomeFirstResponder中,我们创建B,并且添加到A后面。
- (BOOL)formCellCanBecomeFirstResponder { return [self canBecomeFirstResponder]; }- (BOOL)formCellBecomeFirstResponder { if ([self isFirstResponder]) { return [self resignFirstResponder]; } return [self becomeFirstResponder]; }- (BOOL)canBecomeFirstResponder { [super canBecomeFirstResponder]; return !self.rowDescriptor.disabled; }- (BOOL)becomeFirstResponder { [super becomeFirstResponder]; NSIndexPath *currentIndexPath = [self.rowDescriptor.sectionDescriptor.formDescriptor indexPathForRowDescriptor:self.rowDescriptor]; JTSectionDescriptor *section = [self.rowDescriptor.sectionDescriptor.formDescriptor.formSections objectAtIndex:currentIndexPath.section]; JTRowDescriptor *inlineRow = [JTRowDescriptor formRowDescriptorWithTag:nil rowType:JTFormRowTypeInlineDatePicker title:nil]; JTFormDateInlineCell *inlineCell = (JTFormDateInlineCell *)[inlineRow cellInForm]; NSAssert([inlineCell conformsToProtocol:@protocol(JTFormInlineCellDelegate)], @"inline cell must conform to protocol 'JTFormInlineCellDelegate'"); inlineCell.connectedRowDescriptor = self.rowDescriptor; [section addFormRow:inlineRow afterRow:self.rowDescriptor]; [self.findForm ensureRowIsVisible:inlineRow]; BOOL result = [super becomeFirstResponder]; if (result) { [self.findForm beginEditing:self.rowDescriptor]; } return result; }- (BOOL)canResignFirstResponder { BOOL result = [super canResignFirstResponder]; return result; }- (BOOL)resignFirstResponder { BOOL result = [super resignFirstResponder]; if ([self.rowDescriptor.rowType isEqualToString:JTFormRowTypeDateInline]) { NSIndexPath *currentIndexPath = [self.rowDescriptor.sectionDescriptor.formDescriptor indexPathForRowDescriptor:self.rowDescriptor]; NSIndexPath *nextRowPath = [NSIndexPath indexPathForRow:currentIndexPath.row + 1 inSection:currentIndexPath.section]; JTRowDescriptor *inlineRow = [self.rowDescriptor.sectionDescriptor.formDescriptor formRowAtIndex:nextRowPath]; if ([inlineRow.rowType isEqualToString:JTFormRowTypeInlineDatePicker]) { [self.rowDescriptor.sectionDescriptor removeFormRow:inlineRow]; } } return result; }

    推荐阅读