SwiftMessages 10.0.0

SwiftMessages 10.0.0

测试已测试
语言语言 SwiftSwift
许可证 MIT
发布最新版本2024年2月
SPM支持SPM

Timothy Moose维护。



  • 作者:
  • Timothy Moose

SwiftMessages

Twitter: @TimothyMoose Version License Platform Carthage compatible

概览

SwiftMessages 是一个适用于iOS的非常灵活的视图和视图控制器展示库。

消息视图和视图控制器可以显示在屏幕的顶部、底部或中心,或在导航栏和标签栏后面。它包含包括基于物理的互动消失手势在内的多种手势。多种背景变暗模式。还有很多更多!

除了众多的配置选项,SwiftMessages还提供了几个美观的布局和主题。SwiftMessages对设计师友好,这意味着您可以完全轻松地自定义视图

  • 将其中一个包含的nib文件复制到您的项目中并修改它。
  • 从子类MessageView添加元素等。
  • 或者只需提供一个任意的UIView实例。

请尝试通过appetize.io上的演示应用来探索SwiftMessages的广泛可配置性。

视图控制器

SwiftMessages可以使用自定义模态切换SwiftMessagesSegue来呈现视图控制器!

pod 'SwiftMessages'

github "SwiftKickMobile/SwiftMessages"

用户手册

  1. 将SwiftMessages仓库放置在您的项目目录中的某个位置。
  2. 在Xcode中,将SwiftMessages.xcodeproj添加到您的项目中。
  3. 在您的应用程序目标上,在“常规”选项卡中将SwiftMessages框架
    1. 作为嵌入式二进制文件。
    2. 在“构建阶段”选项卡中作为目标依赖项。

使用方法

基础知识

SwiftMessages.show(view: myView)

尽管您可以展示任何UIView实例,但SwiftMessages提供了一个MessageView类以及一系列基于nib的布局,这些布局应该能处理大多数情况

// Instantiate a message view from the provided card view layout. SwiftMessages searches for nib
// files in the main bundle first, so you can easily copy them into your project and make changes.
let view = MessageView.viewFromNib(layout: .cardView)

// Theme message elements with the warning style.
view.configureTheme(.warning)

// Add a drop shadow.
view.configureDropShadow()

// Set message title, body, and icon. Here, we're overriding the default warning
// image with an emoji character.
let iconText = ["🤔", "😳", "🙄", "😶"].randomElement()!
view.configureContent(title: "Warning", body: "Consider yourself warned.", iconText: iconText)

// Increase the external margin around the card. In general, the effect of this setting
// depends on how the given layout is constrained to the layout margins.
view.layoutMarginAdditions = UIEdgeInsets(top: 20, left: 20, bottom: 20, right: 20)

// Reduce the corner radius (applicable to layouts featuring rounded corners).
(view.backgroundView as? CornerRoundingView)?.cornerRadius = 10

// Show the message.
SwiftMessages.show(view: view)

您可能希望使用视图提供者变体的show(viewProvider:),以确保您的UIKit代码在主队列中执行

SwiftMessages.show {
    let view = MessageView.viewFromNib(layout: .cardView)
    // ... configure the view
    return view
}

提供者结构SwiftMessages.Config提供了多个可以通过show()传递的配置选项

var config = SwiftMessages.Config()

// Slide up from the bottom.
config.presentationStyle = .bottom

// Display in a window at the specified window level.
config.presentationContext = .window(windowLevel: .statusBar)

Note that, as of iOS 13, it is no longer possible to cover the status bar
regardless of the window level. A workaround is to hide the status bar instead.
config.prefersStatusBarHidden = true

// Disable the default auto-hiding behavior.
config.duration = .forever

// Dim the background like a popover view. Hide when the background is tapped.
config.dimMode = .gray(interactive: true)

// Disable the interactive pan-to-hide gesture.
config.interactiveHide = false

// Specify a status bar style to if the message is displayed directly under the status bar.
config.preferredStatusBarStyle = .lightContent

// Specify one or more event listeners to respond to show and hide events.
config.eventListeners.append() { event in
    if case .didHide = event {
        print("yep id=\(String(describing: event.id)")
    }
}

SwiftMessages.show(config: config, view: view)

指定默认配置选项

SwiftMessages.defaultConfig.presentationStyle = .bottom

// Show message with default config.
SwiftMessages.show(view: view)

// Customize config using the default as a base.
var config = SwiftMessages.defaultConfig
config.duration = .forever
SwiftMessages.show(config: config, view: view)

无障碍访问

SwiftMessages提供了出色的VoiceOver支持。

  • 当消息显示时,标题和正文的组合成为一个单一公告。可以将MessageView.accessibilityPrefix属性设置为公告前面附加额外的解释性文本。

    有时,一条消息可能包含一些重要的视觉提示,这些提示没有在标题或正文中捕获。例如,消息可能依赖于黄色背景来传达警告,而不是在标题或正文中使用“警告”一词。在这种情况下,将MessageView.accessibilityPrefix = "warning"可能是有帮助的。

  • 如果消息使用config.dimMode以昏暗视图显示,则昏暗视图下面的元素在消息隐藏之前不可聚焦。如果config.dimMode.interactive == true,则昏暗视图本身将是可聚焦的,并将读取“取消”接着是“按钮”。前一个文本可以通过设置config.dimModeAccessibilityLabel属性来自定义。

请参阅AccessibleMessage协议以在自定义视图中实现适当的辅助功能支持。

键盘避免

KeyboardTrackingView类可用于使消息视图在键盘太靠近时向上滑动以避免键盘。

var config = SwiftMessages.defaultConfig
config.keyboardTrackingView = KeyboardTrackingView()

即使您不是使用SwiftMessages,也可以将KeyboardTrackingView集成到您的应用中。通过将KeyboardTrackingView锚定到屏幕的底部、左边和右边来安装到视图层次结构中。然后,将您应避免触摸键盘的内容的底部锚定到顶部的KeyboardTrackingView。使用等式约束严格跟踪键盘,或使用不等式约束在键盘太靠近时才移动。KeyboardTrackingView通过监听键盘通知并调整其高度以保持其顶边在键盘之上来工作,从而推动您的上下文向上。请参阅KeyboardTrackingView中的注释以获取配置选项。

消息队列

您可以根据需要多次调用SwiftMessages.show()。SwiftMessages维护一个队列,一次仅显示一条消息。如果您的视图实现了Identifiable协议(如MessageView),则自动删除重复的消息。可以调整消息之间的暂停时间。

SwiftMessages.pauseBetweenMessages = 1.0

有几种方法可以程序性地隐藏消息

// Hide the current message.
SwiftMessages.hide()

// Or hide the current message and clear the queue.
SwiftMessages.hideAll()

// Or for a view that implements `Identifiable`:
SwiftMessages.hide(id: someId)

// Or hide when the number of calls to show() and hideCounted(id:) for a 
// given message ID are equal. This can be useful for messages that may be
// shown from  multiple code paths to ensure that all paths are ready to hide.
SwiftMessages.hideCounted(id: someId)

可以使用多个SwiftMessages实例同时显示多条消息。请注意,SwiftMessage中的静态SwiftMessages.show()和其他静态API只是对共享实例SwiftMessages.sharedInstance)的便利包装。实例必须被保留,因此它应该是某个东西的属性(例如您的视图控制器)

class SomeViewController: UIViewController {
    let otherMessages = SwiftMessages()	
	
    func someMethod() {
        SwiftMessages.show(...)
        otherMessages.show(...)
    }
}

检索消息

有几个API可用于检索当前正在显示、隐藏或已排队显示的消息。这些API在事件发生时更新消息很有用,而无需保留临时引用。请参阅eventListeners

// Get a message view with the given ID if it is currently 
// being shown or hidden.
if let view = SwiftMessages.current(id: "some id") { ... }

// Get a message view with the given ID if is it currently 
// queued to be shown. 
if let view = SwiftMessages.queued(id: "some id") { ... }

// Get a message view with the given ID if it is currently being
// shown, hidden or in the queue to be shown.
if let view = SwiftMessages.currentOrQueued(id: "some id") { ... }

定制

SwiftMessages可以显示任何UIView。然而,可以对捆绑的视图进行不同程度的自定义。

Nib文件

SwiftMessages捆绑的所有消息设计都有相关的nib文件。建议您将这些nib文件复制到您的项目中,并修改以满足需求。SwiftMessages将加载您复制的文件而不是原始文件。您可以使用拖放操作在Xcode中复制nib文件。

为了方便使用基于nib的布局,MessageView提供了一些类型安全的便捷方法来加载捆绑的nib。

let view = MessageView.viewFromNib(layout: .cardView)

此外,SwiftMessages类也提供了某些通用加载方法。

// Instantiate MessageView from a named nib.
let view: MessageView = try! SwiftMessages.viewFromNib(named: "MyCustomNib")

// Instantiate MyCustomView from a nib named MyCustomView.nib.
let view: MyCustomView = try! SwiftMessages.viewFromNib()

MessageView类

位于MessageView的所有捆绑设计都使用它。它主要由以下可选的@IBOutlet属性组成

元素 声明 描述
标题 titleLabel: UILabel? 消息标题。
消息体 bodyLabel: UILabel? 消息体。
图像图标 iconImageView: UIImageView? 基于图像的图标。
文本图标 iconLabel: UILabel? 图像图标的基于文本(表情符号)的替代品。
按钮 button: UIButton? 动作按钮。

SwiftMessages的nib文件使用MessageView作为顶级视图,内容连接到这些占位符。布局是通过堆叠视图完成的,这意味着你只需隐藏元素即可删除它

view.titleLabel.isHidden = true

一个常见错误是尝试通过将相应的占位符设置为nil来删除元素。这是因为它不会从视图层次结构中删除元素。

配置

MessageView提供了遵循configure*命名约定的众多方法

view.configureTheme(.warning)
view.configureContent(title: "Warning", body: "Consider yourself warned.", iconText: "🤔")

所有这些方法都是快速配置底层视图属性的快捷方式。SwiftMessages力求在这些方法中避免任何内部魔法,因此不需要调用它们。您可以直接配置视图属性或组合两种方法。

交互

MessageView为按钮和视图本身提供了一个可选的基于块的手动处理程序

// Hide when button tapped
messageView.buttonTapHandler = { _ in SwiftMessages.hide() }

// Hide when message view tapped
messageView.tapHandler = { _ in SwiftMessages.hide() }

扩展

要从MessageView开始,并添加新的元素,如额外的按钮,建议的方法如下:

  1. 将捆绑的nib文件之一复制到您的项目中,或者从头开始创建一个。
  2. 将新元素添加到nib文件中。
  3. 子类化MessageView并为新元素创建出口。
  4. 将nib文件中的顶层视图分配到子类。
  5. 在nib文件和子类之间连接出口。
  6. (推荐)根据需要覆盖Identifiable的实现,将新元素纳入消息的身份。
  7. (推荐)根据需要覆盖AccessibleMessage的实现,将新元素纳入Voice Over。
  8. 使用上述nib加载方法之一加载视图。

BaseView 类

BaseViewMessageView的父类,提供许多不是针对MessageView的“标题 + 正文 + 图标 + 按钮”设计的选项。与MessageView显著不同的自定义视图(例如进度指示器)应子类化BaseView

CornerRoundingView 类

CornerRoundingView是一个自定义视图,消息可以使用它来使用椭圆对视图的所有部分或一部分进行圆角处理(您在应用图标上看到的更平滑的圆角处理方法)。具有圆角特征的nib文件将backgroundView分配给CornerRoundingView。它提供了一个roundsLeadingCorners选项,用于在从顶部或底部显示时动态圆角仅圆角视图的前角(这是一个用于选项卡样式布局的功能)。

Animator 协议

Animator 是 SwiftMessages 用于展示和消失动画的协议。通过 SwiftMessages.PresentationStyle.custom(animator:) 可以实现自定义动画。一些相关组件

  • TopBottomAnimationAnimator 的滑动实现,用于 .top.bottom 展示样式内部。它提供了一些定制选项。
  • PhysicsAnimation.center 展示样式中使用的缩放+不透明度实现,它提供了一套有趣的物理消失手势,并提供包括 .top.bottom 位置的定制选项。
  • PhysicsPanHandlerPhysicsAnimation 提供了基于物理的消失手势,并可以整合到其他的 Animator 实现中。

欢迎为酷炫的 Animator 实现提供高质量的 PR!

MarginAdjustable 协议

MarginAdjustable 是被 BaseView 采纳的协议。如果被展示的视图采纳了 MarginAdjustable,SwiftMessages 会接管这个视图的布局边距,以确保在整个展示上下文中理想的空间。

BackgroundViewable 协议

BackgroundViewable 是被 BaseView 采纳的协议,要求视图提供一个 backgroundView 属性。BaseView 会初始化 backgroundView = self,你可以自由地将它重新赋值给任意子视图。

如果被展示的视图采纳了 BackgroundViewable,SwiftMessages 将会忽略 backgroundView 之外的所有触摸。这是非常重要的,因为消息视图总是占据设备的全宽。卡片和标签样式布局看起来从设备的边缘缩进,因为消息视图的背景是透明的,并且 backgroundView 被赋值给一个子视图,该子视图被约束在布局边距中。在这些布局中,应该忽略透明边距内的触摸。

可识别协议

Identifiable 是由 MessageView 采用的协议,要求视图提供一个单独的 id 属性,SwiftMessages 使用该属性进行消息去重。

MessageView 根据消息内容计算 id,但根据需要也可以显式设置 id

可访问消息协议

AccessibleMessage 是由 MessageView 采用的协议。如果要展示的视图采用 AccessibleMessage,SwiftMessages 将提供改进的 Voice Over 功能。

关于 SwiftKick Mobile

我们打造高质量的应用程序!如需项目帮助,请联系我们。

授权

SwiftMessages 根据MIT授权协议进行分发。有关详细信息,请参阅 LICENSE