StatefulViewController 3.0

StatefulViewController 3.0

×

测试已测试✓
Lang语言 SwiftSwift
许可证 MIT
发布最后发布2016年11月
SwiftSwift 版本3.0
SPM支持 SPM✗

由 Alexander Schuch 维护。

StatefulViewController 3.0

StatefulViewController

一个协议，允许 UIViewController 或 UIView 根据内容、加载、错误或空状态来展示占位符视图。

StatefulViewController Example

概述

在网络应用程序中，视图控制器或自定义视图通常有以下状态，这些状态需要告知用户：

  • 加载：内容目前正在通过网络加载。
  • 内容：内容可用并向用户展示。
  • 空：目前没有可展示的内容。
  • 错误：下载内容时出现错误。

虽然这个流程听起来很简单，但有很多情况会导致一个相当大的决策树。

Decision Tree

StatefulViewController 是这个特定决策树的实体实现。（如果您想创建自己的版本，可能会对用于显示和隐藏视图的 状态机 感兴趣。）

版本兼容性

当前 Swift 兼容性分解

Swift 版本 框架版本
3.0 master
2.3 2.x
2.2 1.x

使用方法

本指南描述了在 UIViewController 上使用 StatefulViewController 协议。但是，您也可以在任何 UIViewController 子类（如 UITableViewController 或 UICollectionViewController）以及您的自定义 UIView 子类上采用 StatefulViewController 协议。

首先，请确保您的视图控制器采用了 StatefulViewController 协议。

class MyViewController: UIViewController, StatefulViewController {
    // ...
}

然后，在 viewDidLoad 中配置 StatefulViewController 协议提供的 loadingView、emptyView 和 errorView 属性。

override func viewDidLoad() {
    super.viewDidLoad()

    // Setup placeholder views
    loadingView = // UIView
    emptyView = // UIView
    errorView = // UIView
}

此外，请在 viewWillAppear: 中调用 setupInitialViewState() 方法以设置控制器的初始状态。

override func viewWillAppear(animated: Bool) {
    super.viewWillAppear(animated)

    setupInitialViewState()
}

之后，只需告知视图控制器何时加载内容，而 StatefulViewController 将为您显示和隐藏正确的加载、错误和空视图。

override func viewWillAppear(animated: Bool) {
    super.viewWillAppear(animated)

    loadDeliciousWines()
}

func loadDeliciousWines() {
    startLoading()

    let url = NSURL(string: "http://example.com/api")
    let session = NSURLSession.sharedSession()
    session.dataTaskWithURL(url) { (let data, let response, let error) in
        endLoading(error: error)
    }.resume()
}

生命周期

StatefulViewController 调用 hasContent 方法来检查是否有内容可以显示。如果您在自己的类中没有重写此方法，则 StatefulViewController 将始终假定有内容可以显示。

func hasContent() -> Bool {
    return datasourceArray.count > 0
}

可选地，当内容已显示时，您还可能想响应错误。在这种情况下，StatefulViewController 不会显示其 errorView，因为已经有可以显示的内容。

例如，要显示自定义警报或其他非侵入性错误消息，请使用 handleErrorWhenContentAvailable: 手动呈现错误给用户。

func handleErrorWhenContentAvailable(error: ErrorType) {
    let alertController = UIAlertController(title: "Ooops", message: "Something went wrong.", preferredStyle: .Alert)
    alertController.addAction(UIAlertAction(title: "OK", style: .Default, handler: nil))
    self.presentViewController(alertController, animated: true, completion: nil)
}

自定义占位符视图内边距

默认情况下，StatefulViewController 以全屏方式（即从父视图顶部、底部、左侧和右侧为0内边距）呈现所有配置的占位符视图。如果占位符视图应具有自定义内边距，则配置的占位符视图可以遵守 StatefulPlaceholderView 协议并重写 placeholderViewInsets 方法以返回自定义边缘内边距。

class MyPlaceholderView: UIView, StatefulPlaceholderView {
  func placeholderViewInsets() -> UIEdgeInsets {
    return UIEdgeInsets(top: 20, left: 20, bottom: 20, right: 20)
  }
}

视图状态机

注意：以下部分仅针对那些想要创建与上述流程不同的状态控制器的人。

您也可以使用底层的视图状态机为您自定义的显示/隐藏视图流程创建类似的实现。

let stateMachine = ViewStateMachine(view: view)

// Add states
stateMachine["loading"] = loadingView
stateMachine["other"] = otherView

// Transition to state
stateMachine.transitionToState(.View("loading"), animated: true) {
    println("finished switching to loading view")
}

// Hide all views
stateMachine.transitionToState(.None, animated: true) {
    println("all views hidden now")
}

安装

手动

只需将两个 .swift 文件从 StatefulViewController 文件夹拖放到您的项目中即可。

测试

打开 Xcode 项目，按 ⌘-U 运行测试。

或者，您可以通过使用 xctool 从终端运行所有测试。

xctool -scheme StatefulViewControllerTests -sdk iphonesimulator test

待办事项

  • 默认加载、错误、空视图
  • 视图协议，通知视图移除和添加
  • 视图可以提供延迟，以告知状态机在特定延迟后将显示/删除它们（例如，用于隐藏和显示动画）

贡献

  • 创建一些令人惊叹的东西，改进代码，添加一些功能，无论是什么（这是最困难的）。
  • 分叉它
  • 创建一个新分支以进行更改
  • 将所有更改提交到您的分支上
  • 提交一个 pull request

联系

随时联系我们。