Protocols

Objective-C

@protocol QMUIToastAnimatorDelegate <NSObject>

Swift

protocol QMUIToastAnimatorDelegate : NSObjectProtocol

Objective-C

@protocol QMUIAlertControllerDelegate <NSObject>

@optional

- (void)willShowAlertController:(QMUIAlertController *)alertController;
- (void)willHideAlertController:(QMUIAlertController *)alertController;
- (void)didShowAlertController:(QMUIAlertController *)alertController;
- (void)didHideAlertController:(QMUIAlertController *)alertController;
- (BOOL)shouldHideAlertController:(QMUIAlertController *)alertController;

@end

Swift

protocol QMUIAlertControllerDelegate : NSObjectProtocol

Objective-C

@protocol QMUIModalPresentationContentViewControllerProtocol <NSObject>

@optional

/**
 *  当浮层以 UIViewController 的形式展示（而非 UIView），并且使用 modalController 提供的默认布局时，则可通过这个方法告诉 modalController 当前浮层期望的大小。如果 modalController 实现了自己的 layoutBlock，则可不实现这个方法，实现了也不一定按照这个方法的返回值来布局，完全取决于 layoutBlock。
 *  @param  controller  当前的modalController
 *  @param  keyboardHeight 当前的键盘高度，如果键盘降下，则为0
 *  @param  limitSize   浮层最大的宽高，由当前 modalController 的大小及 `contentViewMargins`、`maximumContentViewWidth` 和键盘高度决定
 *  @return 返回浮层在 `limitSize` 限定内的大小，如果业务自身不需要限制宽度/高度，则为 width/height 返回 `CGFLOAT_MAX` 即可
 */
- (CGSize)preferredContentSizeInModalPresentationViewController:(QMUIModalPresentationViewController *)controller keyboardHeight:(CGFloat)keyboardHeight limitSize:(CGSize)limitSize;

@end

Swift

protocol QMUIModalPresentationContentViewControllerProtocol : NSObjectProtocol

Objective-C

@protocol QMUIModalPresentationViewControllerDelegate <NSObject>

@optional

/**
 *  是否应该隐藏浮层，会在调用`hideWithAnimated:completion:`时，以及点击背景遮罩时被调用。默认为YES。
 *  @param  controller  当前的modalController
 *  @return 是否允许隐藏，YES表示允许隐藏，NO表示不允许隐藏
 */
- (BOOL)shouldHideModalPresentationViewController:(QMUIModalPresentationViewController *)controller;

/**
 *  modalController 即将隐藏时的回调方法，在调用完这个方法后才开始做一些隐藏前的准备工作，例如恢复 window 的 dimmed 状态等。
 *  @param  controller  当前的modalController
 */
- (void)willHideModalPresentationViewController:(QMUIModalPresentationViewController *)controller;

/**
 *  modalController隐藏后的回调方法，不管是直接调用`hideWithAnimated:completion:`，还是通过点击遮罩触发的隐藏，都会调用这个方法。
 *  如果你想区分这两种方式的隐藏回调，请直接使用hideWithAnimated方法的completion参数，以及`didHideByDimmingViewTappedBlock`属性。
 *  @param  controller  当前的modalController
 */
- (void)didHideModalPresentationViewController:(QMUIModalPresentationViewController *)controller;

@end

Swift

protocol QMUIModalPresentationViewControllerDelegate : NSObjectProtocol

Objective-C

@protocol QMUIModalPresentationComponentProtocol <NSObject>

Swift

protocol QMUIModalPresentationComponentProtocol : NSObjectProtocol

Objective-C

@protocol QMUIWindowSizeMonitorProtocol <NSObject>

@optional

/**
 当继承自 UIResponder 的对象，比如 UIView 或 UIViewController 实现了这个方法时，其所属的 window 在大小发生改变后在这个方法回调。
 @note 类似系统的 [-viewWillTransitionToSize:withTransitionCoordinator:]，但是系统这个方法回调时 window 的大小实际上还未发生改变，如果你需要在 window 大小发生之后且在 layout 之前来处理一些逻辑时，可以放到这个方法去实现。
 @note 如果子类和父类同时实现了该方法，则两个方法均会被调用，调用顺序是先父类后子类。
 @param size 所属窗口的新大小
 */

- (void)windowDidTransitionToSize:(CGSize)size;

@end

Swift

protocol QMUIWindowSizeMonitorProtocol : NSObjectProtocol

Objective-C

@protocol QMUICellSizeKeyCache_UICollectionViewDelegate <NSObject>

@optional
- (nonnull id<NSCopying>)qmui_collectionView:(nonnull UICollectionView *)collectionView cacheKeyForItemAtIndexPath:(nonnull NSIndexPath *)indexPath;
@end

Swift

protocol QMUICellSizeKeyCache_UICollectionViewDelegate : NSObjectProtocol

Objective-C

@protocol QMUIImagePreviewViewDelegate <QMUIZoomImageViewDelegate>

@required
- (NSUInteger)numberOfImagesInImagePreviewView:(QMUIImagePreviewView *)imagePreviewView;
- (void)imagePreviewView:(QMUIImagePreviewView *)imagePreviewView renderZoomImageView:(QMUIZoomImageView *)zoomImageView atIndex:(NSUInteger)index;

@optional
// 返回要展示的媒体资源的类型（图片、live photo、视频），如果不实现此方法，则 QMUIImagePreviewView 将无法选择最合适的 cell 来复用从而略微增大系统开销
- (QMUIImagePreviewMediaType)imagePreviewView:(QMUIImagePreviewView *)imagePreviewView assetTypeAtIndex:(NSUInteger)index;

/**
 *  当左右的滚动停止时会触发这个方法
 *  @param  imagePreviewView 当前预览的 QMUIImagePreviewView
 *  @param  index 当前滚动到的图片所在的索引
 */
- (void)imagePreviewView:(QMUIImagePreviewView *)imagePreviewView didScrollToIndex:(NSUInteger)index;

/**
 *  在滚动过程中，如果某一张图片的边缘（左/右）经过预览控件的中心点时，就会触发这个方法
 *  @param  imagePreviewView 当前预览的 QMUIImagePreviewView
 *  @param  index 当前滚动到的图片所在的索引
 */
- (void)imagePreviewView:(QMUIImagePreviewView *)imagePreviewView willScrollHalfToIndex:(NSUInteger)index;

@end

Swift

protocol QMUIImagePreviewViewDelegate : QMUIZoomImageViewDelegate

Objective-C

@protocol QMUIZoomImageViewDelegate <NSObject>
@optional
- (void)singleTouchInZoomingImageView:(QMUIZoomImageView *)zoomImageView location:(CGPoint)location;
- (void)doubleTouchInZoomingImageView:(QMUIZoomImageView *)zoomImageView location:(CGPoint)location;
- (void)longPressInZoomingImageView:(QMUIZoomImageView *)zoomImageView;

/**
 *  告知 delegate 用户点击了 iCloud 图片的重试按钮
 */
- (void)didTouchICloudRetryButtonInZoomImageView:(QMUIZoomImageView *)imageView;

/**
 *  告知 delegate 在视频预览界面里，由于用户点击了空白区域或播放视频等导致了底部的视频工具栏被显示或隐藏
 *  @param didHide 如果为 YES 则表示工具栏被隐藏，NO 表示工具栏被显示了出来
 */
- (void)zoomImageView:(QMUIZoomImageView *)imageView didHideVideoToolbar:(BOOL)didHide;

/// 是否支持缩放，默认为 YES
- (BOOL)enabledZoomViewInZoomImageView:(QMUIZoomImageView *)zoomImageView;

@end

Swift

protocol QMUIZoomImageViewDelegate : NSObjectProtocol

Objective-C

@protocol QMUIDynamicEffectProtocol <NSObject>

@required

/// 获取当前 UIVisualEffect 的实际 effect（返回的 effect 必定不是 dynamic image）
@property(nonatomic, strong, readonly) __kindof UIVisualEffect *qmui_rawEffect;

/// 标志当前 UIVisualEffect 对象是否为动态 effect（由 [UIVisualEffect qmui_effectWithThemeProvider:] 创建的 effect
@property(nonatomic, assign, readonly) BOOL qmui_isDynamicEffect;

@end

Swift

protocol QMUIDynamicEffectProtocol : NSObjectProtocol

Objective-C

@protocol QMUIDynamicImageProtocol <NSObject>

@required

/// 获取当前 UIImage 的实际图片（返回的图片必定不是 dynamic image）
@property(nonatomic, strong, readonly) UIImage *qmui_rawImage;

/// 标志当前 UIImage 对象是否为动态图片（由 [UIImage qmui_imageWithThemeProvider:] 创建的颜色
@property(nonatomic, assign, readonly) BOOL qmui_isDynamicImage;

@end

Swift

protocol QMUIDynamicImageProtocol : NSObjectProtocol

Objective-C

@protocol QMUILoggerDelegate <NSObject>

@optional

/**
 *  当每一个 enabled 的 QMUILog 被使用时都会走到这里，可以由业务自行决定要如何处理这些 log，如果没实现这个方法，默认用 NSLog() 打印内容
 *  @param file 当前的文件的本地完整路径，可通过 file.lastPathComponent 获取文件名
 *  @param line 当前 log 命令在该文件里的代码行数
 *  @param func 当前 log 命令所在的方法名
 *  @param logItem 当前 log 命令对应的 QMUILogItem，可得知该 log 的 level
 *  @param defaultString QMUI 默认拼好的 log 内容
 */
- (void)printQMUILogWithFile:(nonnull NSString *)file line:(int)line func:(nullable NSString *)func logItem:(nullable QMUILogItem *)logItem defaultString:(nullable NSString *)defaultString;

/**
 *  当某个 logName 的 enabled 发生变化时，通知到 delegate。注意如果是新创建某个 logName 也会走到这里。
 *  @param logName 变化的 logName
 *  @param enabled 变化后的值
 */
- (void)QMUILogName:(nonnull NSString *)logName didChangeEnabled:(BOOL)enabled;

/**
 *  某个 logName 被删除时通知到 delegate
 *  @param logName 被删除的 logName
 */
- (void)QMUILogNameDidRemove:(nonnull NSString *)logName;

@end

Swift

protocol QMUILoggerDelegate : NSObjectProtocol

Objective-C

@protocol QMUITextFieldDelegate <UITextFieldDelegate>

@optional

/**
 *  配合 `maximumTextLength` 属性使用，在输入文字超过限制时被调用。
 *  @warning 在 UIControlEventEditingChanged 里也会触发文字长度拦截，由于此时 textField 的文字已经改变完，所以无法得知发生改变的文本位置及改变的文本内容，所以此时 range 和 replacementString 这两个参数的值也会比较特殊，具体请看参数讲解。
 *
 *  @param textField 触发的 textField
 *  @param range 要变化的文字的位置，如果在 UIControlEventEditingChanged 里，这里的 range 也即文字变化后的 range，所以可能比最大长度要大。
 *  @param replacementString 要变化的文字，如果在 UIControlEventEditingChanged 里，这里永远传入 nil。
 */
- (void)textField:(QMUITextField *)textField didPreventTextChangeInRange:(NSRange)range replacementString:(NSString *)replacementString;

@end

Swift

protocol QMUITextFieldDelegate : UITextFieldDelegate

Objective-C

@protocol QMUINavigationTitleViewDelegate <NSObject>

@optional

/**
 点击 titleView 后的回调，只需设置 titleView.userInteractionEnabled = YES 后即可使用。不过一般都用于配合 QMUINavigationTitleViewAccessoryTypeDisclosureIndicator。

 @param titleView 被点击的 titleView
 @param isActive titleView 是否处于活跃状态（所谓的活跃，对应右边的箭头而言，就是点击后箭头向上的状态）
 */
- (void)didTouchTitleView:(QMUINavigationTitleView *)titleView isActive:(BOOL)isActive;

/**
 titleView 的活跃状态发生变化时会被调用，也即 [titleView setActive:] 被调用时。

 @param active 是否处于活跃状态
 @param titleView 变换状态的 titleView
 */
- (void)didChangedActive:(BOOL)active forTitleView:(QMUINavigationTitleView *)titleView;

@end

Swift

protocol QMUINavigationTitleViewDelegate : NSObjectProtocol

Objective-C

@protocol QMUIAlbumViewControllerDelegate <NSObject>

@required
/// 点击相簿里某一行时，需要给一个 QMUIImagePickerViewController 对象用于展示九宫格图片列表
- (QMUIImagePickerViewController *)imagePickerViewControllerForAlbumViewController:(QMUIAlbumViewController *)albumViewController;

@optional
/**
 *  取消查看相册列表后被调用
 */
- (void)albumViewControllerDidCancel:(QMUIAlbumViewController *)albumViewController;

/**
 *  即将需要显示 Loading 时调用
 *
 *  @see shouldShowDefaultLoadingView
 */
- (void)albumViewControllerWillStartLoading:(QMUIAlbumViewController *)albumViewController;

/**
 *  即将需要隐藏 Loading 时调用
 *
 *  @see shouldShowDefaultLoadingView
 */
- (void)albumViewControllerWillFinishLoading:(QMUIAlbumViewController *)albumViewController;

@end

Swift

protocol QMUIAlbumViewControllerDelegate : NSObjectProtocol

Objective-C

@protocol QMUIImagePickerPreviewViewControllerDelegate <NSObject>

@optional

/// 取消选择图片后被调用
- (void)imagePickerPreviewViewControllerDidCancel:(QMUIImagePickerPreviewViewController *)imagePickerPreviewViewController;
/// 即将选中图片
- (void)imagePickerPreviewViewController:(QMUIImagePickerPreviewViewController *)imagePickerPreviewViewController willCheckImageAtIndex:(NSInteger)index;
/// 已经选中图片
- (void)imagePickerPreviewViewController:(QMUIImagePickerPreviewViewController *)imagePickerPreviewViewController didCheckImageAtIndex:(NSInteger)index;
/// 即将取消选中图片
- (void)imagePickerPreviewViewController:(QMUIImagePickerPreviewViewController *)imagePickerPreviewViewController willUncheckImageAtIndex:(NSInteger)index;
/// 已经取消选中图片
- (void)imagePickerPreviewViewController:(QMUIImagePickerPreviewViewController *)imagePickerPreviewViewController didUncheckImageAtIndex:(NSInteger)index;

@end

Swift

protocol QMUIImagePickerPreviewViewControllerDelegate : NSObjectProtocol

Objective-C

@protocol QMUIImagePickerViewControllerDelegate <NSObject>

@optional

/**
 *  创建一个 ImagePickerPreviewViewController 用于预览图片
 */
- (QMUIImagePickerPreviewViewController *)imagePickerPreviewViewControllerForImagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController;

/**
 *  控制照片的排序，若不实现，默认为 QMUIAlbumSortTypePositive
 *  @note 注意返回值会决定第一次进来相片列表时列表默认的滚动位置，如果为 QMUIAlbumSortTypePositive，则列表默认滚动到底部，如果为 QMUIAlbumSortTypeReverse，则列表默认滚动到顶部。
 */
- (QMUIAlbumSortType)albumSortTypeForImagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController;

/**
 *  多选模式下选择图片完毕后被调用（点击 sendButton 后被调用），单选模式下没有底部发送按钮，所以也不会走到这个delegate
 *
 *  @param imagePickerViewController 对应的 QMUIImagePickerViewController
 *  @param imagesAssetArray          包含被选择的图片的 QMUIAsset 对象的数组。
 */
- (void)imagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController didFinishPickingImageWithImagesAssetArray:(NSMutableArray<QMUIAsset *> *)imagesAssetArray;

/**
 *  cell 被点击时调用（先调用这个接口，然后才去走预览大图的逻辑），注意这并非指选中 checkbox 事件
 *
 *  @param imagePickerViewController        对应的 QMUIImagePickerViewController
 *  @param imageAsset                       被选中的图片的 QMUIAsset 对象
 *  @param imagePickerPreviewViewController 选中图片后进行图片预览的 viewController
 */
- (void)imagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController didSelectImageWithImagesAsset:(QMUIAsset *)imageAsset afterImagePickerPreviewViewControllerUpdate:(QMUIImagePickerPreviewViewController *)imagePickerPreviewViewController;

/// 是否能够选中 checkbox
- (BOOL)imagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController shouldCheckImageAtIndex:(NSInteger)index;

/// 即将选中 checkbox 时调用
- (void)imagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController willCheckImageAtIndex:(NSInteger)index;

/// 选中了 checkbox 之后调用
- (void)imagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController didCheckImageAtIndex:(NSInteger)index;

/// 即将取消选中 checkbox 时调用
- (void)imagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController willUncheckImageAtIndex:(NSInteger)index;

/// 取消了 checkbox 选中之后调用
- (void)imagePickerViewController:(QMUIImagePickerViewController *)imagePickerViewController didUncheckImageAtIndex:(NSInteger)index;

/**
 *  取消选择图片后被调用
 */
- (void)imagePickerViewControllerDidCancel:(QMUIImagePickerViewController *)imagePickerViewController;

/**
 *  即将需要显示 Loading 时调用
 *
 *  @see shouldShowDefaultLoadingView
 */
- (void)imagePickerViewControllerWillStartLoading:(QMUIImagePickerViewController *)imagePickerViewController;

/**
 *  即将需要隐藏 Loading 时调用
 *
 *  @see shouldShowDefaultLoadingView
 */
- (void)imagePickerViewControllerDidFinishLoading:(QMUIImagePickerViewController *)imagePickerViewController;

@end

Swift

protocol QMUIImagePickerViewControllerDelegate : NSObjectProtocol

Objective-C

@protocol QMUICellHeightCache_UITableViewDataSource

@optional
/// 搭配 QMUICellHeightCache 使用，对于 UITableView 而言如果要用 QMUICellHeightCache 那套高度计算方式，则必须实现这个方法
- (nullable __kindof UITableViewCell *)qmui_tableView:(nullable UITableView *)tableView cellWithIdentifier:(nonnull NSString *)identifier;

@end

Swift

protocol QMUICellHeightCache_UITableViewDataSource

Objective-C

@protocol QMUICellHeightKeyCache_UITableViewDelegate <NSObject>

@optional

- (nonnull id<NSCopying>)qmui_tableView:(nonnull UITableView *)tableView cacheKeyForRowAtIndexPath:(nonnull NSIndexPath *)indexPath;
@end

Swift

protocol QMUICellHeightKeyCache_UITableViewDelegate : NSObjectProtocol

Objective-C

@protocol QMUITableViewDelegate <UITableViewDelegate, QMUICellHeightKeyCache_UITableViewDelegate>

@optional

/**
 * 自定义要在<i>- (BOOL)touchesShouldCancelInContentView:(UIView *)view</i>内的逻辑<br/>
 * 若delegate不实现这个方法，则默认对所有UIControl返回NO（UIButton除外，它会返回YES），非UIControl返回YES。
 */
- (BOOL)tableView:(nonnull QMUITableView *)tableView touchesShouldCancelInContentView:(nonnull UIView *)view;

@end

Swift

protocol QMUITableViewDelegate : UITableViewDelegate, QMUICellHeightKeyCache_UITableViewDelegate

Objective-C

@protocol QMUITableViewDataSource <UITableViewDataSource, QMUICellHeightCache_UITableViewDataSource>

@end

Swift

protocol QMUITableViewDataSource : UITableViewDataSource, QMUICellHeightCache_UITableViewDataSource

Objective-C

@protocol QMUIPopupMenuItemProtocol <NSObject>

/// item 里的文字
@property(nonatomic, copy, nullable) NSString *title;

/// item 的高度，默认为 -1。小于 0 的值均表示高度以 QMUIPopupMenuView.itemHeight 为准，当需要给某个 item 指定特定高度时才需要用这个 height 属性。
@property(nonatomic, assign) CGFloat height;

/// item 被点击时的事件处理，需要在内部自行隐藏 QMUIPopupMenuView。
@property(nonatomic, copy, nullable) void (^handler)(__kindof NSObject<QMUIPopupMenuItemProtocol> *aItem);

/// 当前 item 所在的 QMUIPopupMenuView 的引用，只有在 item 被添加到菜单之后才有值。
@property(nonatomic, weak, nullable) QMUIPopupMenuView *menuView;

/// item 被添加到 menuView 之后（也即 menuView 属性有值了）会被调用，可在这个方法里更新 item 的样式（因为某些样式可能需要从 menuView 那边读取）
- (void)updateAppearance;

@end

Swift

protocol QMUIPopupMenuItemProtocol : NSObjectProtocol

Objective-C

@protocol QMUIMoreOperationControllerDelegate <NSObject>

@optional

/// 即将显示操作面板
- (void)willPresentMoreOperationController:(QMUIMoreOperationController *)moreOperationController;

/// 已经显示操作面板
- (void)didPresentMoreOperationController:(QMUIMoreOperationController *)moreOperationController;

/// 即将降下操作面板，cancelled参数是用来区分是否触发了maskView或者cancelButton按钮降下面板还是手动调用hide方法来降下面板。
- (void)willDismissMoreOperationController:(QMUIMoreOperationController *)moreOperationController cancelled:(BOOL)cancelled;

/// 已经降下操作面板，cancelled参数是用来区分是否触发了maskView或者cancelButton按钮降下面板还是手动调用hide方法来降下面板。
- (void)didDismissMoreOperationController:(QMUIMoreOperationController *)moreOperationController cancelled:(BOOL)cancelled;

/// itemView 点击事件，可以与 itemView.handler 共存，可通过 itemView.tag 或者 itemView.indexPath 来区分不同的 itemView
- (void)moreOperationController:(QMUIMoreOperationController *)moreOperationController didSelectItemView:(QMUIMoreOperationItemView *)itemView;
@end

Swift

protocol QMUIMoreOperationControllerDelegate : NSObjectProtocol

Objective-C

@protocol QMUIEmptyViewLoadingViewProtocol <NSObject>

@optional

- (void)startAnimating; // 当调用 setLoadingViewHidden:NO 时，系统将自动调用此处的 startAnimating

@end

Swift

protocol QMUIEmptyViewLoadingViewProtocol : NSObjectProtocol

Objective-C

@protocol QMUIKeyboardManagerDelegate <NSObject>

Swift

protocol QMUIKeyboardManagerDelegate : NSObjectProtocol

Objective-C

@protocol QMUITextViewDelegate <UITextViewDelegate>

@optional
/**
 *  输入框高度发生变化时的回调，当实现了这个方法后，文字输入过程中就会不断去计算输入框新内容的高度，并通过这个方法通知到 delegate
 *  @note 只有当内容高度与当前输入框的高度不一致时才会调用到这里，所以无需在内部做高度是否变化的判断。
 */
- (void)textView:(QMUITextView *)textView newHeightAfterTextChanged:(CGFloat)height;

/**
 *  用户点击键盘的 return 按钮时的回调（return 按钮本质上是输入换行符“\n”）
 *  @return 返回 YES 表示程序认为当前的点击是为了进行类似“发送”之类的操作，所以最终“\n”并不会被输入到文本框里。返回 NO 表示程序认为当前的点击只是普通的输入，所以会继续询问 textView:shouldChangeTextInRange:replacementText: 方法，根据该方法的返回结果来决定是否要输入这个“\n”。
 *  @see maximumTextLength
 */
- (BOOL)textViewShouldReturn:(QMUITextView *)textView;

/**
 *  配合 `maximumTextLength` 属性使用，在输入文字超过限制时被调用。例如如果你的输入框在按下键盘“Done”按键时做一些发送操作，就可以在这个方法里判断 [replacementText isEqualToString:@"\n"]。
 *  @warning 在 textViewDidChange: 里也会触发文字长度拦截，由于此时 textView 的文字已经改变完，所以无法得知发生改变的文本位置及改变的文本内容，所以此时 range 和 replacementText 这两个参数的值也会比较特殊，具体请看参数讲解。
 *
 *  @param textView 触发的 textView
 *  @param range 要变化的文字的位置，如果在 textViewDidChange: 里，这里的 range 也即文字变化后的 range，所以可能比最大长度要大。
 *  @param replacementText 要变化的文字，如果在 textViewDidChange: 里，这里永远传入 nil。
 */
- (void)textView:(QMUITextView *)textView didPreventTextChangeInRange:(NSRange)range replacementText:(NSString *)replacementText;

@end

Swift

protocol QMUITextViewDelegate : UITextViewDelegate