`标语牌 (Placard)`

Placard 是一个小型且易于使用的包，用于使用 SwiftUI 呈现动画消息栏。

消息视图可以显示在屏幕的顶部、底部或中心，并且可以使用 UIEdgeInsets 从屏幕边缘和垂直位置偏移。

具有交互式的显示、点击和关闭手势 - 一系列动画主题可供选择（或者如果您需要，可以选择无动画）。

Placard 允许您为基于优先级的消息等内容选择默认消息主题，但也提供通过参数、配置对象进行的自定义，或者您可以使用自己的 SwiftUI 视图并让 Placard 控制其动画和外观。可以配置 Placard 以显示任意时间段（默认情况下，它会永远显示 - 或者直到用户点击它）。此外，所有 Placard 消息都可以指定一个在用户点击时执行的动作（但如果 Placard 通过超时自动关闭，则不会）。

标语牌会自动重绘自身，以适应设备方向的变化

要求

Placard 仅针对 iOS 17.2 及更高版本构建和测试。

通过 PlacardDemo 项目运行 Placard

PlacardDemo 应用程序允许您探索 Placard，包括默认选项和通过更改配置进行探索

下载此存储库的 zip 文件并将其解压缩。运行 PlacardDemo.xcodeproj 并选择 iphone 或 ipad 作为模拟器的目标（请参阅“要求”部分，了解所需的 xcode 构建）。

本文档中 Placard 的图片全部取自 PlacardDemo 项目的屏幕截图。

Placard 的安装

要通过演示界面试用 Placard，请参阅上面的部分。但是，如果您想在自己的项目中使用 Placard，请通过 Swift Package Manager 或手动下载 Placard

使用 Swift Package Manager

转到 Xcode 中的 File | Swift Packages | Add Package Dependency... 并搜索“Placard”。

来自 Swift Package Index

从 Swift Package Index 获取 Placard

用法

使用 Placard 很简单，但了解 Placard 由您可以使用的三个视图组成会有所帮助

PlacardPriorityView：一种简单、内置的方式，用于显示基于优先级的状态消息。
PlacardView：另一种内置类型，但比 PlacardPriorityView 更可配置，并且没有优先级。
PlacardCustomView：Placard 将获取您的 SwiftUI 视图并将其显示为标语牌！

配置

Placard 类型采用类型为 PlacardConfig 的配置，您可以使用它来更改 Placard 视图的行为、位置和格式。配置不是必需的，但允许您自定义 Placard。

Placard 配置的协议是 PlacardConfigP

public protocol PlacardConfigP {
    var backgroundColor: UIColor? { get }
    var primaryFont: UIFont? { get }
    var secondaryFont: UIFont? { get }
    var accentColor: UIColor? { get }
    var titleTextColor: UIColor? { get }
    var placement: PlacardPlacement? { get }
    var insets: UIEdgeInsets? { get }
    var showAnimation: TransitionAnimation? { get }
    var hideAnimation: TransitionAnimation? { get }
    var tapAnimation: TapAnimation? { get }
    var fadeAnimation: Bool? { get }
}

以下是对这些属性的描述

配置属性	描述
backgroundColor	Placard 视图的背景颜色（作为 UIColor）
primaryFont	标题的字体
secondaryFont	状态消息的字体
accentColor	Placard 视图的强调色（作为 UIColor）（用于状态消息的前景色）
titleTextColor	用于 Placard 视图标题和 systemImage 前景颜色的颜色（作为 UIColor）
placement	在设备屏幕上放置 Placard 视图的位置
insets	用于从其 PlacardPlacement 偏移 Placard 视图的 UIEdgeInsets
showAnimation	Placard 视图出现时要使用的动画
hideAnimation	Placard 视图消失时要使用的动画
tapAnimation	用户点击 Placard 视图时要使用的动画
fadeAnimation	如果为 true，则显示和隐藏动画将分别淡入或淡出

在下面的示例中，所有可用的配置选项都已设置

let config = PlacardConfig(backgroundColor: .darkGray,
                            primaryFont: UIFont.systemFont(ofSize: 30.0, weight: .heavy),
                            secondaryFont: UIFont.systemFont(ofSize: 16.0, weight: .regular),
                            accentColor: .red,
                            titleTextColor: .yellow,
                            placement: .top,
                            insets: UIEdgeInsets(top: 50, left: 20, bottom: 0, right: 20),
                            showAnimation: .spin,
                            hideAnimation: .fade,
                            tapAnimation: .pulseIn,
                            fadeAnimation: true)

其中两个属性，Insets 和 Animations，需要更详细的说明

Insets

用于从其 PlacardPlacement 偏移 Placard 视图的 UIEdgeInsets。请记住，UIEdgeInsets.left 和 UIEdgeInsets.right 的作用是将 Placard 视图从设备屏幕的边缘“推开”（允许用户创建不跨越屏幕的 Placard）。此外，所有值都应该是正偏移量 - UIEdgeInsets.top 的值为 50 会将 Placard 视图从设备顶部推送 50 个点（无论其方向如何）。 UIEdgeInsets.bottom 的值为 50 会将 Placard 视图从设备底部推送 50 个点（朝向中心）。

Note that for:
- PlacardPlacement.top - UIEdgeInsets.bottom is ignored
- PlacardPlacement.bottom - UIEdgeInsets.top is ignored

动画

过渡动画

这些是在标语牌显示和隐藏时发生的动画过渡的类型。可用选项包括

public enum TransitionAnimation {
    case none, fade, rollUp, rollDown, floatUp, floatDown, floatLeft, floatRight, toX, toY, toPoint, spin, spinOnX, spinOnY
}

过渡动画的示例

点击动画

这些是用户点击标语牌时发生的动画（随后是动作完成和标语牌的关闭）。可用选项包括

public enum TapAnimation {
    case none, pulseIn, pulseOut, zoomInWithEasing, zoomOutWithEasing
}

点击动画的示例

通过动画 gif 很难看到差异，但请使用 PlacardDemo 应用程序来更清楚地了解这些差异。

缩小，缓入

放大，缓出

脉冲发出

脉冲进入

使用配置的另一种方法 - 使用枚举。这基本上与使用 PlacardConfig 实例相同，但是您可以定义一个配置类型（符合 PlacardConfigP）并将其传递进去。

    enum Custom: PlacardConfigP {
        // the type we are defining
        case terminal

        var backgroundColor: UIColor? {
            switch self { case .terminal: return .lightGray }
        }

        var accentColor: UIColor? {
            switch self {
            case .terminal: return .purple
            }
        }

        var primaryFont: UIFont? {
            switch self {
            case .terminal: return UIFont(name: "HelveticaNeue-Light", size: 24.0)
            }
        }

        var secondaryFont: UIFont? {
            switch self {
            case .terminal: return UIFont(name: "HelveticaNeue-Light", size: 16.0)
            }
        }

        var titleTextColor: UIColor? {
            switch self { case .terminal: return .green }
        }

        var placement: PlacardPlacement? {
            switch self { default: return .center }
        }

        var insets: UIEdgeInsets? {
            switch self { default: return UIEdgeInsets(top: 0, left: 20, bottom: 0, right: 20) }
        }

        var showAnimation: TransitionAnimation? {
            switch self { default: return .spinOnX }
        }

        var hideAnimation: TransitionAnimation? {
            switch self { default: return .spinOnY }
        }

        var tapAnimation: TapAnimation? {
            switch self { default: return .zoomOutWithEasing }
        }

        var fadeAnimation: Bool? {
            switch self { default: return true }
        }
    }

它将像这样使用

    PlacardView(
        title: "You Dawg!",
        statusMessage: "Git that squeaky!",
        systemImageName: "pawprint",
        config: Custom.terminal
    )

PlacardPriorityView

PlacardPriorityView 类型是内置的 Placard，旨在用于基于优先级的用户状态消息。您可以通过 PlacardPriorityView 的参数更改消息的标题和正文，以及图像。您还可以传入自己的配置来更改更多内容（请参阅上面的配置部分）。但这些旨在快速轻松地表示状态。

您可以更改以下任何参数，但只有 title 和 statusMessage 是必需的。

参数	类型	描述
title	String	标语牌的标题
statusMessage	String	标语牌的状态消息
systemImageName	String	要用作图标的系统图像（SF 符号）的名称
config	PlacardConfig	配置文件（请参阅上面的部分）
duration	Double	标语牌要显示的秒数
action	() -> Void	用户点击标语牌时要执行的动作
priority	PlacardPriority	.success、.info、.warning、.error 或 .default 优先级

在这里，我们使用我们自己的标题和状态消息创建一个成功消息

PlacardPriorityView(title: "Success!", 
                    statusMessage: "Some status message", 
                    priority: .success)

PlacardView

PlacardView 类型与 PlacardPriorityView 类型相似，但没有与其关联的优先级。它可以以相同的方式进行自定义。

其可用的参数集为

参数	类型	描述
title	String	标语牌的标题
statusMessage	String	标语牌的状态消息
systemImageName	String	要用作图标的系统图像（SF 符号）的名称
config	PlacardConfig	配置文件（请参阅上面的部分）
duration	Double	标语牌要显示的秒数
action	() -> Void	用户点击标语牌时要执行的动作

在这里，我们传入我们自己的 systemImage 来显示

    PlacardView(title: "Don't forget to smile!",
                statusMessage: "Teeth are like bats that hang from your gums.",
                systemImageName: "mouth.fill")

Placard 接受一个动作（类型为 () -> Void），以便在点击时执行（仅当点击时 - 如果您设置了持续时间并且 Placard 在用户点击之前过期，则不会触发该动作）。

PlacardView(title: "Don't forget to smile!",
            statusMessage: "Teeth are like bats that hang from your gums.",
            systemImageName: "face.smiling",
            action: { print("You tapped me!") })

PlacardCustomView

当您想在使用 Placard 的功能的同时提供自己的 SwiftUI 视图时，您将使用 PlacardCustomView。

PlacardCustomView 的可用参数集为

参数	类型	描述
title	String	标语牌的标题
statusMessage	String	标语牌的状态消息
content	UIView	您的 SwiftUI 视图
config	PlacardConfig	配置文件（请参阅上面的部分）
duration	Double	标语牌要显示的秒数
action	() -> Void	用户点击标语牌时要执行的动作

定义您自己的 SwiftUI 视图以用作标语牌。这是一个例子

    struct ViewWithButton: View {
        @State var action: Bool

        var body: some View {
            var color: String {
                if action { return "red" }
                return "green"
            }

            VStack {
                Text("Make me see \\(color)")
                    .background(action ? .green : .red)
                Button(action: {
                    action.toggle()
                }) {
                    HStack {
                        Image(systemName: "face.dashed")
                            .font(.title)
                            .foregroundColor(action ? .green : .red)
                        Text("change me")
                            .fontWeight(.semibold)
                            .font(.title)
                    }
                    .padding()
                    .foregroundColor(.white)
                    .background(Color.black)
                    .cornerRadius(40)
                }
            }
            .frame(maxWidth: .infinity, minHeight: 200, alignment: .center)
            .background(Color(red: 155/255, green: 198/255, blue: 222/255))
        }
    }

将该视图传递到 PlacardCustomView 实例中

    PlacardCustomView(title: "some title", statusMessage: "some body", config: custom_config) {
        // SwiftUI view
        ViewWithButton(action: toggle)
    }