NSURL 官方文档阅读

NSURL

Overview

NSURL对象表示可能包含远程服务器上的资源位置，磁盘上本地文件的路径或甚至任意编码数据的URL。

我们可以使用URL对象来构造URL并访问其部件。对于表示本地文件的URL，你还可以直接操作这些文件的属性，例如更改文件的最后修改日期。最后，我们可以将URL对象传递给其他API以检索这些URL的内容。例如，你可以使用NSURLSession，NSURLConnection和NSURLDownload类访问远程资源的内容。

URL对象是引用本地文件的首选方式。大多数从文件读取数据或将数据写入文件的对象都有接受NSURL对象而不是路径名作为文件引用的方法。例如，我们可以可以使用initWithContentsOfURL：encoding：error：初始化字符串或使用initWithContentsOfURL：options：error：初始化NSData对象来获取本地的内容。

我们还可以使用URL进行应用间通信。在macOS中，NSWorkspace类提供了openURL：方法来打开URL指定的位置。类似地，在iOS中，UIApplication类提供了openURL：方法。

另外，我们可以在使用粘贴板时使用URL，如NSURL Additions Reference（AppKit框架的一部分）中所述。

NSURL与CF框架里面的对应的类是可以桥接的（"Toll-Free Bridging"）.

Important：Swift覆盖到Foundation框架提供了URL结构，它与NSURL类进行了桥接。 URL值类型提供与NSURL引用类型相同的功能，两者可以与Swift代码交互使用，与Objective-C API交互。此行为类似于Swift将标准字符串，数字和集合类型桥接到其相应的Foundation类。

Structure of a URL

一个NSURL对象由两部分组成：一个潜在的为nil的base URL和一个相对于基本URL解析的字符串。如果NSURL对象的字符串部分在没有base的情况下能完全解析，则认为它是绝对的; 所有其他网址被认为是相对的。
例如，构造NSURL对象时，可以指定file:///path/to/user/作为base URL和folder/file.html作为字符串部分，如下所示：

NSURL *baseURL = [NSURL fileURLWithPath:@"file:///path/to/user/"];
NSURL *URL = [NSURL URLWithString:@"folder/file.html" relativeToURL:baseURL];
NSLog(@"absoluteURL = %@", [URL absoluteURL]);

完全解析后，absolute URL 为： file:///path/to/user/folder/file.html.

URL也可以根据其结构分为几个部分。例如，https://johnny:[email protected]:443/script.ext;param=value?query=value#ref 包含以下URL组件：

Component	Value
scheme	https
user	johnny
password	p4ssw0rd
host	www.example.com
port	443
path	/script.ext
pathExtension	ext
pathComponents	["/", "script.ext"]
parameterString	param=paramvalue
query	query=value
fragment	ref

NSURL类提供了可以检查每个组件的属性（见后文Symbols）。

Bookmarks and Security Scope

从OS X v10.6和iOS 4.0开始，NSURL类提供了创建和使用书签对象的功能。书签提供对系统文件资源的持久引用。定义一个书签时，你将获得资源当前位置的URL。如果用户移动或重命名资源，或者用户重新启动应用程序或重新启动系统，则书签与文件资源（通常为文件或文件夹）的关联通常会还会存在。

有关使用书签的一般介绍，请参阅“文件系统编程指南”中的“使用书签查找文件”。

当我们获取一个security-scoped书签时，你将获得一个security-scoped的URL。

Security-Scoped URLs

security-scoped的URL可以访问应用程序沙箱外的资源。在macOS中，当我们解析security-scoped的书签时，我们可以访问security-scoped的URL。在iOS中，使用UIDocumentPickerViewController打开或移动文档的应用程序也会收到security-scoped的URL。

要访问security-scoped的URL，我们必须调用startAccessingSecurityScopedResource方法（或其Core Foundation里面的CFURLStartAccessingSecurityScopedResource函数）。对于iOS应用程序，如果我们使用UIDocument访问该URL，则系统会自动管理security-scoped的URL。

如果startAccessingSecurityScopedResource（或CFUrLStartAccessingSecurityScopedResource）返回YES，则必须通过调用stopAccessingSecurityScopedResource方法（或其Core Foundation的CFURLStopAccessingSecurityScopedResource函数）来停止访问。一旦我们完成使用该文件，我们应该停止访问。在调用这些方法后，我们立即失去对该资源的访问权限。

警告：如果我们在不再需要文件系统资源时无法停止访问权限，则我们的应用程序会出现泄漏内核资源的问题。当内核资源泄漏到一定量的时候，我们的应用程序将失去将系统文件位置添加到沙箱，使用Powerbox，security-scoped的书签或类似的API的功能，直到重新启动APP。

Security-Scoped URLs and String Paths

在macOS应用程序中，当你复制安全范围的URL时，副本具有原始安全范围。你可以像使用原始URL一样访问文件系统资源（URL指向）：通过调用startAccessingSecurityScopedResource方法（或其Core Foundation等效的函数）。

如果你需要一个security-scoped的URL的path来作为一个字符串的值（由path的getter方法获得），例如需要从URL的path获取到的字符串的API，但是请注意，从security-scoped的URL获取到path并没有security scoped，并且我们不能通过此路径获取到security-scoped的URL对应的资源

iCloud Document Thumbnails

在OS X v10.10和iOS 8.0，NSURL类可以获取和设置文档缩略图作为iCloud文档的资源属性。你可以使用getResourceValue：forKey：error：或getPromisedItemResourceValue：forKey：error：方法在iOS中获取UIImage对象字典的字典或macOS中获取NSImage对象的字典。例子如下：

NSURL *URL = [self URLForDocument];
NSDictionary *thumbnails = nil;
NSError *error = nil;
 
BOOL success = [URL getPromisedItemResourceValue:&thumbnails
                                          forKey:NSURLThumbnailDictionaryKey
                                           error:&error];
if (success) {
  NSImage *image = thumbnails[NSThumbnail1024x1024SizeKey];
} else {
  // handle the error
}

在macOS中，你可以使用setResourceValue：forKey：error：方法设置缩略图字典。你还可以使用NSURLThumbnailKey获取或设置具有多个表示形式的NSImage对象所有缩略图。例子如下：

NSURL *URL = [self URLForDocument];
NSImage *thumbnail = [self createDocumentThumbnail];
NSError *error = nil;
 
BOOL success = [URL setResourceValue:@{NSThumbnail1024x1024SizeKey : thumbnail}
                              forKey:NSURLThumbnailDictionaryKey
                               error:&error];
 
if (!success) {
  // handle the error
}

NOTE: 不要直接设置NSURLThumbnailDictionaryKey键。修改此Key会干扰文档跟踪，并导致文档的重复项以及其他可能的问题。

在iOS中，使用UIDocument子类来管理你的文件。通过覆盖文档的fileAttributesToWriteToURL：forSaveOperation：error：方法并返回包含正确的缩略图键（以及任何其他文件属性）的字典来设置缩略图。

NOTE: 虽然缩略图API旨在支持多种图像分辨率，但目前它只支持1024 x 1024像素的缩略图。

Symbols

Creating an NSURL Object

+ (instancetype)URLWithString:(NSString *)URLString

通过指定的URLString来创建NSURL对象；

用于初始化NSURL对象的URL字符串，必须是符合RFC 2396的字符串。此方法根据RFC 1738和1808分析URLString。如果URL字符串格式不正确或无效，则返回nil。

此方法的URLString只包含正确形成URL中允许的字符。所有其他字符必须正确转义。任何转义的字符都要使用UTF-8编码。

Important：要为文件系统路径创建NSURL对象，请使用fileURLWithPath：isDirectory：代替。

- (instancetype)initWithString:(NSString *)URLString

同上；

+ (instancetype)URLWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL

使用baseURL和URLString创建NSURL对象；

URLString：用于初始化NSURL对象的URL字符串。可能不是nil。必须符合RFC 2396.
baseURL：NSURL对象的base URL；

如果URLString格式错误或为nil，则返回nil。

此方法允许我们创建相对于base路径或URL的URL。例如，如果我们有磁盘上的文件夹的URL和该文件夹中的文件的名称，则可以通过提供文件夹的URL作为基本路径（带有斜杠）和文件名作为字符串部分来构造文件的URL 。
此方法的URLString只包含正确形成URL中允许的字符。所有其他字符必须正确转义。任何转义的字符都要使用UTF-8编码。

- (instancetype)initWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL

同上；

+ (NSURL *)fileURLWithPath:(NSString *)path isDirectory:(BOOL)isDir

初始化并返回一个新创建的NSURL对象作为具有指定路径的文件URL。

path：NSURL对象将表示的路径。路径应该是有效的系统路径，而不能是空的路径。如果路径以波形开头，则必须首先使用stringByExpandingTildeInPath进行扩展。如果路径是相对路径，则将其视为相对于当前工作目录。
isDir：一个布尔值，指定在解析相对路径组件时将路径视为目录路径。如果路径指示目录，则传YES，否则否为NO。

- (instancetype)initFileURLWithPath:(NSString *)path isDirectory:(BOOL)isDir

同上；

+ (NSURL *)fileURLWithPath:(NSString *)path

初始化并返回一个新创建的NSURL对象作为具有指定路径的文件URL。

path：NSURL对象将表示的路径。路径应该是有效的系统路径，而不能是空的路径。如果路径以波形开头，则必须首先使用stringByExpandingTildeInPath进行扩展。如果路径是相对路径，则将其视为相对于当前工作目录。

该方法假设如果以斜线结尾，则路径是目录。如果路径未以斜杠结尾，则该方法会检查文件系统以确定路径是文件还是目录。如果文件系统中存在该路径，并且是目录，则该方法会追加一个尾部斜线。如果文件系统中不存在路径，则该方法假定它表示一个文件，并且不附加尾部斜杠。

请考虑使用fileURLWithPath：isDirectory :方法,它允许你显式指定返回的NSURL对象是否表示文件或目录。

- (instancetype)initFileURLWithPath:(NSString *)path

调用此方法等同于调用initWithScheme：host：path：方法，其中scheme为NSURLFileScheme（一个指向安装卷上的文件的URL），host为空。
其他的同上；

+ (NSURL *)fileURLWithPathComponents:(NSArray *)components

使用具有指定路径组件(即)的文件URL来初始化NSURL对象并返回；

+ (instancetype)URLByResolvingAliasFileAtURL:(NSURL *)url options:(NSURLBookmarkResolutionOptions)options error:(NSError * _Nullable *)error

返回通过url解析别名文件而创建的新URL。

url：指向别名文件的URL。
options：解析书签数据时考虑的选项。此方法不支持NSURLBookmarkResolutionWithSecurityScope选项。
error：尝试解析提供的URL时发生的错误。

使用此方法只需要一步就可以决定使用writeBookmarkData:toURL:options:error:方法决定的书签数据并且完成数据解析；
如果url参数不引用由NSURLIsAliasFileKey属性定义的别名文件，则此方法返回url参数。
如果url参数不可用，则此方法返回nil，并填充可选的错误参数。

NOTE：在Swift中，此方法返回非选择结果，并用throws关键字标记，以指示在失败的情况下会引发错误。

你可以在try表达式中调用此方法，并处理do语句的catch子句中的任何错误，

+ (instancetype)URLByResolvingBookmarkData:(NSData *)bookmarkData options:(NSURLBookmarkResolutionOptions)options relativeToURL:(NSURL *)relativeURL bookmarkDataIsStale:(BOOL *)isStale error:(NSError * _Nullable *)error

返回通过解析书签数据而创建的新URL。

bookmarkData: URL传递过来的书签数据；
options:解析书签数据时考虑的选项。要解析security-scoped的书签以支持App Sandbox，你必须包含（通过按位与运算符与此参数中的任何其他选项）NSURLBookmarkResolutionWithSecurityScope选项。
relativeURL:书签数据的base URL。
isStale: 如果为YES，则书签数据过期。你的应用应使用返回的URL创建新的书签，并使用它来代替现有书签的任何存储副本。
error:在无法创建URL的情况下发生的错误。

对于relativeURL，如果你正在解析安全范围的书签以获取安全范围的URL，请使用以下参数：
```
  a. 要解决应用范围的书签，请使用nil值。
  b. 要解析文档范围的书签，请使用你从中检索书签的文档的绝对路径（尽管有此参数的名称）。
```
App Sandbox不会限制哪些URL值可以传递给此参数。

如果原始文件或目录无法找到或无法挂载的卷，则此方法将失败。如果此方法失败，你可以使用resourceValuesForKeys：fromBookmarkData：方法来获取有关书签的信息，例如最后一个已知路径（NSURLPathKey），以帮助用户决定如何继续下一步。

要从安全范围的书签获取安全范围的URL，请使用NSURLBookmarkResolutionWithSecurityScope选项调用此方法。另外，要使用安全范围，你必须首先为你的应用启用适当的权利，如启用安全性范围的书签和URL访问中所述。

为了获得访问由安全范围的URL指向的文件系统资源（换句话说，将资源引入到应用程序的沙盒中），请在返回的URL上调用startAccessingSecurityScopedResource方法（或其Core Foundation等效的CFURLStartAccessingSecurityScopedResource函数）。

- (instancetype)initByResolvingBookmarkData:(NSData *)bookmarkData options:(NSURLBookmarkResolutionOptions)options relativeToURL:(NSURL *)relativeURL bookmarkDataIsStale:(BOOL *)isStale error:(NSError * _Nullable *)error

同上；

+ (NSURL *)fileURLWithFileSystemRepresentation:(const char *)path isDirectory:(BOOL)isDir relativeToURL:(NSURL *)baseURL

返回使用C字符串初始化的新的URL对象，表示本地文件系统路径。

path：文件系统表示中以空值终止的C字符串，其中包含表示为URL的路径。如果此路径是相对路径，则将其视为相对于当前工作目录。
isDir：YES表示为目录，NO表示不是目录；
baseURL：新的URL对象的base URL。这必须是一个文件URL。如果路径是绝对的，则忽略此URL。

- (instancetype)initFileURLWithFileSystemRepresentation:(const char *)path isDirectory:(BOOL)isDir relativeToURL:(NSURL *)baseURL

同上；

- (BOOL)getFileSystemRepresentation:(char *)buffer maxLength:(NSUInteger)maxBufferLength

使用由本地文件系统路径的C字符串填充提供的缓冲区。

buffer：一个足够支持路径的缓冲区，在文件系统表示中包含一个以null结尾的C字符串。
maxBufferLength：缓冲区的最大字节数（一般为MAXPATHLEN或PATH_MAX）

如果URL可以转换为文件系统表示形式返回YES，否则为NO。
文件系统表示格式在文件编码和字体中描述。

Identifying and Comparing Objects

- (BOOL)isEqual:(id)anObject

返回一个布尔值，指示接收方和给定对象是否具有相同的URL字符串和base URL。

anObject：要与调用者进行比较的对象。

该方法定义了实例相等的含义。当且仅当它们为baseURL和relativeString返回相同的值时，两个NSURL被认为是相等的。

Querying an NSURL

- (BOOL)checkResourceIsReachableAndReturnError:(NSError * _Nullable *)error

返回文件URL指向的资源是否可以查询到。

error：获取指定资源发送错误的原因；

此方法可同步检查提供的URL中的文件是否可访问。当做出不需要对资源进行其他即时操作时，例如定期维护特定文档的存在状态，适当的可达性检查。例如，如果用户删除文件，你可能会从下载列表中删除某个项目。

如果你的应用程序必须对文件执行操作，例如打开或复制资源属性，则调用此方法去实现这些操作并且处理错误情况会更叫高效。
如果此方法返回NO，错误引用的对象指针将附加其他信息。

- (BOOL)isFileReferenceURL

返回URL是否是文件引用的URL。

@property(readonly, getter=isFileURL) BOOL fileURL`

一个布尔值，用于确定接收方是否是文件URL。

如果接收方使用文件格式，属性值为YES，否则为NO。文件路径和文件引用URL都被认为是文件URL。
如果此属性的值为YES，则接收者的路径属性包含适用于输入NSFileManager或NSPathUtilities。

Accessing the Parts of the URL

@property(readonly, copy) NSString *absoluteString

接收者的URL字符串。（只读）
该属性的值通过根据RFC 1808中给出的算法解析接收者的字符串与其基数来计算。

@property(readonly, copy) NSURL *absoluteURL

指向与接收者相同资源的绝对URL。（只读）

@property(readonly, copy) NSURL *baseURL

即 relative URL;如果不是通过有relativeToURL的方法生成的，此值为nil;
一般由scheme包含到port部分；

@property(readonly) const char *fileSystemRepresentation

包含URL文件系统路径的C字符串。（只读）
这将在文件系统表示中返回一个以null结尾的C字符串。

@property(readonly, copy) NSString *scheme

例如，在 http://www.example.com/index.html的网址中，scheme是http。

一个完整的URL由scheme + ":" + resourceSpecifier（后面有介绍）组成

@property(readonly, copy) NSString *host

如果未转义，使用stringByReplacingPercentEscapesUsingEncoding：方法转义。如果调用者不符合RFC 1808，则该属性为nil。例如，在http://www.example.com/index.html的网址中，host是www.example.com。

@property(readonly, copy) NSNumber *port

例如，在URL http://www.example.com:8080/index.php中，端口号是8080。

@property(readonly, copy) NSString *lastPathComponent

如果未转义，使用stringByReplacingPercentEscapesUsingEncoding：方法转义。例如，在URL file:///path/to/file中，最后一个路径组件是file。

@property(readonly, copy) NSArray *pathComponents

例如，在URL file:///directory/directory%202/file中，路径组件数组将为@[@"/", @"directory", @"directory 2", @"file"].。

@property(readonly, copy) NSString *parameterString

例如，在URL file:///path/to/file;foo中，parameterString为foo。
该属性不应与query属性混淆，该属性通常还包含一个参数串。
；后面的是parameterString，？后面的是query

@property(readonly, copy) NSString *query

例如，在URL http://www.example.com/index.php?key1=value1&key2=value2中，查询字符串为key1 = value1＆key2 = value2。

@property(readonly, copy) NSString *user

例如，在URL ftp://[email protected]/中，user是username。

@property(readonly, copy) NSString *password

例如，在URL http://username:[email protected]/index.html,中，密码是密码。

@property(readonly, copy) NSString *path

如果调用者为文件或文件引用URL（由fileURL确定），则此属性的值适用于NSFileManager或NSPathUtilities的方法的参数。如果该路径具有尾部斜线，则会被去掉。
如果接收方包含文件引用URL，则此属性的值提供了引用资源的当前路径，如果资源不再存在，则该参数可能为nil。

如果parameterString属性不为nil，则路径可能不完整。如果调用者包含未编码的分号，则路径以分号前的字符结束。该URL的其余部分在parameterString属性中提供。
如果parameterString非空，要获取完整路径，请附加一个分号，后跟参数字符串。

根据RFC 3986，主机名和端口部分之后的斜线被视为路径的一部分。例如，在http://www.example.com/index.html的网址中，路径为/index.html。

@property(readonly, copy) NSString *relativePath

端port后面，parameterString前面的部分；如果路径具有尾部斜杠，则将其剥离；

@property(readonly, copy) NSString *pathExtension

例如，在URL file:///path/to/file.txt中，路径扩展名为txt。

@property(readonly, copy) NSString *relativeString

如果调用者是绝对URL，则此方法返回与absoluteString相同的值。就是除了baseURL以外的其他部分；

@property(readonly, copy) NSString *resourceSpecifier

此属性指资源说明符。例如，在 http://www.example.com/index.html?key1=value1#jumplink 的网址中，资源说明符是 //www.example.com/index.html?key1=value1#jumplink（即冒号之后的所有内容）。

NOTE：如果调用者不是网络资源的URL，比如是由桥接的CFURL的CFURLCopyNetLocation函数得来的，那么此方法返回的只会是原来应该返回的一部分，比如在URL file:///file.txt 中，返回的就是/file.txt并没有前面两个//;

@property(readonly, copy) NSString *fragment

符合RFC 1808的碎片标识符（只读）
例如，在URL http://www.example.com/index.html#jumpLocation中，片段标识符是jumpLocation。

@property(readonly, copy) NSURL *standardizedURL

将URL中的"."或者是".."移除的一个副本；
该属性为一个新的NSURL对象，使用调用者的的路径进行初始化，其中包含任何“..”或“.”的地方都将除去。如果调用者不符合RFC 1808，则该属性为nil。

由于 NSURL 里面有太多方法，而且大多数我看了下，大部分的场景是用不到的，比如书签相关的，所以到此就不再翻译 NSURL 相关的，有兴趣的同学可以自己看下官方文档，或者是留言和我讨论。