JTAppleCalendar 使用指南：打造 100% 可自定义的 iOS Swift 日历视图

移动开发UI组件【免费下载链接】JTAppleCalendarThe Unofficial Apple iOS Swift Calendar View. Swift calendar Library. iOS calendar Control. 100% Customizable项目地址https://gitcode.com/gh_mirrors/jt/JTAppleCalendar点击查看免费下载导读JTAppleCalendar 是 Swift 生态中一个高度可配置的日历控件本仓库中的 README 用一句话概括了它的核心承诺——你的日历日期单元格想长什么样就能长什么样However you want them to look。本文以 README.md 中列出的功能清单为主线结合 Sources/JTAppleCalendar 下的源码实现与 SampleJTAppleCalendar 中的真实示例系统讲解区间选择、边界日期、周/月模式、自定义 Cell 与月份头部、每周首日、横竖滚动、按日期滚动等能力并给出可直接复制的代码片段与底层实现依据帮助你快速上手并将日历深度集成进自己的 App。一、功能总览README 承诺了什么仓库 README 的 Features 部分列出了以下已实现[x]的能力本文后续章节将逐一展开功能说明核心源码依据区间选择Range selection支持选择一段日期外观完全由你设计JTACMonthView.swift 中的allowsRangedSelection与 CalendarEnums.swift 中的SelectionRangePosition/RangeSelectionMode边界日期Boundary dates限制日历的日期范围JTACMonthViewProtocols.swift 的configureCalendar与 CalendarStructs.swift 的ConfigurationParameters周/月视图Week/month mode显示 1 行周视图或 2/3/6 行月视图ConfigurationParameters.numberOfRows见 CalendarStructs.swift自定义单元格日单元格外观与功能完全由你决定JTACDayCell.swift 与 JTACMonthViewProtocols.swift 的cellForItemAt自定义日历视图日历整体外观与功能可自由设计JTACMonthView.swift 直接继承UICollectionView每周首日可指定一周中任意一天作为第一天ConfigurationParameters.firstDayOfWeek默认读取系统Calendar.firstWeekday横向或纵向模式支持水平/垂直滚动JTACMonthView.swift 的scrollDirection月份头部支持不同尺寸与样式的月份头JTACMonthViewProtocols.swift 的headerViewForDateRange按日期滚动传入日期即可滚动到对应月份JTACInteractionMonthFunctions.swift 的scrollToDate(_:)提示README 同时给出了演示动图链接和官方 Wiki/Tutorial 指引本仓库内可直接运行的演示工程位于 SampleJTAppleCalendar其中 TestViewController.swift、TestRangeSelectionViewController.swift 等示例可对照本文学习。二、安装与工程结构2.1 支持的分发方式从仓库的打包配置可以看出该项目支持多种主流的 Swift 依赖管理方式CocoaPodsJTAppleCalendar.podspec 声明版本8.0.5、Swift 5、iOS/tvOS 最低部署目标11.0源码文件为Sources/JTAppleCalendar/*.swiftSwift Package ManagerPackage.swift 使用swift-tools-version:5.3平台要求.iOS(.v12)提供名为JTAppleCalendar的 library target并内置测试目标JTAppleCalendarTestsCarthageREADME 徽章中标注了 Carthage 兼容Carthage-compatible仓库同时包含 JTAppleCalendar.xcodeproj 与 SampleJTAppleCalendar.xcodeproj 两个工程文件以及单元测试 Tests/JTAppleCalendarTests 和 LinuxMain.swift。2.2 源码模块划分核心源码集中在 Sources/JTAppleCalendar按职责拆分为多个文件视图主体JTACMonthView.swift日历视图直接继承UICollectionView、JTACYearView.swift协议JTACMonthViewProtocols.swiftDataSource/Delegate数据模型CalendarStructs.swiftConfigurationParameters、CellState、Month、DateSegmentInfo枚举定义CalendarEnums.swift布局与滚动JTACMonthLayout.swift、JTACMonthLayoutHorizontalCalendar.swift、JTACMonthLayoutVerticalCalendar.swift交互与动作JTACInteractionMonthFunctions.swift、JTACMonthActionFunctions.swift、JTACScrollViewDelegates.swift。从源码结构看JTACMonthView自己接管了UICollectionView的 dataSource 与 delegate见 JTACMonthActionFunctions.swift 的super.dataSource self开发者只需遵循JTACMonthViewDataSource与JTACMonthViewDelegate两个协议即可驱动整个日历。三、五分钟快速上手最小可运行示例3.1 在 Storyboard 或代码中创建日历JTACMonthView是UICollectionView的子类JTACMonthView.swift因此你可以像拖一个 Collection View 一样把它放进 Storyboard也可以纯代码创建。它自带init()便捷构造器并自动管理自己的布局JTACMonthView.swiftimport JTAppleCalendar let calendarView JTACMonthView() calendarView.translatesAutoresizingMaskIntoConstraints false view.addSubview(calendarView)3.2 遵循两个协议extension YourViewController: JTACMonthViewDataSource, JTACMonthViewDelegate { // 数据源返回边界日期与配置参数 func configureCalendar(_ calendar: JTACMonthView) - ConfigurationParameters { let formatter DateFormatter() formatter.dateFormat yyyy MM dd let startDate formatter.date(from: 2017 01 01)! let endDate formatter.date(from: 2030 02 01)! return ConfigurationParameters(startDate: startDate, endDate: endDate) } // 代理配置每个日期单元格 func calendar(_ calendar: JTACMonthView, cellForItemAt date: Date, cellState: CellState, indexPath: IndexPath) - JTACDayCell { let cell calendar.dequeueReusableJTAppleCell( withReuseIdentifier: cell, for: indexPath) as! CellView cell.dayLabel.text cellState.text return cell } }以上代码取自仓库示例 TestViewController.swift 的完整写法configureCalendar只传了起止日期其余参数走默认值日历即可正常渲染。3.3 在 viewDidLoad 中接线calendarView.calendarDataSource self calendarView.calendarDelegate self示例工程中CellView是自定义的JTACDayCell子类通过 XIB 定义见 CellView.swift 与 CellView.xib这也引出了下一节要讲的自定义能力。四、边界日期与 ConfigurationParameters 详解README 的 Boundary dates 功能本质就是由ConfigurationParameters的startDate/endDate决定的。该结构体定义于 CalendarStructs.swift完整初始化签名如下public init(startDate: Date, endDate: Date, numberOfRows: Int 6, calendar: Calendar Calendar.current, generateInDates: InDateCellGeneration .forAllMonths, generateOutDates: OutDateCellGeneration .tillEndOfGrid, firstDayOfWeek: DaysOfWeek? nil, hasStrictBoundaries: Bool? nil)各参数含义与默认值参数默认值作用startDate/endDate无必传日历的起止边界示例中2017 01 01至2030 02 01TestViewController.swiftnumberOfRows6每个月分区的行数只有1...6才生效否则回退为 6CalendarStructs.swiftcalendarCalendar.current用于计算的Calendar实例generateInDates.forAllMonths生成前置日期上月补位的模式.forFirstMonthOnly/.forAllMonths/.offgenerateOutDates.tillEndOfGrid生成后置日期下月补位的模式.tillEndOfRow补满一行/.tillEndOfGrid补满 6×7 网格/.offfirstDayOfWeek系统calendar.firstWeekday每周第一天DaysOfWeek枚举周日1 ... 周六7hasStrictBoundariesnumberOfRows 1 ? true : false当某月不满指定行数时日期是否被限制在本月分区内不跨月流窜该值在注册了月份头部时会被忽略4.1 底层如何计算补位日期从源码可以确认这些参数直接参与月份网格的生成。CalendarStructs.swift 中的setupMonthInfoDataForStartAndEndDate(_:)会逐月计算根据generateInDates决定是否计算本月前置日期数量numberOfPreDatesForThisMonthnumberOfInDatesForMonth依据firstDayOfWeek与当月 1 号的星期几算出见 CalendarStructs.swift根据generateOutDates决定后置日期.tillEndOfGrid固定按最多 6 行maxNumberOfRowsPerMonth生成.tillEndOfRow则按实际行数补齐CalendarStructs.swift最终每个Month结构体记录inDates、outDates、rows、numberOfDaysInMonthGrid等数据供布局与 Cell 状态使用。补充numberOfInDatesForMonth中firstDayOfWeek的换算表周一6、周二5、周三4、周四10、周五9、周六8、周日7来自 CalendarStructs.swift是理解每周首日配置如何影响网格布局的直接证据。4.2 周视图与月视图切换README 的 Week/month mode 对应numberOfRows 1单周或2 / 3 / 6多行月视图。示例 TestRangeSelectionViewController.swift 展示了完整传参写法let parameter ConfigurationParameters( startDate: startDate, endDate: endDate, numberOfRows: 6, generateInDates: .forAllMonths, generateOutDates: .tillEndOfGrid, firstDayOfWeek: .sunday)五、自定义日期 Cell外观与交互的完全掌控README 强调 Custom cells——日单元格的样式和功能完全由你决定这是本库设计的核心理念。5.1 自定义 Cell 的两种方式代码方式见 CodeCellView.swiftXIB 方式见 CellView.swift CellView.xib示例 Cell 内部包含dayLabel、monthLabel、selectedView三个视图元素。Cell 必须继承JTACDayCell源码位于 JTACDayCell.swift并通过dequeueReusableJTAppleCell(withReuseIdentifier:for:)出队JTACInteractionMonthFunctions.swift。5.2 CellState驱动一切样式的数据源CellStateCalendarStructs.swift在cellForItemAt中随 Cell 一起传入它携带isSelected是否被选中text日期字符串如 1dateBelongsToDateOwner枚举区分thisMonth、previousMonthWithinBoundary、previousMonthOutsideBoundary、followingMonthWithinBoundary、followingMonthOutsideBoundaryCalendarEnums.swift——示例用它把当月日期染黑、把补位日期染灰TestViewController.swiftdate、dayDaysOfWeek、row()、column()、dateSection()selectedPosition()区间选择时的位置.left/.middle/.right/.full/.noneCalendarEnums.swiftselectionType.programatic或.userInitiatedCalendarEnums.swift。示例工程中用selectedPosition()分别给区间首、中、尾涂上不同颜色switch cellState.selectedPosition() { case .full: view.backgroundColor .green case .left: view.backgroundColor .yellow case .right: view.backgroundColor .red case .middle: view.backgroundColor .blue case .none: view.backgroundColor nil }摘自 TestViewController.swift。5.3 头部 View 的自定义README 提到 Ability to add month headers in varying sizes/styles。月份头部继承JTACMonthReusableView通过headerViewForDateRange代理方法返回。仓库给出了代码绘制头部的示例 CodePinkSectionHeaderView.swift以及 XIB 版本 PinkSectionHeaderView.xib。头部尺寸通过calendarSizeForMonths(_:)返回的MonthSize控制——MonthSize支持defaultSize统一尺寸也可按月份months或具体日期dates单独指定CalendarStructs.swift。六、区间选择Range Selection实战README 的 Range selection - select dates in a range. The design is entirely up to you 在本库中有两层含义库负责范围设计交给你的 Cell。6.1 开启区间选择calendarView.allowsMultipleSelection true calendarView.allowsRangedSelection true // 见 JTACMonthView.swiftallowsRangedSelection定义于 JTACMonthView.swift注释明确说明启用后每次点击日期单元格左右两侧的单元格都会快速刷新用于计算区间内每个 Cell 的选中位置。rangeSelectionMode则提供.segmented跨月分段视觉断开与.continuous连续两种模式JTACMonthView.swift 与 CalendarEnums.swift。6.2 程序化选择区间示例 TestViewController.swift 展示了直接选中一整段日期let date formatter.date(from: 2017 01 01)! let date2 formatter.date(from: 2017 12 25)! calendarView.selectDates(from: date, to: date2, triggerSelectionDelegate: true)底层实现selectDates(from:to:triggerSelectionDelegate:keepSelectionIfMultiSelectionAllowed:)会调用generateDateRange(from:to:)生成连续的Date数组后再批量选中JTACInteractionMonthFunctions.swift 与 JTACInteractionMonthFunctions.swift。另外还有selectDates(_:triggerSelectionDelegate:keepSelectionIfMultiSelectionAllowed:)可传入任意日期数组deselect(dates:...)/deselectAllDates(triggerSelectionDelegate:)用于反选JTACInteractionMonthFunctions.swift。6.3 区间样式绘制范例仓库的 TestRangeSelectionViewController.swift 给出了经典的胶囊形区间绘制根据selectedPosition()设置selectedView的cornerRadius与maskedCorners让区间首尾圆角、中间平直视觉上连成一条完整的选择带。七、滚动横向/纵向、分页与按日期滚动7.1 滚动方向与滚动模式scrollDirectionUICollectionView.ScrollDirection的.horizontal或.verticalJTACMonthView.swiftscrollingModeScrollingMode枚举CalendarEnums.swift包括.stopAtEachCalendarFrame每帧停靠默认等价于分页、.stopAtEachSection每分区停靠、.stopAtEach(customInterval:)自定义间隔.nonStopToSection(withResistance:)、.nonStopToCell(withResistance:)、.nonStopTo(customInterval:withResistance:)带阻力的连续滚动.none自然减速停止。设置scrollingMode时内部会同步调整isPagingEnabled与decelerationRateJTACMonthView.swift。7.2 按日期滚动到任意月份README 的 Ability to scroll to any month by simply using the date 由scrollToDate实现public func scrollToDate(_ date: Date, triggerScrollToDateDelegate: Bool true, animateScroll: Bool true, preferredScrollPosition: UICollectionView.ScrollPosition? nil, extraAddedOffset: CGFloat 0, completionHandler: (() - Void)? nil)定义见 JTACInteractionMonthFunctions.swift。传入任意Date日历会先通过pathsFromDates(_:)找到对应 IndexPath再按滚动模式计算目标偏移量并滚动过去若日期超出边界则忽略JTACMonthView.swift 的requestedContentOffset逻辑。7.3 分段滚动与可见日期回调scrollToSegment(_:triggerScrollToDateDelegate:animateScroll:extraAddedOffset:completionHandler:)按.next/.previous/.start/.endSegmentDestinationCalendarEnums.swift滚动到相邻或首尾分段JTACInteractionMonthFunctions.swift滚动期间会回调willScrollToDateSegmentWith与didScrollToDateSegmentWith参数是DateSegmentInfo——它把当前可见日期分为indates前置补位、monthDates本月、outdates后置补位三组CalendarStructs.swift。示例用visibleDates().monthDates.first更新顶部的月份标题TestViewController.swift还可在任意时刻调用visibleDates()同步查询当前可见日期或传入 completionHandler 异步获取JTACInteractionMonthFunctions.swift。7.4 高度/方向变化后的重载reloadData(withAnchor:completionHandler:)支持传入锚定日期在刷新完成后自动滚动到该日期JTACInteractionMonthFunctions.swiftviewWillTransition(to:with:anchorDate:)则用于屏幕旋转时保持视觉焦点JTACInteractionMonthFunctions.swift。示例工程在viewWillTransition中调用它以适配横竖屏切换TestViewController.swift。八、实用工具 API 速查除上述核心能力外仓库还提供了一批高价值工具方法均位于 JTACInteractionMonthFunctions.swiftAPI用途cellStatus(for date: Date)查询某个日期对应 Cell 的CellState未加载或加载中时返回 nilcellStatus(for date: Date, completionHandler:)异步版本布局未就绪时会自动延迟执行cellStatus(at point: CGPoint)按屏幕坐标查询 Cell 状态cellStatusForDate(at row:column:)按行列查询当前分区内的 Cell 状态monthStatus(for date: Date)返回日期所属的Month结构体generateDateRange(from:to:)生成起止日期之间的连续日期数组reloadDates(_:)仅重载指定日期对应的 Cell及其跨月镜像 Celldeselect(dates:triggerSelectionDelegate:keepDeselectionIfMultiSelectionAllowed:)反选指定日期另外两个实用开关值得一提allowsDateCellStretching默认true当月不足 6 行时允许 Cell 拉伸填满整行宽度JTACMonthView.swiftsemanticContentAttribute支持 RTL从右到左阅读方向切换时视图会做镜像翻转JTACMonthView.swift。九、测试与质量保障仓库在 Tests/JTAppleCalendarTests 中提供了单元测试JTAppleCalendarTests.swift、XCTestManifests.swift并在 LinuxMain.swift 中注册了 Linux 平台的测试入口Package.swift 的 testTarget 声明了JTAppleCalendarTests依赖主 target。示例工程还包含 UI 测试 SampleJTAppleCalendarUITests.swift。如果你在集成后需要验证日期网格、选择与滚动的正确性可以参考这些测试的组织方式。十、总结从 README 到可运行日历回顾 README 的核心承诺——You want it, you build itJTAppleCalendar 的设计哲学可以归纳为三点数据边界由配置驱动ConfigurationParameters一个结构体集中管理边界日期、行数、每周首日、补位日期生成策略示例代码四五行即可配置完成外观全部下沉到 Cell库只负责把哪个 Cell 对应哪个日期、处于什么选中位置通过CellState告诉你的自定义JTACDayCell渲染逻辑完全由你掌控交互能力开箱即用区间选择、按日期滚动、分段滚动、可见日期回调等 API 都已封装完毕与原生UICollectionView的手感无缝衔接。如果你希望进一步探索建议依次阅读 SampleJTAppleCalendar/Example Calendars 下的多个示例控制器覆盖普通日历、区间选择、波斯历、年份视图、横竖屏切换等场景再对照 Sources/JTAppleCalendar 中的源码理解每个开关的底层行为。赞分享移动开发UI组件【免费下载链接】JTAppleCalendarThe Unofficial Apple iOS Swift Calendar View. Swift calendar Library. iOS calendar Control. 100% Customizable项目地址https://gitcode.com/gh_mirrors/jt/JTAppleCalendar点击查看免费下载相关推荐Hyper Fetch性能优化指南减少网络请求的7个高级策略Hyper Fetch性能优化指南减少网络请求的7个高级策略 Hyper Fetch是一个强大的实时数据交换框架通过优化网络请求流程显著提升应用性能。本文将终极iOS日历定制指南JTAppleCalendar让你的应用日历焕然一新终极iOS日历定制指南JTAppleCalendar让你的应用日历焕然一新 还记得那个让你头疼的iOS日历开发经历吗当你需要为应用添加一个简单的日期选择器时移动开发UI组件CVCalendar 开源项目教程打造 iOS 自定义日历的终极指南CVCalendar 开源项目教程打造 iOS 自定义日历的终极指南 还在为 iOS 应用中的日历功能而烦恼吗想要一个既美观又功能强大的自定义日历组件CV移动开发UI库/组件上一篇class-transformer CommonJS与ESM兼容性处理跨模块使用下一篇Eve多语言支持终极指南如何实现国际化与本地化最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考