FileProvider框架详细解析 (二) —— 实现File Provider extension(一)

版本记录

版本号 时间
V1.0 2019.05.16 星期四

前言

今天翻阅苹果的API文档,发现多了一个框架就是FileProvider,看了下才看见是iOS11.0新添加的框架,这里我们就一起来看一下框架FileProvider。感兴趣的看下面几篇文章。
1. FileProvider框架详细解析 (一) —— 基本概览(一)

开始

首先看下写作环境

Swift 5, iOS 12, Xcode 10

在本教程中,您将了解File Provider框架以及如何实现自己的File Provider extension以公开应用程序自己的内容。

iOS 11中首次引入了File Provider extension,可通过iOS Files应用程序访问您的应用程序管理的内容。 此外,其他应用程序可以使用UIDocumentBrowserViewController或UIDocumentPickerViewController类来访问您的应用程序的数据。

File Provider extension的主要任务是:

  • 创建表示远程内容的文件占位符。
  • 拦截从主机应用程序读取,以便文档可以下载或更新。
  • 在更新文档后发出通知,以便更改可以上载到远程服务器。
  • 枚举存储的文档和目录。
  • 对文档执行操作,例如重命名,移动或删除。

您将使用Heroku Button配置托管文件的服务器。 服务器设置完成后,您将配置扩展以枚举服务器的内容。

打开Favart-Starter文件夹并在Xcode中打开Favart.xcodeproj。 确保您已选择Favart scheme,然后构建并运行该应用程序,您将看到以下内容:

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第1张图片

该应用程序提供了一个基本视图,用于教育用户如何启用File Provider extension,因为您实际上不会在应用程序本身内执行任何操作。每次在本教程中构建和运行应用程序时,您都将返回主屏幕并打开Files应用程序以访问您的扩展程序。

注意:如果要在实际设备上运行示例项目,除了为两个目标设置开发团队之外,还必须在Configuration文件夹中编辑Favart.xcconfig。将bundle identifier更新为唯一值。

示例项目将此值用于两个目标中的PRODUCT_BUNDLE_IDENTIFIER构建设置,以及Provider.entitlements中的App Group标识符和Info.plist中的关联NSExtensionFileProviderDocumentGroup值。如果不在项目中一致地更新值,则可能会看到模糊且难以调试的错误。使用自定义构建设置是保持平稳运行的好方法。

示例项目包括您将用于File Provider extension的基本组件:

  • NetworkClient.swift包含用于与Heroku服务器通信的网络客户端。
  • FileProviderExtension.swift本身具有File Provider extension
  • FileProviderEnumerator.swift包含枚举器,用于列出目录的内容。
  • Models是一个包含完成扩展所需模型的组。

Setting Up the Back End With Heroku

首先,您需要自己的后端服务器实例。 幸运的是,使用Heroku Button很容易。 单击下面的按钮以访问Heroku dashboard

在您注册免费帐户或登录Heroku后,您将最终进入类似以下内容的页面。

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第2张图片

在此页面上,您可以选择为应用程序命名。 您可以选择一个名称,如果您将该字段留空,Heroku将为您生成一个名称。 由于无需担心其他配置,请单击Deploy app按钮,片刻之后,您的后端将启动并运行。

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第3张图片

Heroku完成部署应用程序后,单击底部的View按钮。这将带您到承载后端实例的URL。在应用程序的根目录下,您应该看到一条JSON消息,是Hello world!

最后,您需要复制Heroku实例的URL。您只需要域部分,它应如下所示:{app-name} .herokuapp.com

starter项目中,打开Provider / NetworkClient.swift。在文件的顶部,您应该看到一条警告:Add your Heroku URL here。删除警告并使用您的URL替换components.host占位符字符串。

这样就完成了服务器配置。接下来,您将定义File Provider所依赖的模型。


Defining an NSFileProviderItem

首先,File Provider需要一个符合NSFileProviderItem的模型。此模型将提供有关文件提供程序管理的文件的信息。初始化项目包含FileProviderItem.swift中的FileProviderItem,您将使用它,但在符合协议之前需要做一些工作。

虽然该协议有27个属性,但只需要4个。可选属性为File Provider框架提供有关每个文件的更多详细信息,并启用其他功能。在本教程中,您将专注于所需的属性:itemIdentifierparentItemIdentifierfilenametypeIdentifier

itemIdentifier为模型提供唯一可识别的密钥。File Provider使用parentIdentifier来跟踪其在扩展的层次结构中的位置。

filenameFiles/em> app<. finally>typeIdentifier是项目的uniform type identifierUTI中展示的item名称。

FileProviderItem符合NSFileProviderItem之前,它需要一种方法来处理来自后端的数据。 MediaItem定义了一个从后端返回的简单模型。 MediaItemReference不是直接在FileProviderItem中使用这个模型,而是处理扩展的一些额外逻辑以弥补差距。

您将在本教程中使用MediaItemReference有两个原因:

  • 1) Heroku上的后端非常简单。它无法提供NSFileProviderItem所需的所有信息,因此您需要在其他地方获取它。
  • 2) File Provider extension也很简单。更完整的File Provider extension需要使用诸如Core Data之类的东西在本地持久保存后端返回的信息,以便在扩展的生命周期中稍后引用它。

为了将教程的重点放在文件File Provider extension本身上,您将使用MediaItemReference通过将四个必需属性的数据嵌入到URL对象中来作弊。然后,您将对该URL进行base64编码,并将其编码为NSFileProviderItemIdentifier。您不需要自己保留任何内容,因为NSFileProviderExtension会为您处理它。

要开始构建模型,请打开Provider / MediaItemReference.swift并在MediaItemReference中添加以下内容:

// 1
private let urlRepresentation: URL

// 2
private var isRoot: Bool {
  return urlRepresentation.path == "/"
}

// 3
private init(urlRepresentation: URL) {
  self.urlRepresentation = urlRepresentation
}

// 4
init(path: String, filename: String) {
  let isDirectory = filename.components(separatedBy: ".").count == 1
  let pathComponents = path.components(separatedBy: "/").filter {
    !$0.isEmpty
  } + [filename]
  
  var absolutePath = "/" + pathComponents.joined(separator: "/")
  if isDirectory {
    absolutePath.append("/")
  }
  absolutePath = absolutePath.addingPercentEncoding(
    withAllowedCharacters: .urlPathAllowed
  ) ?? absolutePath
  
  self.init(urlRepresentation: URL(string: "itemReference://\(absolutePath)")!)
}

这是你做的:

  • 1) 对于本教程,URL将表示NSFileProviderItem所需的大部分信息。
  • 2) 此计算属性确定当前项是否是文件系统的根。
  • 3) 您将此初始化程序设为私有以防止从模型外部使用。
  • 4) 从后端读取数据时,您将使用此初始化程序。 您假设如果文件名不包含句点,则它必须是目录,因为初始化程序无法推断其类型。

在添加最终初始化程序之前,请使用以下内容替换文件顶部的import语句:

import FileProvider

接下来,在前面的代码下面添加以下初始化器:

init?(itemIdentifier: NSFileProviderItemIdentifier) {
  guard itemIdentifier != .rootContainer else {
    self.init(urlRepresentation: URL(string: "itemReference:///")!)
    return
  }
  
  guard 
    let data = Data(base64Encoded: itemIdentifier.rawValue),
    let url = URL(dataRepresentation: data, relativeTo: nil) 
    else {
      return nil
  }
  
  self.init(urlRepresentation: url)
}

大部分扩展都将使用此初始化程序。 记下schemeitemReference://。 您可以单独处理根容器标识符,以确保正确设置其URL路径。

对于其他项,通过将标识符的原始值转换为base64编码的数据来检索URL表示。 URL中的信息来自首先枚举实例的网络请求。

现在初始化器已经不在了,是时候为这个模型添加一些属性了。 首先,在文件顶部添加以下导入:

import MobileCoreServices

这提供了对文件类型的访问。 接下来,在结构体的末尾添加以下内容:

// 1
var itemIdentifier: NSFileProviderItemIdentifier {
  if isRoot {
    return .rootContainer
  } else {
    return NSFileProviderItemIdentifier(
      rawValue: urlRepresentation.dataRepresentation.base64EncodedString()
    )
  }
}

var isDirectory: Bool {
  return urlRepresentation.hasDirectoryPath
}

var path: String {
  return urlRepresentation.path
}

var containingDirectory: String {
  return urlRepresentation.deletingLastPathComponent().path
}

var filename: String {
  return urlRepresentation.lastPathComponent
}

// 2
var typeIdentifier: String {
  guard !isDirectory else {
    return kUTTypeFolder as String
  }
  
  let pathExtension = urlRepresentation.pathExtension
  let unmanaged = UTTypeCreatePreferredIdentifierForTag(
    kUTTagClassFilenameExtension,
    pathExtension as CFString,
    nil
  )
  let retained = unmanaged?.takeRetainedValue()
  
  return (retained as String?) ?? ""
}

// 3
var parentReference: MediaItemReference? {
  guard !isRoot else {
    return nil
  }
  return MediaItemReference(
    urlRepresentation: urlRepresentation.deletingLastPathComponent()
  )
}

记住:

  • 1) itemIdentifier对于FileProvider管理的每个项目必须是唯一的。 如果项引用是根,则它使用NSFileProviderItemIdentifier.rootContainer。 如果没有,它会从引用的URL创建一个标识符。
  • 2) 这里它根据URL的路径扩展创建一个标识符。 奇怪的UTTypeCreatePreferredIdentifierForTag是一个C函数,它返回给定输入的UTI类型。
  • 3) 在目录结构中工作时,引用父级是很有用的。 这表示包含当前引用的文件夹。 它是可选的,因为根引用没有父引用。

您在此处添加了一些其他属性,这些属性不需要太多解释,但在创建NSFileProviderItem时非常有用。 这样,参考模型就完成了。 是时候在FileProviderItemhook所有内容。

打开FileProviderItem.swift并在文件顶部添加以下内容:

import FileProvider

然后,在类实现之外将以下内容添加到文件的底部:

// MARK: - NSFileProviderItem

extension FileProviderItem: NSFileProviderItem {
  // 1
  var itemIdentifier: NSFileProviderItemIdentifier {
    return reference.itemIdentifier
  }
  
  var parentItemIdentifier: NSFileProviderItemIdentifier {
    return reference.parentReference?.itemIdentifier ?? itemIdentifier
  }
  
  var filename: String {
    return reference.filename
  }
  
  var typeIdentifier: String {
    return reference.typeIdentifier
  }
  
  // 2
  var capabilities: NSFileProviderItemCapabilities {
    if reference.isDirectory {
      return [.allowsReading, .allowsContentEnumerating]
    } else {
      return [.allowsReading]
    }
  }
  
  // 3
  var documentSize: NSNumber? {
    return nil
  }
}

FileProviderItem现在符合NSFileProviderItem并实现所有必需的属性。 仔细阅读代码:

  • 1) 大多数必需属性只是映射您之前添加到MediaItemReference的逻辑。
  • 2) NSFileProviderItemCapabilities指示可以对文档浏览器中的项目执行哪些操作 - 例如读取和删除。 对于这个应用程序,您只需要允许读取和枚举目录。 在实际用例中,您可能会使用.allowsAll功能,因为用户希望所有操作都能正常工作。
  • 3) 本教程不会使用文档大小,但它包含在内以防止NSFileProviderManager.writePlaceholder(at:withMetadata :)中的崩溃。 这可能是框架的一个bug,幸运的是,一个典型的应用程序的File Extension无论如何都会提供documentSize

这就是模型。 NSFileProviderItem具有更多属性,但是您已实现的内容足以满足本教程的需要。


Enumerating Documents

现在该模型已经到位,是时候将它投入使用了。 要向用户显示模型定义的项目,您需要告知系统应用程序的内容。

NSFileProviderEnumerator定义系统与应用程序内容之间的关系。 稍后,您将通过提供表示当前上下文的NSFileProviderItemIdentifier来查看系统如何请求枚举器。 如果用户正在查看扩展的根目录,系统将提供.rootContainer标识符。 当用户在目录内导航时,系统会传入模型定义的该项的标识符。

首先,您将构建启动项目中提供的枚举器。 打开Provider / FileProviderEnumerator.swift并在path下添加以下内容:

private var currentTask: URLSessionTask?

此属性将存储对当前网络任务的引用。 这提供了取消请求的能力。

接下来,使用以下内容替换enumerateItems(for:startingAt :)的内容:

let task = NetworkClient.shared.getMediaItems(atPath: path) { results, error in
  guard let results = results else {
    let error = error ?? FileProviderError.noContentFromServer
    observer.finishEnumeratingWithError(error)
    return
  }

  let items = results.map { mediaItem -> FileProviderItem in
    let ref = MediaItemReference(path: self.path, filename: mediaItem.name)
    return FileProviderItem(reference: ref)
  }

  observer.didEnumerate(items)
  observer.finishEnumerating(upTo: nil)
}

currentTask = task

这里,提供的网络客户端代码获取指定路径上的所有项目。 成功请求后,枚举器的观察者通过调用didEnumerate然后使用finishEnumerating(upTo :)来返回新数据,以指示批次项目的结束。 它通过调用finishEnumeratingWithError通知枚举器的观察者是否从请求中发生错误。

注意:生产应用程序可能使用分页来获取数据。 它将使用NSFileProviderPage方法参数来执行此操作。 在这种情况下,应用程序将使用整数作为页面索引,然后将其序列化并存储在NSFileProviderPage结构中。

完成枚举器的最后一步是将以下内容添加到invalidate()

currentTask?.cancel()
currentTask = nil

如果需要,这将取消当前的网络请求。 了解用户设备上的资源使用总是一个好主意,例如网络或位置访问。

完成该方法后,就可以使用此枚举器访问存储在后端的数据。 应用程序逻辑的其余部分将进入FileProviderExtension类。

打开Provider / FileProviderExtension.swift并用以下内容替换item(for :)的内容:

guard let reference = MediaItemReference(itemIdentifier: identifier) else {
  throw NSError.fileProviderErrorForNonExistentItem(withIdentifier: identifier)
}
return FileProviderItem(reference: reference)

系统提供传递给此方法的标识符,并返回该标识符的FileProviderItemguard语句确保标识符创建有效的MediaItemReference

接下来,使用以下代码替换urlForItem(withPersistentIdentifier :)persistentIdentifierForItem(at :)

// 1
override func urlForItem(withPersistentIdentifier
  identifier: NSFileProviderItemIdentifier) -> URL? {
  guard let item = try? item(for: identifier) else {
    return nil
  }
  
  return NSFileProviderManager.default.documentStorageURL
    .appendingPathComponent(identifier.rawValue, isDirectory: true)
    .appendingPathComponent(item.filename)
}

// 2
override func persistentIdentifierForItem(at url: URL) -> NSFileProviderItemIdentifier? {
  let identifier = url.deletingLastPathComponent().lastPathComponent
  return NSFileProviderItemIdentifier(identifier)
}

继续这个:

  • 1) 验证项目以确保给定标识符解析为扩展模型的实例。 然后返回一个文件URL,指定将项目存储在文件管理器的文档存储目录中的位置。
  • 2) urlForItem(withPersistentIdentifier :)返回的每个URL都需要映射回最初设置为表示的NSFileProviderItemIdentifier。 在该方法中,您以 / / 格式构建了URL,因此在这里您将采用倒数第二个路径组件作为项标识符。

有两种方法需要您引用引用远程文件的文件占位符URL。 首先,您将创建一个帮助方法来创建此占位符。 将以下内容添加到providePlaceholder(at :)

// 1
guard 
  let identifier = persistentIdentifierForItem(at: url),
  let reference = MediaItemReference(itemIdentifier: identifier) 
  else {
    throw FileProviderError.unableToFindMetadataForPlaceholder
}
 
// 2
try fileManager.createDirectory(
  at: url.deletingLastPathComponent(),
  withIntermediateDirectories: true,
  attributes: nil
)

// 3  
let placeholderURL = NSFileProviderManager.placeholderURL(for: url)
let item = FileProviderItem(reference: reference)
  
// 4
try NSFileProviderManager.writePlaceholder(
  at: placeholderURL,
  withMetadata: item
)

下面就是在做的事情:

  • 1) 首先,您从提供的URL创建标识符和引用。 如果失败,则抛出错误。
  • 2) 创建占位符时,必须确保封闭目录存在,否则您将遇到问题。 因此,使用NSFileManager来执行此操作。
  • 3) 传递给此方法的url用于显示图像,而不是占位符。 因此,您使用placeholderURL(for :)创建占位符URL,并获取此占位符将表示的NSFileProviderItem
  • 4) 将占位符项写入文件系统。

接下来,使用以下内容替换providePlaceholder(at:completionHandler :)的内容:

do {
  try providePlaceholder(at: url)
  completionHandler(nil)
} catch {
  completionHandler(error)
}

当需要占位符URL时,File Provider将调用providePlaceholder(at:completionHandler :)。 在其中,您尝试使用上面构建的帮助程序创建占位符,如果出现错误,则将其传递给completionHandler。 成功之后,您无需传递任何内容 - File Provider只需要您编写占位符URL,就像在providePlaceholder(at :)中一样。

当用户导航目录时,File Provider将调用enumerator(for:)以请求给定标识符的FileProviderEnumerator。 用以下内容替换此存根方法的内容:

if containerItemIdentifier == .rootContainer {
  return FileProviderEnumerator(path: "/")
}

guard 
  let ref = MediaItemReference(itemIdentifier: containerItemIdentifier),
  ref.isDirectory 
  else {
    throw FileProviderError.notAContainer
}

return FileProviderEnumerator(path: ref.path)

此方法确保提供的标识符的项目是目录。 如果标识符是根项,则仍然创建枚举器,因为根是有效目录。

建立并运行。 应用启动后,切换到Files应用并启用应用的扩展程序。 点击Browse选项卡栏项两次以导航到Files的根目录。 选择More Locations并切换Provider,这是扩展名称。

注意:如果找不到More Locations下列出的Provider,请点击右上角的Edit按钮,以确保列表中显示已禁用的扩展名。

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第4张图片

您现在有一个有效的File Provider extension! 缺少一些重要的东西,但接下来你会添加它们。


Providing Thumbnails

由于此应用程序应显示后端的图像,因此显示图像的缩略图非常重要。 有一种覆盖方法可以处理扩展的缩略图生成。

enumerator(for:)以下添加:

// MARK: - Thumbnails
  
override func fetchThumbnails(
  for itemIdentifiers: [NSFileProviderItemIdentifier],
  requestedSize size: CGSize,
  perThumbnailCompletionHandler: 
    @escaping (NSFileProviderItemIdentifier, Data?, Error?) -> Void,
  completionHandler: @escaping (Error?) -> Void) 
    -> Progress {
  // 1
  let progress = Progress(totalUnitCount: Int64(itemIdentifiers.count))

  for itemIdentifier in itemIdentifiers {
    // 2
    let itemCompletion: (Data?, Error?) -> Void = { data, error in
      perThumbnailCompletionHandler(itemIdentifier, data, error)

      if progress.isFinished {
        DispatchQueue.main.async {
          completionHandler(nil)
        }
      }
    }

    guard 
      let reference = MediaItemReference(itemIdentifier: itemIdentifier),
      !reference.isDirectory 
      else {
        progress.completedUnitCount += 1

        let error = NSError.fileProviderErrorForNonExistentItem(
          withIdentifier: itemIdentifier
        )
        itemCompletion(nil, error)
        continue
    }

    let name = reference.filename
    let path = reference.containingDirectory

    // 3
    let task = NetworkClient.shared
      .downloadMediaItem(named: name, at: path) { url, error in
        guard 
          let url = url,
          let data = try? Data(contentsOf: url, options: .alwaysMapped) 
          else {
            itemCompletion(nil, error)
            return
        }
        itemCompletion(data, nil)
    }

    // 4
    progress.addChild(task.progress, withPendingUnitCount: 1)
  }

  return progress
}

虽然这种方法非常冗长,但其逻辑很简单:

  • 1) 此方法返回一个Progress对象,该对象跟踪每个缩略图请求的状态。
  • 2) 它为每个itemIdentifier定义一个完成块。 该块将负责调用此方法所需的每个项块以及最后调用最后一个块。
  • 3) 缩略图文件使用启动器项目附带的NetworkClient从服务器下载到临时文件。 下载完成后,完成处理程序将下载的数据data传递给itemCompletion闭包。
  • 4) 每个下载任务都作为依赖项添加到父进程对象。

注意:在处理较大的数据集时,为每个占位符发出单独的网络请求可能需要一些时间。 因此,如果可能,您的后端集成应提供在单个请求中批量下载图像的方法。

建立并运行。 在Files中打开扩展名,您应该看到加载缩略图。

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第5张图片

Viewing Items

现在,当您选择一个项目时,该应用会显示一个没有完整图像的空白视图:

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第6张图片

到目前为止,您只实现了预览缩略图的显示 - 现在是时候添加查看完整内容的功能了!

与缩略图生成一样,查看项目内容只需要一种方法,即startProvidingItem(at:completionHandler :)。 将以下内容添加到FileProviderExtension类的底部:

// MARK: - Providing Items

override func startProvidingItem(
  at url: URL, 
  completionHandler: @escaping ((_ error: Error?) -> Void)) {
  // 1
  guard !fileManager.fileExists(atPath: url.path) else {
    completionHandler(nil)
    return
  }

  // 2
  guard 
    let identifier = persistentIdentifierForItem(at: url),
    let reference = MediaItemReference(itemIdentifier: identifier) 
    else {
      completionHandler(FileProviderError.unableToFindMetadataForItem)
      return
  }

  // 3
  let name = reference.filename
  let path = reference.containingDirectory
  NetworkClient.shared
    .downloadMediaItem(named: name, at: path, isPreview: false) { fileURL, error in
    // 4
    guard let fileURL = fileURL else {
      return completionHandler(error)
    }

    // 5
    do {
      try self.fileManager.moveItem(at: fileURL, to: url)
      completionHandler(nil)
    } catch {
      completionHandler(error)
    }
  }
}

这是代码的作用:

  • 1) 检查指定URL中是否已存在某个项目,以防止再次请求相同的数据。 在实际案例使用中,您应该检查修改日期和文件版本,以确保您拥有最新数据。 但是,在本教程中没有必要这样做,因为它不支持版本控制。
  • 2) 获取关联URL的MediaItemReference,以便您知道需要从后端获取哪个文件。
  • 3) 从引用中提取名称和路径以从后端请求文件内容。
  • 4) 如果下载文件时出错,则会失败。
  • 5) 将文件从其临时下载目录移动到扩展指定的文档存储URL。

建立并运行。 打开扩展程序后,选择一个项目以查看完整版本。

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第7张图片

当您打开更多文件时,扩展程序将需要处理删除下载的文件。File Provider extension内置了此功能。

您必须覆盖stopProvidingItem(at :)以清理文件并为其提供新的占位符。 在FileProviderExtension类的底部添加以下内容:

override func stopProvidingItem(at url: URL) {
  try? fileManager.removeItem(at: url)
  try? providePlaceholder(at: url)
}

这将删除该项,并调用providePlaceholder(at :)以生成新的占位符。

这样就完成了File Provider的最基本功能。 文件枚举,缩略图预览和查看文件内容是此扩展的基本组件。

恭喜, File Provider完整且功能齐全!

了解可以在Apple’s Documentation about File Providers中为File Provider实施的更多操作。 您还可以使用其他扩展程序将自定义UI添加到File Provider,您可以在here阅读更多相关信息。

后记

本篇主要讲述了实现File Provider extension,感兴趣的给个赞或者关注~~~

FileProvider框架详细解析 (二) —— 实现File Provider extension(一)_第8张图片

你可能感兴趣的:(FileProvider框架详细解析 (二) —— 实现File Provider extension(一))