UIScrollView文档翻译

//

//  UIScrollView.h

//  UIKit

//

//  Copyright (c) 2007-2015 Apple Inc. All rights reserved.

//

#import <Foundation/Foundation.h>

#import <CoreGraphics/CoreGraphics.h>

#import <UIKit/UIView.h>

#import <UIKit/UIGeometry.h>

#import <UIKit/UIKitDefines.h>

NS_ASSUME_NONNULL_BEGIN

// ---------------------------------------------------------------------------------------------------------------------------------------------------

typedef NS_ENUM(NSInteger, UIScrollViewIndicatorStyle) {

    UIScrollViewIndicatorStyleDefault,     // black with white border. good against any background黑与白边，在任何背景下都很好

    UIScrollViewIndicatorStyleBlack,       // black only. smaller. good against a white background只有黑色，小，在白色背景下良好

    UIScrollViewIndicatorStyleWhite        // white only. smaller. good against a black background只有白色，小，在黑色背景下良好

};

typedef NS_ENUM(NSInteger, UIScrollViewKeyboardDismissMode) {

    UIScrollViewKeyboardDismissModeNone,

    UIScrollViewKeyboardDismissModeOnDrag,      // dismisses the keyboard when a drag begins当拖动时键盘消失

    UIScrollViewKeyboardDismissModeInteractive, // the keyboard follows the dragging touch off screen, and may be pulled upward again to cancel the dismiss 键盘跟随拖动触摸屏，并可能再次向上拉，取消消失

} NS_ENUM_AVAILABLE_IOS(7_0);

UIKIT_EXTERN const CGFloat UIScrollViewDecelerationRateNormal NS_AVAILABLE_IOS(3_0);

UIKIT_EXTERN const CGFloat UIScrollViewDecelerationRateFast NS_AVAILABLE_IOS(3_0);

@class UIEvent, UIImageView, UIPanGestureRecognizer, UIPinchGestureRecognizer;

@protocol UIScrollViewDelegate;

NS_CLASS_AVAILABLE_IOS(2_0)@interface UIScrollView : UIView <NSCoding>

// ---------------------------------------------------------------------------------------------------------------------------------------------------

@property(nonatomic)         CGPoint                      contentOffset;                 // default CGPointZero 在滚动视图中，contentOffset属性可以跟踪UIScrollView的具体位置，你能够自己获取和设置它，contentOffset的值是你当前可视内容在滚动视图上面偏移原来的左上角的偏移量

@property(nonatomic)         CGSize                       contentSize;                   // default CGSizeZerocontentSize是内容大小，也就是可以滚动的大小，默认是0，没有滚动效果

@property(nonatomic)         UIEdgeInsets                 contentInset;                  // default UIEdgeInsetsZero. add additional scroll area around contentcontentInset增加你在contentSize中指定的内容能够滚动的上下左右区域的距离。

@property(nullable,nonatomic,weak)id<UIScrollViewDelegate>        delegate;                      // default nil. weak reference

@property(nonatomic,getter=isDirectionalLockEnabled)BOOL directionalLockEnabled;        // default NO. if YES, try to lock vertical or horizontal scrolling while dragging默认是NO，可以在垂直和水平方向同时运动。当值是YES时，假如一开始是垂直或者水平运动，那么接下来会送定另外一个方向的滚动，加入一开始是对角方向移动，则不会禁止某个方向

@property(nonatomic)        BOOL                         bounces;                       // default YES. if YES, bounces past edge of content and back again默认是YES，就是滚动超过边界会反弹，有反弹回来的效果，如果是NO，那么滚动到达边界会立即停止

@property(nonatomic)        BOOL                         alwaysBounceVertical;          // default NO. if YES and bounces is YES, even if content is smaller than bounds, allow drag vertically默认是NO，如果是YES并且边界可以反弹，即使边界比较小，允许垂直拖动

@property(nonatomic)        BOOL                         alwaysBounceHorizontal;        // default NO. if YES and bounces is YES, even if content is smaller than bounds, allow drag horizontally默认是NO，如果是YES并且边界可以反弹，即使边界比较小，允许横向拖动

@property(nonatomic,getter=isPagingEnabled)BOOL          pagingEnabled __TVOS_PROHIBITED;// default NO. if YES, stop on multiples of view bounds当值是YES会自动滚到视图边界的倍数上，默认为NO（也就是是否整页翻动）

@property(nonatomic,getter=isScrollEnabled)BOOL          scrollEnabled;                 // default YES. turn off any dragging temporarily默认是YES，决定是否可以滚动

@property(nonatomic)        BOOL                         showsHorizontalScrollIndicator;// default YES. show indicator while we are tracking. fades out after isTracking滚动时是否显示水平滚动条

@property(nonatomic)        BOOL                         showsVerticalScrollIndicator;  // default YES. show indicator while we are tracking. fades out after tracking 滚动时是否显示垂直滚动条

@property(nonatomic)         UIEdgeInsets                 scrollIndicatorInsets;         // default is UIEdgeInsetsZero. adjust indicators inside of insets设置滚动条的位置

@property(nonatomic)         UIScrollViewIndicatorStyle   indicatorStyle;                // default is UIScrollViewIndicatorStyleDefault滚动条的样式，基本只是设置颜色，总共3个颜色：默认、黑、白

@property(nonatomic)         CGFloat                      decelerationRate NS_AVAILABLE_IOS(3_0);// 设置手指放开后的减速率

- (void)setContentOffset:(CGPoint)contentOffset animated:(BOOL)animated; // animate at constant velocity to new offset 以恒定速度的动画到新的偏移量

- (void)scrollRectToVisible:(CGRect)rect animated:(BOOL)animated;        // scroll so rect is just visible (nearest edges). nothing if rect completely visible 

// 上面这两个函数用来自动滚到想要的位置，此过程中设置有动画效果，停止时，触发该函数。当animated为YES的时候有动画效果

- (void)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.

没有滚动条的滚动是一个有点复杂的。在触摸结束后，我们不知道用户将要滚动画着跟踪视图像控制。

在接触下来，我们开始一个计时器，也看任何运动。如果没有足够的时间改变位置，我们开始向中观的内容试图发送事件。如果用户拖拽足够远，我们切换回拖和取消在子视图的任何跟踪。

下面的方法是由滚动视图调用的，给子类重写点添加自定义行为。

你可以删除交货延迟 touchesBegen：withEvent：设置子视图的delaysContentTouches

 */

@property(nonatomic,readonly,getter=isTracking)     BOOL tracking;       // returns YES if user has touched. may not yet have started dragging当用户touch后还没有开始拖动的时候是YES，否则为NO

@property(nonatomic,readonly,getter=isDragging)     BOOL dragging;       // returns YES if user has started scrolling. this may require some time and or distance to move to initiate dragging如果scrollView正在被拖动，返回YES（检测当前目标是否正在被拖拽）

@property(nonatomic,readonly,getter=isDecelerating)BOOL decelerating;   // returns YES if user isn't dragging (touch up) but scroll view is still moving当滚动后，手指放开但是孩子啊继续滚动中。这个时候是YES，其他时候是NO（监控当前目标是否正在减速）

@property(nonatomic)BOOL delaysContentTouches;      // default is YES. if NO, we immediately call -touchesShouldBegin:withEvent:inContentView:. this has no effect on presses默认是YES，当值是YES的时候，用户触碰开始，scrollView要延迟一会，看看用户是否有意图滚动。加入滚动了，那么捕捉touch-down时间，否则就不捕捉。加入值是NO，当用户触碰，scrollView会立即触发（控制试图是否延时调用开始滚动的方法）

@property(nonatomic)BOOL canCancelContentTouches;   // 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当值是YES的时候，用户触碰后，然后在一定时间内没有移动，scrollView发送tracking events，然后用户移动手指足够长度触发滚动事件，这个时候scrollView发送了touchesCancelled：withEvent：到subView，然后scrollView开始滚动。假如为NO，scrollView发送tracking events后，就算用户移动手指，scrollView也不会滚动（控制控件是否接触取消touch的事件）

// 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 默认返回是

- (BOOL)touchesShouldBegin:(NSSet<UITouch *> *)touches withEvent:(nullable UIEvent *)event inContentView:(UIView *)view;

// 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

- (BOOL)touchesShouldCancelInContentView:(UIView *)view;// 开始发送tracking message消息给subview的时候调用这个方法，决定是否发送tracking message消息给subView，假如返回NO，发送，YES则不发送

/*

 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:

 */

@property(nonatomic) CGFloat minimumZoomScale;    // default is 1.0 表示能缩最小的倍数

@property(nonatomic) CGFloat maximumZoomScale;    // default is 1.0. must be > minimum zoom scale to enable zooming表示能放最大的倍数

@property(nonatomic) CGFloat zoomScale NS_AVAILABLE_IOS(3_0);           // default is 1.0

- (void)setZoomScale:(CGFloat)scale animated:(BOOL)animated NS_AVAILABLE_IOS(3_0);

- (void)zoomToRect:(CGRect)rect animated:(BOOL)animated NS_AVAILABLE_IOS(3_0);

@property(nonatomic)BOOL  bouncesZoom;         // 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和bounces类似，区别在于：这个效果反应在缩放方面加入缩放超过最大缩放，那么会有反弹效果；假如是NO，则到达最大或者最小的时候立即停止

@property(nonatomic,readonly,getter=isZooming)       BOOL zooming;      // returns YES if user in zoom gesture 当正在缩放的时候是YES，否则是NO

@property(nonatomic,readonly,getter=isZoomBouncing) BOOL zoomBouncing; // returns YES if we are in the middle of zooming back to the min/max value当内容放大到最大或者缩小到最小的时候值是YES，否则是NO

// 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.

@property(nonatomic)BOOL  scrollsToTop __TVOS_PROHIBITED;         // 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.

@property(nonatomic,readonly) UIPanGestureRecognizer *panGestureRecognizer NS_AVAILABLE_IOS(5_0);

// `pinchGestureRecognizer` will return nil when zooming is disabled.

@property(nullable,nonatomic, readonly) UIPinchGestureRecognizer *pinchGestureRecognizer NS_AVAILABLE_IOS(5_0);

// `directionalPressGestureRecognizer` is disabled by default, but can be enabled to perform scrolling in response to up / down / left / right arrow button presses directly, instead of scrolling indirectly in response to focus updates.

@property(nonatomic,readonly) UIGestureRecognizer *directionalPressGestureRecognizer UIKIT_AVAILABLE_TVOS_ONLY(9_0);

@property(nonatomic) UIScrollViewKeyboardDismissMode keyboardDismissMode NS_AVAILABLE_IOS(7_0);// default is UIScrollViewKeyboardDismissModeNone

@end

// ---------------------------------------------------------------------------------------------------------------------------------------------------

@protocol UIScrollViewDelegate<NSObject>

@optional

// scrollView已经滑动

- (void)scrollViewDidScroll:(UIScrollView *)scrollView;                                              // any offset changes

// 视图已经放大或者缩小

- (void)scrollViewDidZoom:(UIScrollView *)scrollView NS_AVAILABLE_IOS(3_2);// any zoom scale changes

// scrollView开始拖动called on start of dragging (may require some time and or distance to move)

- (void)scrollViewWillBeginDragging:(UIScrollView *)scrollView; 

// scrollView即将停止拖拽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

- (void)scrollViewWillEndDragging:(UIScrollView *)scrollView withVelocity:(CGPoint)velocity targetContentOffset:(inout CGPoint *)targetContentOffset NS_AVAILABLE_IOS(5_0);

// scrollView结束拖动called on finger up if the user dragged. decelerate is true if it will continue moving afterwards

- (void)scrollViewDidEndDragging:(UIScrollView *)scrollView willDecelerate:(BOOL)decelerate;

// scrollView即将减速完成

- (void)scrollViewWillBeginDecelerating:(UIScrollView *)scrollView;  // called on finger up as we are moving

// scrollView减速完成

- (void)scrollViewDidEndDecelerating:(UIScrollView *)scrollView;     // called when scroll view grinds to a halt

// scrollView结束减速并且必须有动画效果才会触发（必须要有动画效果）

- (void)scrollViewDidEndScrollingAnimation:(UIScrollView *)scrollView;// called when setContentOffset/scrollRectVisible:animated: finishes. not called if not animating

// 返回缩放后的试图，但只能返回scrollView（内容）上的子视图

- (nullable UIView *)viewForZoomingInScrollView:(UIScrollView *)scrollView;    // return a view that will be scaled. if delegate returns nil, nothing happens

// 开始缩放

- (void)scrollViewWillBeginZooming:(UIScrollView *)scrollView withView:(nullable UIView *)view NS_AVAILABLE_IOS(3_2);// called before the scroll view begins zooming its content

// 结束缩放

- (void)scrollViewDidEndZooming:(UIScrollView *)scrollView withView:(nullable UIView *)view atScale:(CGFloat)scale;// scale between minimum and maximum. called after any 'bounce' animations

// 点击状态栏，调用此方法，此方法能实现的前提是scrollToTop的属性是YES

- (BOOL)scrollViewShouldScrollToTop:(UIScrollView *)scrollView;  // return a yes if you want to scroll to the top. if not defined, assumes YES

// scrollView已经回到顶部了

- (void)scrollViewDidScrollToTop:(UIScrollView *)scrollView;     // called when scrolling animation finished. may be called immediately if already at top

@end

NS_ASSUME_NONNULL_END