SMPageControl API参考手册:页码控件全部属性与方法完整列表

原创2026-10-10 13:23:331,770 阅读
文章标签:UI库/组件移动开发

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 完整列表,即可覆盖页码控件定制的所有常见需求。

登录后查看全文
SMPageControl