{"id":23660703,"url":"https://github.com/yizzuide/xfsettings","last_synced_at":"2025-09-01T15:32:08.167Z","repository":{"id":56927919,"uuid":"38201947","full_name":"yizzuide/XFSettings","owner":"yizzuide","description":"基于UITableView的界面定制，目标是更快更方便地构建设置界面，特点是易维护、可扩展性强。","archived":false,"fork":false,"pushed_at":"2017-11-21T08:24:20.000Z","size":1490,"stargazers_count":61,"open_issues_count":3,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-01T16:02:34.610Z","etag":null,"topics":["ios","setting","uitableview"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yizzuide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-28T14:34:16.000Z","updated_at":"2023-03-19T06:28:54.000Z","dependencies_parsed_at":"2022-08-20T23:30:41.411Z","dependency_job_id":null,"html_url":"https://github.com/yizzuide/XFSettings","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yizzuide%2FXFSettings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yizzuide%2FXFSettings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yizzuide%2FXFSettings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yizzuide%2FXFSettings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yizzuide","download_url":"https://codeload.github.com/yizzuide/XFSettings/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231698616,"owners_count":18412843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ios","setting","uitableview"],"created_at":"2024-12-29T04:00:04.055Z","updated_at":"2024-12-29T04:00:04.788Z","avatar_url":"https://github.com/yizzuide.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![XFSettings logo](./ScreenShot/XFSettingLogo.png)\n\n[![CocoaPods](https://img.shields.io/badge/cocoapods-v2.6.0-brightgreen.svg)](http://cocoadocs.org/docsets/XFSettings)\n![Language](https://img.shields.io/badge/language-ObjC-orange.svg)\n![License](https://img.shields.io/hexpm/l/plug.svg)\n![Version](https://img.shields.io/badge/platform-ios7%2B-green.svg)\n\n基于UITableView的界面定制，目标是更快更方便地构建设置界面，特点是易维护、可扩展性强。\n\n![XFSettings usage1](./ScreenShot/usage.gif)\n\n## 安装\n1、通过cocoapods\n\u003e pod 'XFSettings','~\u003e 2.6.0'\n\n2、手动加入\n\n把XFSettings整个目录拖入到工程\n\n## 更新记录\n* 2017/11/21  V2.6.0  增强对`XFSettingAssistImageCell`类型的控制能力\n* 2017/11/14  V2.5.2  修复一个block安全检查问题\n* 2017/11/14  V2.5.1  修复一组只有一行的卡片式样式圆角问题\n* 2017/11/14  V2.5.0  新增卡片式UI可选样式设置`XFSettingStyleCard`\n* 2017/9/14   V2.4.0  支持行高设置`XFSettingItemHeight`字段，自定义底部满线风格下首个cell顶部自动画线\n* 2016/12/9   V2.3.2  修复图标循环使用问题\n* 2016/9/12   V2.3.1  使`XFSetttingCell`可以在外部初始化设置它的子视图状态\n* 2016/8/15   V2.3.0  支持自定义布局`XFSettingPhaseTypeCellLayout`阶段\n* 2016/7/14   V2.2.1  修复在第二级控制器旋转屏幕后，返回到设置界面无法正确适配问题\n* 2016/7/13   V2.2.0  支持横竖屏自适配，开发者无需修改代码\n* 2016/7/8    V2.1.0  重要！修复使用\"UIViewController+XFSettings\"分类方式引发其它基于TableView的控制器崩溃问题，请及时更新！\n* 2016/7/4    V2.0.2  支持动态设置右边文字后自适应大小，优化布局计算，\"UIViewController+XFSettings.h\"分类方式需要手动导入\n* 2016/7/1    V2.0.1  修复自定义线色未设置为空问题，支持设置TableViewStyle\n* 2016/6/23   V2.0.0  使用非侵入式分类UIViewController+XFSettings方式构建设置界面\n* 2015/6/28   V1.0.0  提交第一个版本，支持基本配置功能\n\n\n## 开发文档\n### 一、快速开始使用\n1.导入主头文件`#import \"XFSettings.h`和分类`#import \"UIViewController+XFSettings.h\"`\n\n2.在`viewDidLoad`方法使用`self.xf_cellAttrsData`设置`XFCellAttrsData`类型参数\n\n3.设置数据源`self.xf_dataSource`并调用`[self xf_setup]`进行配置\n\n4.实现`XFSettingTableViewDataSource`协议的`- (NSArray *)settingItems`数据源方法返回`NSArray`以供库内部的渲染\n\n```objc\n//.m\n#import \"XFSettings.h\"\n#import \"UIViewController+XFSettings.h\"\n\n@interface ViewController () \u003cXFSettingTableViewDataSource\u003e\n\n@end\n\n@implementation ViewController\n\n- (void)viewDidLoad {\n    [super viewDidLoad];\n    \n    self.navigationItem.title = @\"设置\";\n    self.view.backgroundColor = [UIColor whiteColor];\n    \n    // set cell attrs\n    XFCellAttrsData *cellAttrsData = [[XFCellAttrsData alloc] init];\n    // 设置图标大小\n    cellAttrsData.contentIconSize = 20;\n    // 设置内容间距\n    cellAttrsData.contentEachOtherPadding = 15;\n    // 标题文字大小（其它文字会按个大小自动调整）\n    cellAttrsData.contentTextMaxSize = 13;\n    // 表格风格\n    cellAttrsData.tableViewStyle = UITableViewStyleGrouped;\n    \n    self.xf_cellAttrsData = cellAttrsData;\n    // 设置数据源\n    self.xf_dataSource = self;\n    // 调用配置设置\n    [self xf_setup];\n    \n    \n}\n\n- (NSArray *)settingItems\n{\n    return @[ // groupArr\n             @{ // groupModel\n                 XFSettingGroupHeader: @\"基本信息\",\n                 XFSettingGroupItems : @[ // items\n                         @{ // itemModel\n                             XFSettingItemTitle: @\"我的朋友\",\n                             XFSettingItemIcon : @\"1435582804_group\",\n                             // 这个字段用于判断是否有右边辅助功能的cell,不写则没有\n                             XFSettingItemClass : [XFSettingInfoItem class], \n                             XFSettingItemAttrDetailText : @\"你的好友\",\n                             // 自定义的cell\n                             XFSettingItemRelatedCellClass:[XFSettingInfoDotCell class],\n                             // 如果有目标控制器\n                            XFSettingItemDestViewControllerClass : [XFNewFriendViewController class], \n                            // 目标控制器带有参数\n                             XFSettingItemDestViewControllerUserInfo : @{@\"url\":@\"http://www.yizzuide.com\"},\n                             // 如果有可选操作\n                             XFSettingOptionActionBlock : ^(XFSettingInfoDotCell *cell,XFSettingPhaseType phaseType,id intentData){\n                                // 如果被点击\n                                 if (phaseType == XFSettingPhaseTypeCellInteracted) {\n                                     cell.rightInfoLabel.hidden = YES;\n                                 }\n                             }\n                             },// end itemModel\n                         ],// end items\n                 XFSettingGroupFooter : @\"lalala~\"\n                 }// end groupModel\n             ];// endgroupArr\n}\n@end\n```\n\n### 二、框架文档\n整体框架图如下：\n![](./ScreenShot/framework.png)\n#### 1. 框架集成的两种方式\n1.1. 集成之继承`XFSettingTableViewController`（过时）  \n注意：从2.0.0开始，这种方式就标为过时了，因为一个类只能继承一个类，不方便开发者自由使用  \n使用方式：\n- 导入主头文件`#import \"XFSettings.h`\n- 使目标控制器继承`XFSettingTableViewController`\n- 在`viewDidLoad`方法里设置`XFCellAttrsData`参数\n- 设置数据源`self.dataSource`\n- 实现`XFSettingTableViewDataSource`协议的`- (NSArray *)settingItems`数据源方法返回`NSArray`以供库内部的渲染\n\n1.2. 集成之分类`UIViewController+XFSettings`（推荐使用）  \n注意：从2.0.0开始支持  \n使用方式：见上面**快速开始使用**\n\n#### 2. 数据源格式\n使用`- (NSArray *)settingItems`返回数据源的格式如下，该方法不能返回`nil`。\n```objc\n- (NSArray *)settingItems\n{\n    return @[ // 对应UITableView的Section数组\n            @{ // 每一个Section\n                XFSettingGroupHeader: @\"Section的Header\",\n                XFSettingGroupItems : @[ // 对应UITableView的cell数组\n                    @{ // 每一个cell\n                        // ...item的具体配置\n                    }\n                ],\n                XFSettingGroupFooter : @\"Section的Footer\"\n            }\n    ];\n}\n```\n\n#### 3.全局配置\n使用`XFCellAttrsData`类全局配置设置界面：\n```objc\n// Cell Color\n@property (nonatomic, strong) UIColor *cellBackgroundColor;\n@property (nonatomic, strong) UIColor *cellSelectedBackgroundColor;\n@property (nonatomic, strong) UIView *cellBackgroundView;\n@property (nonatomic, strong) UIView *cellSelectedBackgroundView;\n// cell下线颜色\n@property (nonatomic, strong) UIColor *cellBottomLineColor;\n// 只显示下方的画线\n@property (nonatomic, assign) BOOL cellFullLineEnable;\n\n// 标题颜色\n@property (nonatomic, strong) UIColor *contentTitleTextColor;\n// 详细文字颜色\n@property (nonatomic, strong) UIColor *contentDetailTextColor;\n// 右边辅助文字颜色\n@property (nonatomic, strong) UIColor *contentInfoTextColor;\n// 标题文字大小（其它文字会按个大小自动调整）\n@property (nonatomic, assign) CGFloat contentTextMaxSize;\n// 设置图标大小\n@property (nonatomic, assign) CGFloat contentIconSize;\n// 设置内容间距\n@property (nonatomic, assign) CGFloat contentEachOtherPadding;\n// 禁止显示第一条线\n@property (nonatomic, assign) BOOL disableTopLine;\n// 列表显示风格（注意：只适用于使用分类UIViewController+XFSettings.h方式）\n@property (nonatomic, assign) UITableViewStyle tableViewStyle;\n```\n\n#### 4. 配置属性\n每一个Cell的显示内容，都会根据以下配置字段：\n```objc\n// 组信息\n/**\n *  分组头信息\n */\nextern NSString * const XFSettingGroupHeader;\n/**\n *  每一组的多个Cell\n */\nextern NSString * const XFSettingGroupItems;\n/**\n *  分组页脚信息\n */\nextern NSString * const XFSettingGroupFooter;\n\n// 每个Item的可用配置\n/**\n *  Cell的模型类型\n */\nextern NSString * const XFSettingItemClass;\n/**\n *  Cell标题\n */\nextern NSString * const XFSettingItemTitle;\n/**\n *  Cell图标\n */\nextern NSString * const XFSettingItemIcon;\n/**\n *  cell arrow图标\n */\nextern NSString * const XFSettingItemArrowIcon;\n/**\n *  CellView的类型\n */\nextern NSString * const XFSettingItemRelatedCellClass;\n/**\n *  第二级跳转控制器Class\n */\nextern NSString * const XFSettingItemDestViewControllerClass;\n/**\n *  使用XFSettingArrowItem时，第二级跳转控制器传参数信息（新的控制器里添加XFSettingIntentUserInfo协议）\n */\nextern NSString * const XFSettingItemDestViewControllerUserInfo;\n/**\n *  Cell点击后的执行代码块\n */\nextern NSString * const XFSettingOptionActionBlock;\n/**\n * 使用XFSettingInfoItem和XFSettingInfoCell时的属性,详细信息\n */\nextern NSString * const XFSettingItemAttrDetailText;\n/**\n *  使用XFSettingInfoItem和XFSettingInfoCell时的属性,右边辅助信息\n */\nextern NSString * const XFSettingItemAttrRightInfo;\n/**\n *  使用XFSettingAssistImageItem和XfSettingAssistImageCell时的属性，右边辅助图\n */\nextern NSString * const XFSettingItemAttrAssistImageName;\n```\n\n#### 4. Cell的可选操作\n每个Cell有布局阶段和有交互事件，在布局阶段可以用代码修改一些信息，被点击时可执行相应操作  \n可选操作定义如下：\n```objc\ntypedef enum : NSUInteger {\n    XFSettingPhaseTypeCellInit, // 初始化阶段\n    XFSettingPhaseTypeCellLayout, // 布局阶段\n    XFSettingPhaseTypeCellInteracted // 有交互事件\n} XFSettingPhaseType;\n\n// cell: 可转换到开发者自己通过XFSettingItemRelatedCellClass字段配置的Cell类型\n// intentData: 为传回的变化数据，如：模型XFSettingSwitchItem类型的Cell,会在UISwitch改变时发出XFSettingPhaseTypeCellInteracted事件\ntypedef void(^SettingItemOptionBlock)(UITableViewCell *cell,XFSettingPhaseType phaseType,id intentData);\n```\n\n#### 5. 预定义模型类和Cell搭配\n框架有定义一些预设的模型数据类（如：`XFSettingItem`）和Cell（如：`XFSettingCell`），用于搭配出不同的显示内容：\n- 无交互事件的Cell: `XFSettingItem` + `XFSettingCell`\n- 带UISwitch的Cell: `XFSettingSwitchItem` + `XFSettingCell`\n- 带右边箭头图标的Cell: `XFSettingArrowItem` + `XFSettingCell`\n- 带右边箭头、有右边消息文字/点的Cell: `XFSettingInfoItem` + `XFSettingInfoCell/XFSettingInfoCountCell/XFSettingInfoDotCell`\n- 带右边箭头、有右边图片的Cell: `XFSettingAssistImageItem` + `XFSettingAssistImageCell`\n\n#### 6. 组装显示各种类型的Cell\n##### 6.1. 普通显示无交互事件的Cell\n可以不用配置`XFSettingItem`和`XFSettingCell`,因为默认就是这种类型，如：\n```objc\n    @{\n        XFSettingItemTitle: @\"标题\",\n        XFSettingItemIcon : @\"img\",\n        }\n```\n##### 6.2. 普通显示有交互事件的Cell\n```objc\n    @{\n        XFSettingItemTitle: @\"标题\",\n        XFSettingItemIcon : @\"img\",\n        XFSettingOptionActionBlock : ^(XFSettingCell *cell,XFSettingPhaseType phaseType,id intentData){\n                  if (phaseType == XFSettingPhaseTypeCellInteracted) {\n                        // todo...\n                    }               \n            }\n        }\n```\n##### 6.3. 普通显示带右边箭头且有交互事件跳转控制器的Cell\n有无右边的箭头不仅是设置`XFSettingItemClass`为`XFSettingArrowItem`,还要设置`XFSettingItemDestViewControllerClass`，不加后者将不会显示箭头\n```objc\n     @{\n        XFSettingItemTitle: @\"标题\",\n        XFSettingItemIcon : @\"img\",\n        XFSettingItemClass: [XFSettingArrowItem class],\n        XFSettingItemDestViewControllerClass:[ViewController class],\n        }\n```\n##### 6.4. 普通显示带自定义右边箭头图标无交互事件的Cell\n在要显示右边箭头，又不能跳转控制器的情况下，设置` XFSettingItemDestViewControllerClass:[NSObject class]`\n```objc\n    @{\n        XFSettingItemTitle: @\"标题\",\n        XFSettingItemIcon : @\"img\",\n        // 使用自定义向右箭头\n        XFSettingItemArrowIcon : @\"CellArrow\",\n        XFSettingItemClass: [XFSettingArrowItem class],\n        // 当不使用控制器类时可以实现有箭头并且不会跳转\n        XFSettingItemDestViewControllerClass:[NSObject class],\n        }\n```\n##### 6.5. 显示有详细信息文字的Cell\n```objc\n    @{\n        XFSettingItemTitle: @\"标题\",\n        XFSettingItemIcon : @\"img\",\n        XFSettingItemAttrDetailText : @\"左边的详细说明\",\n        XFSettingItemAttrRightInfo : @\"右边的信息文字\",\n        XFSettingItemClass: [XFSettingInfoItem class],\n        XFSettingItemRelatedCellClass:[XFSettingInfoCell class],\n        }\n```\n\n##### 6.6 显示右边带图图片的Cell\n```objc\n    @{\n        XFSettingItemTitle: @\"标题\",\n        XFSettingItemIcon : @\"img\",\n        XFSettingItemAttrAssistImageName : @\"assistImg\",\n        XFSettingItemClass: [XFSettingAssistImageItem class],\n        XFSettingItemRelatedCellClass:[XFSettingAssistImageCell class],\n        }\n```\n#### 7. 扩展模型子类和子Cell\n开发者可以扩展自己Cell显示的内容，扩展形式可以参考`XFSettingAssistImageItem` 和 `XFSettingAssistImageCell`\n##### 7.1. 扩展模型数据类\n自定义类继承`XFSettingArrowItem`，添加一些必要的`property`\n##### 7.2. 扩展Cell\n1. 自定义Cell继承`XFSettingCell`  \n2. 覆盖`- (void)setItem:(XFSettingItem *)item`方法，填充自己的数据到视图  \n3. 覆盖`- (void)layoutSubviews`方法，并调用`[super layoutSubviews]`父类实现，对子视图进行布局  \n4. 覆盖`+ (NSString *)settingCellReuseIdentifierString`方法，为自定义的Cell打一个标签，用于循环利用  \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyizzuide%2Fxfsettings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyizzuide%2Fxfsettings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyizzuide%2Fxfsettings/lists"}