UIDocumentBrowserViewController.

#if USE_UIKIT_PUBLIC_HEADERS || !__has_include(<DocumentManager/UIDocumentBrowserViewController.h>)
//
//  UIDocumentBrowserViewController.h
//  UIKit
//
//  Copyright © 2017 Apple Inc. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <UIKit/UIViewController.h>
#import <UIKit/UIViewControllerTransitioning.h>

NS_ASSUME_NONNULL_BEGIN



@protocol UIDocumentBrowserViewControllerDelegate;
@class UIImage, UIColor, UIActivity, UIActivityViewController, UIDocumentBrowserAction, UIDocumentBrowserTransitionController;

/// 文档浏览器发生错误的类型
extern NSString * const UIDocumentBrowserErrorDomain API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos,watchos,tvos) ;

/* 文档错误类型 <枚举> */
typedef NS_ERROR_ENUM(UIDocumentBrowserErrorDomain, UIDocumentBrowserErrorCode) {
    UIDocumentBrowserErrorGeneric                                      = 1,     /// 通用错误
    UIDocumentBrowserErrorNoLocationAvailable API_AVAILABLE(ios(12.0))  = 2,    /// 没有地址错误
} API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos,watchos,tvos) ;

/* 文档导入模式 <枚举> */
typedef NS_ENUM(NSUInteger, UIDocumentBrowserImportMode) {
    UIDocumentBrowserImportModeNone,    /// 无法导入
    UIDocumentBrowserImportModeCopy,    /// 复制导入
    UIDocumentBrowserImportModeMove,    /// 移动导入
} API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos,watchos,tvos)  NS_SWIFT_NAME(UIDocumentBrowserViewController.ImportMode);

/* 文档浏览器UI风格 <枚举> */
typedef NS_ENUM(NSUInteger, UIDocumentBrowserUserInterfaceStyle) {
    UIDocumentBrowserUserInterfaceStyleWhite = 0,   /// 白色风格
    UIDocumentBrowserUserInterfaceStyleLight,       /// 浅色风格
    UIDocumentBrowserUserInterfaceStyleDark,        /// 黑暗风格
} API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos,watchos,tvos)  NS_SWIFT_NAME(UIDocumentBrowserViewController.BrowserUserInterfaceStyle);





#pragma mark - 文档操作控制器 Class
#pragma mark -
/*
 概述
 - 用于浏览用户本地或iCloud中的文件,并直接在程序中打开它
 */
API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos,watchos,tvos) 
@interface UIDocumentBrowserViewController : UIViewController <NSCoding>

#pragma mark |实例化|
/**
 实例化

 @param allowedContentTypes 指定能够打开的文件类型(传nil会使用plist中的CFBundleDocumentTypes键指定的类型)
 @return UIDocumentBrowserViewController
 */
- (instancetype)initForOpeningFilesWithContentTypes:(nullable NSArray <NSString *> *)allowedContentTypes NS_DESIGNATED_INITIALIZER;
// 此方法不可用
- (instancetype)initWithNibName:(nullable NSString *)nibName bundle:(nullable NSBundle *)bundle NS_UNAVAILABLE;

/// 代理
@property (nullable, nonatomic, weak) id <UIDocumentBrowserViewControllerDelegate> delegate;

#pragma mark |行为属性|
/// 是否可以创建新文档(默认:YES)
@property (assign, nonatomic) BOOL allowsDocumentCreation;
/// 是否可以同时打开多个文档(默认:NO)
@property (assign, nonatomic) BOOL allowsPickingMultipleItems;
/// 支持打开的文档类型
@property (readonly, copy, nonatomic) NSArray<NSString *> *allowedContentTypes;

#pragma mark |导航栏按钮|
/// 文档导航栏左侧按钮
@property (strong, nonatomic) NSArray <UIBarButtonItem *> *additionalLeadingNavigationBarButtonItems;
/// 文档导航栏右侧按钮
@property (strong, nonatomic) NSArray <UIBarButtonItem *> *additionalTrailingNavigationBarButtonItems;

#pragma mark |展示|
/**
 在URL处展示文档

 @param url URL
 @param importIfNeeded 是否需要导入(如果需要,文档浏览器在调用完成处理程序之前调用代理方法- documentBrowser:didImportDocumentAtURL:toDestinationURL:如果发生错误调用- documentBrowser:failedToImportDocumentAtURL:error: 方法)
 @param completion 显示后的回调
 */
- (void)revealDocumentAtURL:(NSURL *)url importIfNeeded:(BOOL)importIfNeeded completion:(nullable void(^)(NSURL * _Nullable revealedDocumentURL,  NSError * _Nullable error))completion;

#pragma mark |导入|
/**
 将一个文档导入到另一个文档旁边

 @param documentURL 文档初始位置的URL
 @param neighbourURL 要导入到位置的URL
 @param importMode 文档导入模式
 @param completion 导入后的回调
 */
- (void)importDocumentAtURL:(NSURL *)documentURL nextToDocumentAtURL:(NSURL *)neighbourURL mode:(UIDocumentBrowserImportMode)importMode completionHandler:(void (^)(NSURL * _Nullable, NSError * _Nullable))completion;


#pragma mark |文档过度控制器|
// 创建文档过度控制器(在文档加载的过程中给用户以提示;如转菊花,进度条等;与UIViewControllerTransitioningDelegate协议一起使用)
- (UIDocumentBrowserTransitionController *)transitionControllerForDocumentAtURL:(NSURL *)documentURL API_AVAILABLE(ios(12.0)) NS_SWIFT_NAME(transitionController(forDocumentAt:));
// 已废弃(请使用上边的方法)
- (UIDocumentBrowserTransitionController *)transitionControllerForDocumentURL:(NSURL *)documentURL API_DEPRECATED_WITH_REPLACEMENT("transitionControllerForDocumentAtURL:", ios(11.0,12.0));

#pragma mark |自定义操作|
/// 自定义操作(在编辑菜单或导航栏中添加自定义操作)
@property (strong, nonatomic) NSArray <UIDocumentBrowserAction *> *customActions;

#pragma mark |UI|
/// 文档浏览器UI样式(默认:UIDocumentBrowserUserInterfaceStyleWhite)
@property (assign, nonatomic) UIDocumentBrowserUserInterfaceStyle browserUserInterfaceStyle;

@end





///!!!: 代理 <协议>
API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos,watchos,tvos) 
@protocol UIDocumentBrowserViewControllerDelegate <NSObject>

@optional
// 已废弃(请使用下边的方法)
- (void)documentBrowser:(UIDocumentBrowserViewController *)controller didPickDocumentURLs:(NSArray <NSURL *> *)documentURLs API_DEPRECATED_WITH_REPLACEMENT("documentBrowser:didPickDocumentsAtURLs:", ios(11.0, 12.0));
// 已经选择一个或多个文档的回调(实现此方法以处理用户选择的文档)
- (void)documentBrowser:(UIDocumentBrowserViewController *)controller didPickDocumentsAtURLs:(NSArray <NSURL *> *)documentURLs API_AVAILABLE(ios(12.0));

#pragma mark |新建文档|
// 新建文档
- (void)documentBrowser:(UIDocumentBrowserViewController *)controller didRequestDocumentCreationWithHandler:(void(^)(NSURL *_Nullable urlToImport, UIDocumentBrowserImportMode importMode))importHandler;
// 导入文档成功
- (void)documentBrowser:(UIDocumentBrowserViewController *)controller didImportDocumentAtURL:(NSURL *)sourceURL toDestinationURL:(NSURL *)destinationURL;
// 导入文档失败
- (void)documentBrowser:(UIDocumentBrowserViewController *)controller failedToImportDocumentAtURL:(NSURL *)documentURL error:(NSError * _Nullable)error;

#pragma mark |分享|
// 添加自定义UIActivity分享
- (NSArray<__kindof UIActivity *> *)documentBrowser:(UIDocumentBrowserViewController *)controller applicationActivitiesForDocumentURLs:(NSArray <NSURL *> *)documentURLs;
// UIActivity控制器将要显示
- (void)documentBrowser:(UIDocumentBrowserViewController *)controller willPresentActivityViewController:(UIActivityViewController *)activityViewController;

@end





#pragma mark - 文档浏览器转场控制器 Class
#pragma mark -
API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos,watchos,tvos) 
@interface UIDocumentBrowserTransitionController : NSObject <UIViewControllerAnimatedTransitioning>

#pragma mark |实例化|
- (instancetype)init NS_UNAVAILABLE;

/// 加载进度(文档打开时,在文档缩略图上显示加载进度)
@property (strong, nonatomic, nullable) NSProgress *loadingProgress;
/// 打开/关闭文档控制器时的过度视图(是将要显示视图的子视图)
@property (weak, nullable, nonatomic) UIView *targetView;

@end





NS_ASSUME_NONNULL_END

#else
#import <DocumentManager/UIDocumentBrowserViewController.h>
#endif