SMPageControl API参考手册:页码控件全部属性与方法完整列表
SMPageControl API参考手册:页码控件全部属性与方法完整列表
SMPageControl 是一款 iOS 的页码控件(Page Control)库,可作为系统 UIPageControl 的直接替换(drop-in replacement),同时提供丰富的自定义能力:指示点大小、间距、对齐方式、图片/遮罩指示器、逐页定制、点按直达等。本手册汇总 SMPageControl.h 中声明的全部属性与方法,助你快速查清每一项的默认值、类型与用途。
快速上手:为什么需要 SMPageControl 页码控件?
设计师常希望页码指示器与 App 的视觉风格完全一致(木纹、渐变、内阴影等)。系统 UIPageControl 的可定制性有限,而 SMPageControl 只需把类名换掉即可无缝替换,原有写法完全不变:
SMPageControl *pageControl = [[SMPageControl alloc] init];
pageControl.numberOfPages = 10;
pageControl.pageIndicatorImage = [UIImage imageNamed:@"pageDot"];
pageControl.currentPageIndicatorImage = [UIImage imageNamed:@"currentPageDot"];
核心实现位于 SMPageControl.m,完整示例可运行 Example/SMPageControl.xcodeproj/project.pbxproj 工程,其中 SMViewController.m 演示了 8 种不同配置效果,是学习 SMPageControl 属性的最佳参考。
三个枚举类型:对齐与点按行为
在使用属性之前,先认识三个枚举(均定义在 SMPageControl.h):
| 枚举 | 可选值 | 说明 |
|---|---|---|
SMPageControlAlignment |
Left / Center / Right |
指示器水平对齐方式 |
SMPageControlVerticalAlignment |
Top / Middle / Bottom |
指示器垂直对齐方式 |
SMPageControlTapBehavior |
Step / Jump |
点按行为:步进(默认,同 UIPageControl)或点按哪一点跳哪页 |
属性完整列表:SMPageControl 全部可配置项
以下 15 个属性覆盖全部外观与行为配置,其中标记 ✅ 的属性支持 iOS 5+ 的 UIAppearance 代理(可全局统一设置外观):
基础页码属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
numberOfPages |
NSInteger |
0 | 总页数,最小取 0 |
currentPage |
NSInteger |
0 | 当前页,越界值会被自动夹在 0 与最大页之间 |
hidesForSinglePage |
BOOL |
NO | 只有 1 页时是否隐藏整个控件 |
defersCurrentPageDisplay |
BOOL |
NO | 设为 YES 后,点按/改页不立即刷新显示,需手动调用 updateCurrentPageDisplay |
tapBehavior |
SMPageControlTapBehavior |
Step |
Step 为左右步进;Jump 允许直接点按任意指示点跳到该页 |
尺寸与布局属性
| 属性 | 类型 | 默认值 | UIAppearance | 说明 |
|---|---|---|---|---|
indicatorMargin |
CGFloat |
10 | ✅ | 相邻指示器之间的间距 |
indicatorDiameter |
CGFloat |
6 | ✅ | 圆形指示点的直径(使用图片指示器时自动取图片尺寸) |
minHeight |
CGFloat |
36 | ✅ | 控件最小高度,不能小于 indicatorDiameter |
alignment |
SMPageControlAlignment |
Center |
✅ | 水平对齐 |
verticalAlignment |
SMPageControlVerticalAlignment |
Middle |
✅ | 垂直对齐 |
💡 iOS 7 及以上系统会自动采用更现代的默认样式(点稍大、间距更宽),逻辑见 SMPageControl.m 的 setStyleWithDefaults:。
指示器样式属性:图片、颜色与遮罩
| 属性 | 类型 | UIAppearance | 说明 |
|---|---|---|---|
pageIndicatorImage |
UIImage |
✅ | 非当前页指示图片,设置后颜色属性对该页失效 |
pageIndicatorMaskImage |
UIImage |
✅ | 遮罩模板图(忽略已设的 pageIndicatorImage),按状态自动着色 |
pageIndicatorTintColor |
UIColor |
✅ | 非当前页颜色(设置了图片指示器时无效) |
currentPageIndicatorImage |
UIImage |
✅ | 当前页指示图片 |
currentPageIndicatorTintColor |
UIColor |
✅ | 当前页颜色(设置了当前页图片时无效) |
⚠️ 样式优先级:逐页图片 > 全局图片 > 遮罩 > 纯色圆点,渲染逻辑可参考 SMPageControl.m。
方法完整列表:SMPageControl 全部 13 个方法
页面显示管理(1 个)
| 方法 | 说明 |
|---|---|
updateCurrentPageDisplay |
将显示刷新到当前 currentPage。仅在 defersCurrentPageDisplay 为 YES 时有实际效果(延迟刷新场景:如先连跳多页再统一重绘) |
布局查询(2 个)
| 方法 | 返回值 | 说明 |
|---|---|---|
rectForPageIndicator:(NSInteger) |
CGRect |
返回指定页指示器在控件内的矩形,越界返回 CGRectZero,适合给指示器叠加自定义装饰 |
sizeForNumberOfPages:(NSInteger) |
CGSize |
计算指定页数所需的总尺寸,配合 sizeToFit 使用 |
逐页定制图片(6 个)
这是 SMPageControl 相对系统页码控件最强大的部分——每一页都可以有独立的普通态/当前态图片和遮罩:
| 方法 | 说明 |
|---|---|
setImage:forPage: |
为指定页设置普通态图片,传 nil 可移除 |
setCurrentImage:forPage: |
为指定页设置当前态图片,传 nil 可移除 |
setImageMask:forPage: |
为指定页设置遮罩模板图(自动着色) |
imageForPage: |
读取指定页的普通态图片 |
currentImageForPage: |
读取指定页的当前态图片 |
imageMaskForPage: |
读取指定页的遮罩图 |
示例(来自 SMViewController.m):给第 0、1 页分别换成"搜索"和"Apple"图标,其余页沿用全局圆点。
ScrollView 联动(2 个)
配合 UIScrollView(如分页轮播)双向同步页码:
| 方法 | 说明 |
|---|---|
updatePageNumberForScrollView: |
按滚动位置自动更新 currentPage,通常在 scrollViewDidScroll: 中调用 |
setScrollViewContentOffsetForCurrentPage:animated: |
反向操作:让滚动视图跳转到当前页对应位置,支持动画 |
无障碍命名(2 个)
| 方法 | 说明 |
|---|---|
setName:forPage: |
为某页命名(如 "Search"),VoiceOver 朗读时会附带该名称,默认格式为"第 x 页 / 共 y 页" |
nameForPage: |
读取指定页的名称 |
🔊 无障碍扩展实现见 SMPageControl.h 与 SMPageControl.m。
两个高频场景的最快配置方法
场景一:让每个指示点可直接点按跳转
pageControl.tapBehavior = SMPageControlTapBehaviorJump;
配合 addTarget:action:forControlEvents:UIControlEventValueChanged 监听翻页事件(SMPageControl 继承自 UIControl),示例见 SMViewController.m。
场景二:与分页 ScrollView 联动
// 滚动时更新页码
- (void)scrollViewDidScroll:(UIScrollView *)scrollView {
[self.pageControl updatePageNumberForScrollView:scrollView];
}
项目文件导航:快速定位源码
| 文件 | 内容 |
|---|---|
| SMPageControl.h | 全部公开属性、方法与枚举声明 |
| SMPageControl.m | 渲染、手势、无障碍等完整实现 |
| Example/SMPageControl/SMViewController.m | 8 种配置效果的示例代码 |
| Example/SMPageControl/en.lproj/SMViewController_iPhone.xib | 示例界面布局 |
| SMPageControl.podspec | CocoaPods 规格:iOS 5.0+、要求 ARC,版本 1.2 |
| LICENSE | MIT 开源协议 |
总结:SMPageControl API 要点速记
- 零成本替换:与 UIPageControl 接口一致,换类名即可,额外能力全在扩展项里
- 15 个属性管外观与行为,13 个方法管逐页定制、滚动联动和无障碍
- 样式优先级记住一句话:逐页图片 > 全局图片 > 遮罩 > 圆点颜色
tapBehavior = Jump+ 逐页图片,是打造"可点按导航式页码控件"的关键组合
掌握这份 SMPageControl API 完整列表,即可覆盖页码控件定制的所有常见需求。