SwiftMessages
概览
SwiftMessages 是一个适用于iOS的非常灵活的视图和视图控制器展示库。
消息视图和视图控制器可以显示在屏幕的顶部、底部或中心,或在导航栏和标签栏后面。它包含包括基于物理的互动消失手势在内的多种手势。多种背景变暗模式。还有很多更多!
除了众多的配置选项,SwiftMessages还提供了几个美观的布局和主题。SwiftMessages对设计师友好,这意味着您可以完全轻松地自定义视图
- 将其中一个包含的nib文件复制到您的项目中并修改它。
- 从子类
MessageView
添加元素等。 - 或者只需提供一个任意的
UIView
实例。
请尝试通过appetize.io上的演示应用来探索SwiftMessages的广泛可配置性。
视图控制器
SwiftMessages可以使用自定义模态切换SwiftMessagesSegue
来呈现视图控制器!
pod 'SwiftMessages'
github "SwiftKickMobile/SwiftMessages"
用户手册
- 将SwiftMessages仓库放置在您的项目目录中的某个位置。
- 在Xcode中,将
SwiftMessages.xcodeproj
添加到您的项目中。 - 在您的应用程序目标上,在“常规”选项卡中将SwiftMessages框架
- 作为嵌入式二进制文件。
- 在“构建阶段”选项卡中作为目标依赖项。
使用方法
基础知识
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
开始,并添加新的元素,如额外的按钮,建议的方法如下:
- 将捆绑的nib文件之一复制到您的项目中,或者从头开始创建一个。
- 将新元素添加到nib文件中。
- 子类化
MessageView
并为新元素创建出口。 - 将nib文件中的顶层视图分配到子类。
- 在nib文件和子类之间连接出口。
- (推荐)根据需要覆盖
Identifiable
的实现,将新元素纳入消息的身份。 - (推荐)根据需要覆盖
AccessibleMessage
的实现,将新元素纳入Voice Over。 - 使用上述nib加载方法之一加载视图。
BaseView 类
BaseView
是MessageView
的父类,提供许多不是针对MessageView
的“标题 + 正文 + 图标 + 按钮”设计的选项。与MessageView
显著不同的自定义视图(例如进度指示器)应子类化BaseView
。
CornerRoundingView 类
CornerRoundingView
是一个自定义视图,消息可以使用它来使用椭圆对视图的所有部分或一部分进行圆角处理(您在应用图标上看到的更平滑的圆角处理方法)。具有圆角特征的nib文件将backgroundView
分配给CornerRoundingView
。它提供了一个roundsLeadingCorners
选项,用于在从顶部或底部显示时动态圆角仅圆角视图的前角(这是一个用于选项卡样式布局的功能)。
Animator 协议
Animator
是 SwiftMessages 用于展示和消失动画的协议。通过 SwiftMessages.PresentationStyle.custom(animator:)
可以实现自定义动画。一些相关组件
TopBottomAnimation
是Animator
的滑动实现,用于.top
和.bottom
展示样式内部。它提供了一些定制选项。PhysicsAnimation
是.center
展示样式中使用的缩放+不透明度实现,它提供了一套有趣的物理消失手势,并提供包括.top
和.bottom
位置的定制选项。PhysicsPanHandler
为PhysicsAnimation
提供了基于物理的消失手势,并可以整合到其他的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。