标题图片

Popovers

一个用于展示弹出窗口的库。

在应用程序的主要内容上方展示任何视图。
可以附加到源视图或使用画中画定位。
同时显示多个弹出窗口，并带有流畅的过渡效果。
支持SwiftUI、UIKit和iPadOS上的多任务窗口。
高度可定制的API，使用极其简单 - 只需添加.popover。
可作为iOS 14的Menu的替代品，同时兼容iOS 13。
基于SwiftUI的核心，结构轻量。无依赖项。
2023年了 - 是时候让弹出窗口变得有趣了！

展示厅

示例

包含约20个弹出窗口示例。下载

示例应用

安装

需要iOS 13+。Popovers可以通过Swift Package Manager（推荐）或Cocoapods安装。

<table> <tr> <td> <strong> Swift Package Manager </strong> <br> 添加包URL： </td> <td> <strong> Cocoapods </strong> <br> 在Podfile中添加： </td> </tr> <tr> <td> <br>

https://github.com/aheze/Popovers

</td> <td> <br>

pod 'Popovers'

</td> </tr> </table>

使用方法

要在SwiftUI中展示弹出窗口，请使用.popover(present:attributes:view)修饰符。默认情况下，弹出窗口使用其父视图作为源框架。

import SwiftUI
import Popovers

struct ContentView: View {
    @State var present = false
    
    var body: some View {
        Button("显示弹出窗口！") {
            present = true
        }
        .popover(present: $present) { /// 在这里！
            Text("嗨，我是一个弹出窗口。")
                .padding()
                .foregroundColor(.white)
                .background(.blue)
                .cornerRadius(16)
        }
    }
}

在UIKit中，创建一个Popover实例，然后使用UIViewController.present(_:)进行展示。您还应该设置源框架。

import SwiftUI
import Popovers

class ViewController: UIViewController {
    @IBOutlet weak var button: UIButton!
    @IBAction func buttonPressed(_ sender: Any) {
        var popover = Popover { PopoverView() }
        popover.attributes.sourceFrame = { [weak button] in
            button.windowFrame()
        }
        
        present(popover) /// 在这里！
    }
}

struct PopoverView: View {
    var body: some View {
        Text("嗨，我是一个弹出窗口。")
            .padding()
            .foregroundColor(.white)
            .background(.blue)
            .cornerRadius(16)
    }
}

自定义

🔖	💠	⬜	🔲	⏹	🟩	🟥	🎾	🛑	👓	👉	🎈	🔰

通过Attributes结构体自定义弹出窗口。几乎所有内容都可以自定义，包括定位、动画和关闭行为。

<table> <tr> <td> <strong> SwiftUI </strong> <br> 在<code>attributes</code>参数中配置。 </td> <td> <strong> UIKit </strong> <br> 修改<code>attributes</code>属性。 </td> </tr> <tr> <td> <br>

.popover(
    present: $present,
    attributes: {
        $0.position = .absolute(
            originAnchor: .bottom,
            popoverAnchor: .topLeft
        )
    }
) {
    Text("嗨，我是一个弹出窗口。")
}

</td> <td> <br>

var popover = Popover {
    Text("嗨，我是一个弹出窗口。")
}

popover.attributes.position = .absolute(
    originAnchor: .bottom,
    popoverAnchor: .topLeft
)

present(popover)

</td> </tr> </table>

🔖 标签 • `AnyHashable?`

为弹出窗口添加标签，以便以后从任何地方访问它们。这对于更新现有的弹出窗口很有用。

/// 设置标签。
$0.tag = "你的标签"

/// 稍后访问它。
let popover = popover(tagged: "你的标签") /// 其中`self`是一个`UIView`或`UIViewController`。

/// 如果在SwiftUI视图中，请使用`WindowReader`：
WindowReader { window in
    let popover = window.popover(tagged: "你的标签")
}

注意： 当你使用.popover(selection:tag:attributes:view:)修饰符时，这个tag会自动设置为你在参数中提供的值。

💠 位置 • `Position`

弹出窗口的位置可以是.absolute（附加到视图）或.relative（画中画）。枚举的关联值还可以配置使用哪些侧边和角落。

Anchor代表侧边和角落。
对于.absolute，提供原点锚点和弹出窗口锚点。
对于.relative，提供弹出窗口锚点。如果有多个，用户将能够像PIP一样在它们之间拖动。锚点参考 | .absolute(originAnchor: .bottom, popoverAnchor: .topLeft) | .relative(popoverAnchor: [.right]) --- | --- | --- | |

⬜ 源框架 • `(() -> CGRect)`

这是弹出窗口附加到或放置在其中的框架，具体取决于其位置。这必须是全局窗口坐标。由于框架经常变化，此属性是一个闭包。每当设备旋转或发生其他边界更新时，都会调用该闭包。

<table> <tr> <td> <strong> SwiftUI </strong> <br> 默认情况下，源框架会自动设置为父视图。设置此项将覆盖它。 </td> <td> <strong> UIKit </strong> <br> 强烈建议提供一个源框架，否则弹出窗口将出现在屏幕的左上角。 </td> </tr> <tr> <td> <br>

$0.sourceFrame = {
    /** 这里是一些 CGRect */
}

</td> <td> <br>

 /// 使用 `weak` 防止循环引用
attributes.sourceFrame = { [weak button] in
    button.windowFrame()
}

</td> </tr> </table>

🔲 源框架内边距 • `UIEdgeInsets`

应用于源框架的边缘内边距。正值会缩小框架，负值会扩大框架。

绝对	相对

⏹ 屏幕边缘填充 • `UIEdgeInsets`

所有弹出窗口的全局内边距，防止它们溢出屏幕。类似于安全区域。默认值为 UIEdgeInsets(top: 16, left: 16, bottom: 16, right: 16)。

🟩 呈现 • `Presentation`

此属性存储弹出窗口出现时应用的动画和过渡效果。

/// 默认值：
$0.presentation.animation = .easeInOut
$0.presentation.transition = .opacity

🟥 解除 • `Dismissal`

此属性存储弹出窗口的解除行为。这里有几个子属性。

/// 与 `Presentation` 相同。
$0.dismissal.animation = .easeInOut
$0.dismissal.transition = .opacity

/// 高级设置！以下是它们的默认值：
$0.dismissal.mode = .tapOutside
$0.dismissal.tapOutsideIncludesOtherPopovers = false
$0.dismissal.excludedFrames = { [] }
$0.dismissal.dragMovesPopoverOffScreen = true
$0.dismissal.dragDismissalProximity = CGFloat(0.25)

模式： 配置弹出窗口应如何自动解除。你可以同时使用多个！

.tapOutside - 当用户在弹出窗口外点击时解除。
.dragDown - 当用户向下拖动时解除。
.dragUp - 当用户向上拖动时解除。
.none - 不自动解除弹出窗口。

点击外部包括其他弹出窗口： 仅当 mode 为 .tapOutside 时适用。如果启用此选项，当用户在外部点击时，弹出窗口将被解除，即使点击的是另一个已呈现的弹出窗口。通常情况下，当你点击另一个已呈现的弹出窗口时，当前弹出窗口不会解除。

排除的框架： 仅当 mode 为 .tapOutside 时适用。当用户在弹出窗口外点击，但点击落在这些框架之一时，弹出窗口将保持呈现状态。如果你想要多个弹出窗口，你应该将其他弹出窗口的源框架设置为排除的框架。

/// 将一个弹出窗口的源框架设置为另一个的排除框架。
/// 这可以防止当前弹出窗口在动画到另一个弹出窗口之前被解除。

let popover1 = Popover { Text("你好") }
popover1.attributes.sourceFrame = { [weak button1] in button1.windowFrame() }
popover1.attributes.dismissal.excludedFrames = { [weak button2] in [ button2.windowFrame() ] }

let popover2 = Popover { Text("你好") }
popover2.attributes.sourceFrame = { [weak button2] in button2.windowFrame() }
popover2.attributes.dismissal.excludedFrames = { [weak button1] in [ button1.windowFrame() ] }

拖动将弹出窗口移出屏幕： 仅当 mode 为 .dragDown 或 .dragUp 时适用。如果启用此选项，用户拖动后弹出窗口将继续移出屏幕。

拖动解除接近度： 仅当 mode 为 .dragDown 或 .dragUp 时适用。表示拖动必须达到的屏幕点以自动解除。此属性乘以屏幕高度。

🎾 橡皮筋模式 • `RubberBandingMode`

配置弹出窗口在拖动时可以在哪些轴上"橡皮筋"效果。默认值为 [.xAxis, .yAxis]。

.xAxis - 在 x 轴上启用橡皮筋效果。
.yAxis - 在 y 轴上启用橡皮筋效果。
.none - 禁用橡皮筋效果。

🛑 阻止背景触摸 • `Bool`

设置为 true 可防止底层视图被按下。

👓 辅助功能 • `Accessibility` • `v1.2.0`

Popovers 完全支持辅助功能！Accessibility 结构提供了额外的选项，用于 VoiceOver 如何读出内容。

/// 默认值：
$0.accessibility.shiftFocus = true
$0.accessibility.dismissButtonLabel = defaultDismissButtonLabel /// 包装在 `AnyView?` 中的 X 图标

切换焦点： 如果启用，VoiceOver 将在弹出窗口呈现后立即聚焦于它。

解除按钮标签： 当 VoiceOver 开启时，出现在弹出窗口旁边的按钮。默认情况下，这是一个 <kbd>X</kbd> 圆圈。

<img src="https://yellow-cdn.veclightyear.com/835a84d5/80bf0064-9ae2-495d-98a0-554d11343d93.png" width=300 alt="VoiceOver 高亮显示弹出窗口，旁边有一个 X 按钮。">

提示：你也可以使用辅助功能退出手势（双指 Z 形滑动）来解除所有弹出窗口。

👉 点击外部时 • `(() -> Void)?`

当用户在弹出窗口外点击时调用的闭包。

🎈 解除时 • `(() -> Void)?`

当弹出窗口被解除时调用的闭包。

🔰 上下文变化时 • `((Context) -> Void)?`

当上下文发生变化时调用的闭包。上下文包含弹出窗口的属性、当前框架和其他可见特征。

<br>

实用工具

📘	🧩	🌃	📖	🏷	📄

Popovers 提供了一些功能来简化你的工作。

📘 菜单

v1.3.0 中的新功能！模板 Menu 在外观和行为上几乎与系统菜单完全相同，但也可以在 iOS 13 上使用。它还非常可定制，支持手动呈现和自定义视图。

<img src="https://yellow-cdn.veclightyear.com/835a84d5/da85840c-baf2-42c8-a0b5-2bd770812570.gif" width=500 alt="系统菜单和 Popovers 的自定义菜单并排显示">

<details> <summary>SwiftUI（基础）</summary>

struct ContentView: View {
    var body: some View {
        Templates.Menu {
            Templates.MenuButton(title: "按钮 1", systemImage: "1.circle.fill") { print("按钮 1 被按下") }
            Templates.MenuButton(title: "按钮 2", systemImage: "2.circle.fill") { print("按钮 2 被按下") }
        } label: { fade in
            Text("呈现菜单！")
                .opacity(fade ? 0.5 : 1)
        }
    }
}

</details> <details> <summary>SwiftUI（自定义）</summary> ```swift Templates.Menu( configuration: { $0.width = 360 $0.backgroundColor = .blue.opacity(0.2) } ) { Text("嗨，我是一个菜单!") .padding()

Templates.MenuDivider()

Templates.MenuItem {
    print("项目被点击")
} label: { fade in
    Color.clear.overlay(
        AsyncImage(url: URL(string: "https://getfind.app/image.png")) {
            $0.resizable().aspectRatio(contentMode: .fill)
        } placeholder: {
            Color.clear
        }
    )
    .frame(height: 180)
    .clipped()
    .opacity(fade ? 0.5 : 1)
}

} label: { fade in Text("显示菜单!") .opacity(fade ? 0.5 : 1) }


</details>

<details>
<summary>SwiftUI (手动显示)</summary>

```swift
struct ContentView: View {
    @State var present = false
    var body: some View {
        VStack {
            Toggle("激活", isOn: $present)
                .padding()
                .background(.regularMaterial)
                .cornerRadius(12)
                .padding()
            
            Templates.Menu(present: $present) {
                Templates.MenuButton(title: "按钮 1", systemImage: "1.circle.fill") { print("按钮 1 被按下") }
                Templates.MenuButton(title: "按钮 2", systemImage: "2.circle.fill") { print("按钮 2 被按下") }
            } label: { fade in
                Text("显示菜单!")
                    .opacity(fade ? 0.5 : 1)
            }
        }
    }
}

</details> <details> <summary>UIKit (基础)</summary>

class ViewController: UIViewController {
    @IBOutlet var label: UILabel!

    lazy var menu = Templates.UIKitMenu(sourceView: label) {
        Templates.MenuButton(title: "按钮 1", systemImage: "1.circle.fill") { print("按钮 1 被按下") }
        Templates.MenuButton(title: "按钮 2", systemImage: "2.circle.fill") { print("按钮 2 被按下") }
    } fadeLabel: { [weak self] fade in
        self?.label.alpha = fade ? 0.5 : 1
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        _ = menu /// 创建菜单。
    }
}

</details> <details> <summary>UIKit (自定义)</summary>

class ViewController: UIViewController {
    @IBOutlet var label: UILabel!

    lazy var menu = Templates.UIKitMenu(
        sourceView: label,
        configuration: {
            $0.width = 360
            $0.backgroundColor = .blue.opacity(0.2)
        }
    ) {
        Text("嗨，我是一个菜单!")
            .padding()

        Templates.MenuDivider()

        Templates.MenuItem {
            print("项目被点击")
        } label: { fade in
            Color.clear.overlay(
                AsyncImage(url: URL(string: "https://getfind.app/image.png")) {
                    $0.resizable().aspectRatio(contentMode: .fill)
                } placeholder: {
                    Color.clear
                }
            )
            .frame(height: 180)
            .clipped()
            .opacity(fade ? 0.5 : 1)
        }
    } fadeLabel: { [weak self] fade in
        UIView.animate(withDuration: 0.15) {
            self?.label.alpha = fade ? 0.5 : 1
        }
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        _ = menu /// 创建菜单。
    }
}

</details> <details> <summary>UIKit (手动显示)</summary>

class ViewController: UIViewController {
    /// ...

    @IBAction func switchPressed(_ sender: UISwitch) {
        if menu.isPresented {
            menu.dismiss()
        } else {
            menu.present()
        }
    }
}

</details>

基础	自定义	手动显示

🧩 在弹出窗口之间进行动画过渡

只要视图结构相同，你就可以在弹出窗口之间平滑过渡。

<table> <tr> <td> <strong> SwiftUI </strong> <br> 使用 <code>.popover(selection:tag:attributes:view:)</code> 修饰符。 </td> <td> <strong> UIKit </strong> <br> 使用 <code>UIResponder.popover(tagged:)</code> 获取现有弹出窗口，然后调用 <code>UIResponder.replace(_:with:)</code>。 </td> </tr> <tr> <td> <br>

struct ContentView: View {
    @State var selection: String?
    
    var body: some View {
        HStack {
            Button("显示第一个弹出窗口") { selection = "1" }
            .popover(selection: $selection, tag: "1") {

                /// 当 selection == "1" 时显示。
                Text("嗨，我是一个弹出窗口。")
                    .background(.blue)
            }
            
            Button("显示第二个弹出窗口") { selection = "2" }
            .popover(selection: $selection, tag: "2") {

                /// 当 selection == "2" 时显示。
                Text("嗨，我是一个弹出窗口。")
                    .background(.green)
            }
        }
    }
}

</td> <td> <br>

@IBAction func button1Pressed(_ sender: Any) {
    var newPopover = Popover { Text("嗨，我是一个弹出窗口。").background(.blue) }
    newPopover.attributes.sourceFrame = { [weak button1] in button1.windowFrame() }
    newPopover.attributes.dismissal.excludedFrames = { [weak button2] in [button2.windowFrame()] }
    newPopover.attributes.tag = "弹出窗口 1"
    
    if let oldPopover = popover(tagged: "弹出窗口 2") {
        replace(oldPopover, with: newPopover)
    } else {
        present(newPopover) /// 如果旧弹出窗口不存在则显示。
    }
}
@IBAction func button2Pressed(_ sender: Any) {
    var newPopover = Popover { Text("嗨，我是一个弹出窗口。").background(.green) }
    newPopover.attributes.sourceFrame = { [weak button2] in button2.windowFrame() }
    newPopover.attributes.dismissal.excludedFrames = { [weak button1] in [button1.windowFrame()] }
    newPopover.attributes.tag = "弹出窗口 2"
    
    if let oldPopover = popover(tagged: "弹出窗口 1") {
        replace(oldPopover, with: newPopover)
    } else {
        present(newPopover)
    }
}

</td> </tr> </table>

<img src="https://yellow-cdn.veclightyear.com/835a84d5/2ccfdf11-e91d-4f71-bece-c6ea7af62e9d.gif" width=300 alt="弹出窗口之间的平滑过渡（从蓝色到绿色再返回）。">

🌃 背景

你可以在弹出窗口的背景中放置任何内容。

<table> <tr> <td> <strong> SwiftUI </strong> <br> 使用 <code>.popover(present:attributes:view:background:)</code> 修饰符。 </td> <td> <strong> UIKit </strong> <br> 使用 <code>Popover(attributes:view:background:)</code> 初始化器。 </td> </tr> <tr> <td> <br>

.popover(present: $present) {
    PopoverView()
} background: { /// 这里!
    Color.green.opacity(0.5)
}

</td> <td> <br>

var popover = Popover {
    PopoverView()
} background: { /// 这里!
    Color.green.opacity(0.5)
}

</td> </tr> </table> <img src="https://yellow-cdn.veclightyear.com/835a84d5/1993fb9d-7e48-4794-a0be-07435e11213b.png" width=200 alt="整个屏幕上的绿色背景，但在弹出窗口下方">

📖 弹出窗口读取器

这会读取弹出窗口的上下文，其中包含其框架、窗口、属性和各种其他属性。它有点像 GeometryReader，但更酷。你可以将其放在弹出窗口的视图或背景中。

.popover(present: $present) {
    PopoverView()
} background: {
    PopoverReader { context in
        Path {
            $0.move(to: context.frame.point(at: .bottom))
            $0.addLine(to: context.windowBounds.point(at: .bottom))
        }
        .stroke(Color.blue, lineWidth: 4)
    }
}

<img src="https://yellow-cdn.veclightyear.com/835a84d5/1cea9d8b-40fe-46a2-81fd-0c86063cfcdb.gif" width=200 alt="线条连接弹出窗口底部和屏幕底部">

🏷 框架标签

弹出窗口包含一种用于标记和读取 SwiftUI 视图框架的机制。你可以使用它来提供弹出窗口的 sourceFrame 或 excludedFrames。当与 PopoverReader 结合使用时，它也非常适合连接线条与锚点视图。

Text("这是一个视图")
    .frameTag("你的标签名称") /// 在窗口内添加标签。

/// ...

WindowReader { window in
    Text("点击我!")
    .popover(
        present: $present,
        attributes: {
            $0.sourceFrame = window.frameTagged("你的标签名称") /// 从窗口中检索标签。
        }
    )
}

📄 模板

快速开始可以使用一些模板。所有模板都位于 Templates 目录中，示例应用中有使用示例。

AlertButtonStyle - 类似系统警告的按钮样式。
VisualEffectView - 让你在 SwiftUI 中使用 UIKit 的模糊效果。
Container - BackgroundWithArrow 形状的包装视图。
Shadow - 一种更简单的应用阴影的方法。
BackgroundWithArrow - 带箭头的形状，看起来像系统弹出窗口。
CurveConnector - 可设置端点的可动画形状。
Menu - 从头构建的系统菜单。

<br>

注意事项

状态重新渲染

如果直接将变量传递给弹出视图，它可能不会更新。相反，将视图移到它自己的结构中，并传递一个 Binding。

<table> <tr> <td> <strong> 正确 </strong> <br> 弹出视图在单独的结构中，传递 <code>$string</code>。 </td> <td> <strong> 错误 </strong> <br> 按钮直接位于 <code>view</code> 参数内，接收 <code>string</code>。 </td> </tr> <tr> <td> <br>

struct ContentView: View {
    @State var present = false
    @State var string = "你好，我是一个弹出窗口。"

    var body: some View {
        Button("显示弹出窗口！") { present = true }
        .popover(present: $present) {
            PopoverView(string: $string) /// 传递一个 Binding ($)。
        }
    }
}

/// 创建一个单独的视图以确保按钮更新。
struct PopoverView: View {
    @Binding var string: String

    var body: some View {
        Button(string) { string = "字符串已更改。" }
        .background(.mint)
        .cornerRadius(16)
    }
}

</td> <td> <br>

struct ContentView: View {
    @State var present = false
    @State var string = "你好，我是一个弹出窗口。"

    var body: some View {
        Button("显示弹出窗口！") {
            present = true
        }
        .popover(present: $present) {

            /// 直接传递变量（不带 $）是不支持的。
            /// 按钮可能不会更新。
            Button(string) { 
                string = "字符串已更改。"
            }
            .background(.mint)
            .cornerRadius(16)
        }
    }
}

</td> </tr> </table>

支持多屏幕 • `v1.1.0`

Popovers 内置支持多屏幕，但获取框架标签需要引用宿主窗口。你可以通过 WindowReader 或 PopoverReader 的上下文获取。

WindowReader { window in 

}

/// 如果在弹出窗口的 `view` 或 `background` 内，请使用 `PopoverReader`。
PopoverReader { context in
    let window = context.window
}

弹出窗口层级

通过在视图上附加 .zIndex(_:) 来管理弹出窗口的 z 轴层级。更高的索引会将其置于前面。

社区

作者	贡献	需要帮助？
Popovers 由 aheze 制作。	欢迎所有贡献。只需 fork 仓库，然后提交拉取请求。	开一个 issue 或加入 Discord 服务器。你也可以在 Twitter 上联系我。或者阅读源代码 — 有很多注释。

使用 Popovers 的应用

Find 是一个可以让你在现实生活中查找文本的应用。Popovers 用于快速提示和替代菜单 — 下载来看看吧！

AnyTracker 是一个跟踪网站上的数字、文本和价格的应用。它使用 Popovers 显示带有漂亮背景模糊的精美对话框。

Track Attack! 是公路和赛道上的终极车辆爱好者应用。现代 UI。双前后摄像头。GPS 和传感器数据。转速和油门。Apple Watch 心率监测。赛道计圈和公路多路点导航。轻松导出和分享带数据叠加的视频。Track Attack 使用 Popovers 显示入门教程和应用内通知。

如果你有使用 Popovers 的应用，只需提交 PR 或给我发消息。

许可证

MIT License

Copyright (c) 2023 A. Zheng

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.