macOS开发-NSOpenPanel

一. 前言

打开面板，提示用户选择要打开的文件。

@interface NSOpenPanel : NSSavePanel

Overview

Apps use the Open panel as a convenient way to query the user for the name of a file to open. In macOS 10.15 and later, the system always draws Open panels in a separate process, regardless of whether the app is sandboxed. When the user chooses a file to open, macOS adds that file to the app’s sandbox. Prior to macOS 10.15, the system drew the panels in a separate process only for sandboxed apps.

应用程序使用“打开”面板作为方便的方法来查询用户要打开的文件的名称。在macOS 10.15及更高版本中，系统始终在单独的过程中绘制“打开”面板，而不管该应用程序是否被沙箱化。当用户选择要打开的文件时，macOS将该文件添加到应用的沙箱中。在macOS 10.15之前，系统仅在沙盒应用程序的单独过程中绘制面板。

二. 官方属性方法

1. 创建打开面板

+ (NSOpenPanel *)openPanel; // 创建NSOpenPanel实例对象，但是这个类不是单例。

2. 配置打开面板

// 是否解析别名
@property BOOL resolvesAliases;
// 是否可以选择目录
@property BOOL canChooseDirectories;
// 是否可以选择多个文件或目录
@property BOOL allowsMultipleSelection;
// 是否选择文件
@property BOOL canChooseFiles;
// 附件视图是否可见
@property (getter=isAccessoryViewDisclosed) BOOL accessoryViewDisclosed API_AVAILABLE(macos(10.11)); 

3. iCloud

// 指示面板如何响应具有冲突版本的iCloud文档
@property BOOL canResolveUbiquitousConflicts API_AVAILABLE(macos(10.10));
// 指示面板如何响应未完全本地下载的iCloud文档
@property BOOL canDownloadUbiquitousContents API_AVAILABLE(macos(10.10));

4. 访问用户选择

// URL数组，每个URL包含所选文件或目录的完整指定位置。
@property (readonly, copy) NSArray<NSURL *> *URLs;

三. 父类NSSavePanel保存面板

1. 创建保存面板

+ (NSSavePanel *)savePanel; // 创建NSSavePanel实例对象，但是这个类不是单例。

2. 响应交互

@property (nullable, weak) id<NSOpenSavePanelDelegate> delegate;

// 是否应在“打开”面板中启用指定的URL
- (BOOL)panel:(id)sender shouldEnableURL:(NSURL *)url API_AVAILABLE(macos(10.6));
// 用于保存和打开文件的URL验证。
//    NSSavePanel：当用户选择“保存”按钮时，保存面板会调用该方法一次。用户打算将文件保存在“ url”处。如果'url'是要保存的有效位置，则返回YES。请注意，除非用户决定覆盖现有项目，否则“ url”中的项目可能实际上还不存在。返回“否”，并在“ outError”中填写用户可显示的错误消息，以说明“ URL”无效的原因。如果错误提供了恢复选项，并且恢复成功，则面板将尝试再次关闭。
//    NSOpenPanel：当用户选择“打开”按钮时，将为每个选定的文件名（或目录）调用一次该方法。如果可以打开“ URL”，则返回YES。返回NO并在用户显示的消息中填写“ outError”，以说明为什么“ url”对于打开无效。如果对选定项目的处理需要很长时间，则可以在panel：shouldEnableURL：上使用此方法。如果错误提供了恢复选项，并且恢复成功，则面板将尝试再次关闭。
- (BOOL)panel:(id)sender validateURL:(NSURL *)url error:(NSError **)outError API_AVAILABLE(macos(10.6));
// 用户将所选目录更改为位于指定URL的目录。
- (void)panel:(id)sender didChangeToDirectoryURL:(nullable NSURL *)url API_AVAILABLE(macos(10.6));
// 通过在“保存”面板中单击“保存”，告知代表用户用户已确认文件名选择。
- (nullable NSString *)panel:(id)sender userEnteredFilename:(NSString *)filename confirmed:(BOOL)okFlag;
// “保存”面板即将展开或折叠，因为用户单击了显示或隐藏文件浏览器的显示三角形。
- (void)panel:(id)sender willExpand:(BOOL)expanding;
// 用户在指定的“保存”面板中更改了选择。
- (void)panelSelectionDidChange:(nullable id)sender;

3. 显示面板

// 将面板显示为指定窗口的模态面板
- (void)beginSheetModalForWindow:(NSWindow *)window completionHandler:(void (^)(NSModalResponse result))handler API_AVAILABLE(macos(10.6));
// 将面板显示为无模式窗口。
- (void)beginWithCompletionHandler:(void (^)(NSModalResponse result))handler API_AVAILABLE(macos(10.6));
// 显示面板并以当前工作（或上次选择的）目录作为默认起点开始其事件循环。
- (NSModalResponse)runModal;
// 验证并重新加载面板中可见的浏览器列。

4. 获取所选URL

// 完整指定位置
@property (nullable, readonly, copy) NSURL *URL;

5. 配置外观

// 面板标题
@property (null_resettable, copy) NSString *title;
// 默认按钮中的文本
@property (null_resettable, copy) NSString *prompt;
// 消息文本
@property (null_resettable, copy) NSString *message;
// 标签文本显示在文件名文本字段的前面。
@property (null_resettable, copy) NSString *nameFieldLabel;
// 当前显示在名称字段中的用户可编辑文件名。
@property (copy) NSString *nameFieldStringValue API_AVAILABLE(macos(10.6));
// 面板显示的当前目录
@property (nullable, copy) NSURL *directoryURL API_AVAILABLE(macos(10.6));
// 自定义附件视图
@property (nullable, strong) NSView *accessoryView;
// 是否显示标签字段
@property BOOL showsTagField API_AVAILABLE(macos(10.9));
// 标签名称
@property (nullable, copy) NSArray<NSString *> *tagNames API_AVAILABLE(macos(10.9));

6. 面板行为

// 是否显示创建目录的UI
@property BOOL canCreateDirectories;
// 是否显示文件拓展名的UI
@property BOOL canSelectHiddenExtension;
// 是否显示隐藏文件
@property BOOL showsHiddenFiles;
// 是否隐藏指示和拓展复选框
@property (getter=isExtensionHidden) BOOL extensionHidden;
// 是否拓展面板
@property (getter=isExpanded, readonly) BOOL expanded;
// 是否允许用户保存文件名扩展名不在允许的类型列表中的文件。
@property BOOL allowsOtherFileTypes;
// 是否将文件包显示为目录。
@property BOOL treatsFilePackagesAsDirectories;

7. Action

- (IBAction)ok:(nullable id)sender; // 点击确定
- (IBAction)cancel:(nullable id)sender; // 点击取消

四. 简单示例

- (IBAction)openPanelClick:(NSButton *)sender {
    NSOpenPanel *openPanel = [NSOpenPanel openPanel];
    openPanel.prompt = @"选择";
    openPanel.title = @"NSSplitView Demo";
    openPanel.message = @"你是谁的谁";
    openPanel.canChooseFiles = YES;
    openPanel.canChooseDirectories = YES;
    [openPanel beginSheetModalForWindow:self.view.window completionHandler:^(NSModalResponse result) {
        if (result == NSModalResponseOK) {
            NSLog(@"%@", openPanel.URL.path);
        }
        sender.state = NSControlStateValueOff;
    }];
}