UIScrollView相关文档理解

UIScrollView相关文档理解

import Foundation
import UIKit

//
//  UIScrollView.h
//  UIKit
//
//  Copyright (c) 2007-2016 Apple Inc. All rights reserved.
//

/** 指示器的样式*/
public enum UIScrollViewIndicatorStyle : Int {

    /** 默认样式*/
    case `default` // black with white border. good against any background

    case black // black only. smaller. good against a white background

    case white // white only. smaller. good against a black background
}

/** 滑动的时候如果键盘正在显示，对于键盘的处理*/
@available(iOS 7.0, *)
public enum UIScrollViewKeyboardDismissMode : Int {


    case none /** 不做任何处理*/

    /** 开始拖动的时候dismiss键盘*/
    case onDrag // dismisses the keyboard when a drag begins

    /** 一种交互式效果，具体效果就是：当键盘showing的时候，下拉scrollview到top的时候，继续下        拉，这时候键盘也会跟随scrollview下移，并在某个时刻消失*/
    case interactive // the keyboard follows the dragging touch off screen, and may be pulled upward again to cancel the dismiss
}

/** 类似tableview右侧的index，一种索引模式*/
public enum UIScrollViewIndexDisplayMode : Int {


    case automatic // the index will show or hide automatically as needed

    case alwaysHidden // the index will never be displayed
}

/** 减速常量*/
@available(iOS 3.0, *)
public let UIScrollViewDecelerationRateNormal: CGFloat
@available(iOS 3.0, *)
public let UIScrollViewDecelerationRateFast: CGFloat

@available(iOS 2.0, *)
open class UIScrollView : UIView, NSCoding {

    /** 当前偏移量*/
    open var contentOffset: CGPoint // default CGPointZero

    /** scrollview的可移动范围，通俗点理解就是scrollview的真正大小*/
    open var contentSize: CGSize // default CGSizeZero

    /** 内间距的偏移量*/
    open var contentInset: UIEdgeInsets // default UIEdgeInsetsZero. add additional scroll area around content

    weak open var delegate: UIScrollViewDelegate? // default nil. weak reference

    /** 是否锁定一个方向上的滑动，YES：初始状态下，用户水平滑动，那么垂直方向上的滑动就被禁止；反之亦然。但是如果用户直接斜着滑动，那么便不会锁定某一个方向*/
    open var isDirectionalLockEnabled: Bool // default NO. if YES, try to lock vertical or horizontal scrolling while dragging

    /** 一种弹簧效果（在顶部继续上滑或者底部继续下拉的时候，仅在可滑动的情况下有效）*/
    open var bounces: Bool // default YES. if YES, bounces past edge of content and back again

    /** 我们知道，只有当scrollview的contentsize大于frame（其它可滑动等属性都已设置）的情况下，scrollview才可以滑动并产生弹簧效果；如果设置该属性为YES，那么即使contentsize很小的情况，只要bounces为YES，也可以产生弹簧效果，作用于垂直方向*/
    open var alwaysBounceVertical: Bool // default NO. if YES and bounces is YES, even if content is smaller than bounds, allow drag vertically

    /** 同上，作用于水平方向*/
    open var alwaysBounceHorizontal: Bool // default NO. if YES and bounces is YES, even if content is smaller than bounds, allow drag horizontally

    /** 分页效果，系统会自动根据当前滑动的offset来判断自动滑到哪一页*/
    open var isPagingEnabled: Bool // default NO. if YES, stop on multiples of view bounds

    /** 是否允许用户拖动*/
    open var isScrollEnabled: Bool // default YES. turn off any dragging temporarily

    /** 是否显示水平方向上的指示器*/
    open var showsHorizontalScrollIndicator: Bool // default YES. show indicator while we are tracking. fades out after tracking

    /** 是否显示垂直方向上的指示器*/
    open var showsVerticalScrollIndicator: Bool // default YES. show indicator while we are tracking. fades out after tracking

    /** 指示器的偏移。可以通过该属性来做一些隐性的下拉刷新的效果*/
    open var scrollIndicatorInsets: UIEdgeInsets // default is UIEdgeInsetsZero. adjust indicators inside of insets

    /** 指示器的样式*/
    open var indicatorStyle: UIScrollViewIndicatorStyle // default is UIScrollViewIndicatorStyleDefault

    /** 手指抬起之后scrollview的减速速率,可以使用UIScrollViewDecelerationRateNormal和UIScrollViewDecelerationRateFast这两个常量*/
    @available(iOS 3.0, *)
    open var decelerationRate: CGFloat

    /** 索引模式*/
    open var indexDisplayMode: UIScrollViewIndexDisplayMode

    /** 改变scrollview的contentOffset，如果animated为true，并且已经设置了delegate，那么在动画完成之后会调用“scrollViewDidEndScrollingAnimation”这个代理方法*/
    open func setContentOffset(_ contentOffset: CGPoint, animated: Bool) // animate at constant velocity to new offset

    /** 主要效果同上；通过frame来确定而已*/
    open func scrollRectToVisible(_ rect: CGRect, animated: Bool) // scroll so rect is just visible (nearest edges). nothing if rect completely visible

    /** 短暂的显示一下指示器*/
    open func flashScrollIndicators() // displays the scroll indicators for a short time. This should be done whenever you bring the scroll view to front.


    /*
     Scrolling with no scroll bars is a bit complex. on touch down, we don't know if the user will want to scroll or track a subview like a control.
     on touch down, we start a timer and also look at any movement. if the time elapses without sufficient change in position, we start sending events to
     the hit view in the content subview. if the user then drags far enough, we switch back to dragging and cancel any tracking in the subview.
     the methods below are called by the scroll view and give subclasses override points to add in custom behaviour.
     you can remove the delay in delivery of touchesBegan:withEvent: to subviews by setting delaysContentTouches to NO.
     */

    /** 用户手指触碰但是还没有拖动*/
    open var isTracking: Bool { get } // returns YES if user has touched. may not yet have started dragging

    /** 用户开始拖动*/
    open var isDragging: Bool { get } // returns YES if user has started scrolling. this may require some time and or distance to move to initiate dragging

    /** 用户手指离开了scrollview。  YES：scrollview还会继续滑动*/
    open var isDecelerating: Bool { get } // returns YES if user isn't dragging (touch up) but scroll view is still moving

    /** 该属性可以配合"isTracking"属性来理解。用户手指接触，isTracking为yes，如果这时候用户滑动，并且scrollview开始滑动了，isTracking为No；这时候就算scrollview上面有一个控件（比如button）也不会响应到事件；但是如果将该属性设置为No，那么无论你滑动的多快，事件都会被传递给button*/
    open var delaysContentTouches: Bool // default is YES. if NO, we immediately call -touchesShouldBegin:withEvent:inContentView:. this has no effect on presses

    /** 可以根据SDK备注来理解。默认设置为yes，一旦设置为No之后，触摸使isTracking为yes，但是无论接下来如何移动手指scrollview都不会发生滑动，当然该属性对于压（点击）是无效的*/
    open var canCancelContentTouches: Bool // default is YES. if NO, then once we start tracking, we don't try to drag if the touch moves. this has no effect on presses

    /** 事件是否要传递给其subviews*/
    // override points for subclasses to control delivery of touch events to subviews of the scroll view
    // called before touches are delivered to a subview of the scroll view. if it returns NO the touches will not be delivered to the subview
    // this has no effect on presses
    // default returns YES
    open func touchesShouldBegin(_ touches: Set<UITouch>, with event: UIEvent?, in view: UIView) -> Bool

    // called before scrolling begins if touches have already been delivered to a subview of the scroll view. if it returns NO the touches will continue to be delivered to the subview and scrolling will not occur
    // not called if canCancelContentTouches is NO. default returns YES if view isn't a UIControl
    // this has no effect on presses
    open func touchesShouldCancel(in view: UIView) -> Bool


    /*
     the following properties and methods are for zooming. as the user tracks with two fingers, we adjust the offset and the scale of the content. When the gesture ends, you should update the content
     as necessary. Note that the gesture can end and a finger could still be down. While the gesture is in progress, we do not send any tracking calls to the subview.
     the delegate must implement both viewForZoomingInScrollView: and scrollViewDidEndZooming:withView:atScale: in order for zooming to work and the max/min zoom scale must be different
     note that we are not scaling the actual scroll view but the 'content view' returned by the delegate. the delegate must return a subview, not the scroll view itself, from viewForZoomingInScrollview:
     */

    /** 最小及最大缩放，最大值必须大于等于最小值。并且具体的实现要通过delegate来实现*/
    open var minimumZoomScale: CGFloat // default is 1.0

    open var maximumZoomScale: CGFloat // default is 1.0. must be > minimum zoom scale to enable zooming

    /** 类似setoffset的效果*/
    @available(iOS 3.0, *)
    open var zoomScale: CGFloat // default is 1.0

    @available(iOS 3.0, *)
    open func setZoomScale(_ scale: CGFloat, animated: Bool)

    @available(iOS 3.0, *)
    open func zoom(to rect: CGRect, animated: Bool)

    /** 是否可以超过最大（小）值得缩放(反弹)*/
    open var bouncesZoom: Bool // default is YES. if set, user can go past min/max zoom while gesturing and the zoom will animate to the min/max value at gesture end

    /** 手指未离开的缩放过程*/
    open var isZooming: Bool { get } // returns YES if user in zoom gesture

    /** 手指离开后的反弹动画过程*/
    open var isZoomBouncing: Bool { get } // returns YES if we are in the middle of zooming back to the min/max value


    // When the user taps the status bar, the scroll view beneath the touch which is closest to the status bar will be scrolled to top, but only if its `scrollsToTop` property is YES, its delegate does not return NO from `shouldScrollViewScrollToTop`, and it is not already at the top.
    // On iPhone, we execute this gesture only if there's one on-screen scroll view with `scrollsToTop` == YES. If more than one is found, none will be scrolled.

    /** 系统自带的一种实现功能，点击statusbar可以自动上滑到顶部，但是scrollview的该属性要设置为yes，并且相关代理也需要yes*/
    open var scrollsToTop: Bool // default is YES.


    // Use these accessors to configure the scroll view's built-in gesture recognizers.
    // Do not change the gestures' delegates or override the getters for these properties.

    // Change `panGestureRecognizer.allowedTouchTypes` to limit scrolling to a particular set of touch types.
    @available(iOS 5.0, *)
    /** 手势信息相关，一般可以用户将该手势传递给需要来控制scrollview的控件来实现一些特殊效果*/
    open var panGestureRecognizer: UIPanGestureRecognizer { get }

    // `pinchGestureRecognizer` will return nil when zooming is disabled.
    @available(iOS 5.0, *)
    open var pinchGestureRecognizer: UIPinchGestureRecognizer? { get }

    /** 滑动scrollview的时候键盘的处理(如果存在的话)*/
    @available(iOS 7.0, *)
    open var keyboardDismissMode: UIScrollViewKeyboardDismissMode // default is UIScrollViewKeyboardDismissModeNone

    /** 10.0之后增加的刷新控制机制*/
    @available(iOS 10.0, *)
    open var refreshControl: UIRefreshControl?
}

/** 以下是scrollview的delegate方法*/
public protocol UIScrollViewDelegate : NSObjectProtocol {

    /** 只要scrollview还在滑动就会调用该方法*/
    @available(iOS 2.0, *)
    optional public func scrollViewDidScroll(_ scrollView: UIScrollView) // any offset changes

    /** 只要scrollview还在缩放就会调用该方法*/
    @available(iOS 3.2, *)
    optional public func scrollViewDidZoom(_ scrollView: UIScrollView) // any zoom scale changes

    /** scrollview开始被拖动了*/
    // called on start of dragging (may require some time and or distance to move)
    @available(iOS 2.0, *)
    optional public func scrollViewWillBeginDragging(_ scrollView: UIScrollView)

    // called on finger up if the user dragged. velocity is in points/millisecond. targetContentOffset may be changed to adjust where the scroll view comes to rest

    /** scrollview即将停止被拖动，这时候可以通过设置"targetContentOffset"的值来达到让scrollview平滑的滑到某个位置的效果*/
    @available(iOS 5.0, *)
    optional public func scrollViewWillEndDragging(_ scrollView: UIScrollView, withVelocity velocity: CGPoint, targetContentOffset: UnsafeMutablePointer<CGPoint>)

    /** scrollview停止被拖动，手指刚刚离开scrollview的那一瞬间*/
    /** decelerate: 如果该值为yes，那么scrollview在停止拖动之后还会继续惯性滑动；反之则不会继续滑动而是立即停止*/
    // called on finger up if the user dragged. decelerate is true if it will continue moving afterwards
    @available(iOS 2.0, *)
    optional public func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate decelerate: Bool)

    /** 因为惯性的滑动，scrollview即将减速*/
    @available(iOS 2.0, *)
    optional public func scrollViewWillBeginDecelerating(_ scrollView: UIScrollView) // called on finger up as we are moving

    /** scrollview已经完全减速停止，这时候的scrollview是真正的停下来了*/
    /** 但是如果上面代理中的该值”decelerate“返回为No（即立即停止的情况），是不会调用该代理方法的*/
    @available(iOS 2.0, *)
    optional public func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) // called when scroll view grinds to a halt

    /** 主要在动画设置scrollview的rect，动画停止的时候*/
    @available(iOS 2.0, *)
    optional public func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) // called when setContentOffset/scrollRectVisible:animated: finishes. not called if not animating

    /** scrollview's  subview中需要被缩放的view*/
    @available(iOS 2.0, *)
    optional public func viewForZooming(in scrollView: UIScrollView) -> UIView? // return a view that will be scaled. if delegate returns nil, nothing happens

    /** 即将被缩放*/
    @available(iOS 3.2, *)
    optional public func scrollViewWillBeginZooming(_ scrollView: UIScrollView, with view: UIView?) // called before the scroll view begins zooming its content

    /** 已经缩放*/
    @available(iOS 2.0, *)
    optional public func scrollViewDidEndZooming(_ scrollView: UIScrollView, with view: UIView?, atScale scale: CGFloat) // scale between minimum and maximum. called after any 'bounce' animations

    /** 是否支持点击statusbar返回top，默认yes*/
    @available(iOS 2.0, *)
    optional public func scrollViewShouldScrollToTop(_ scrollView: UIScrollView) -> Bool // return a yes if you want to scroll to the top. if not defined, assumes YES

    /** 已经返回至top*/
    @available(iOS 2.0, *)
    optional public func scrollViewDidScrollToTop(_ scrollView: UIScrollView) // called when scrolling animation finished. may be called immediately if already at top
}