announcement-banner

用途

Announcement Banner Generator 用于为应用生成可配置的应用内公告/横幅系统，用于向用户显示上下文消息，例如维护提醒、新功能亮点、促销活动等。内容可来自远程配置或本地定义，并支持用户关闭、深链接动作与排期控制。

主要能力

生成的核心文件包括：

Announcement.swift：包含样式、动作、优先级、调度信息的模型
AnnouncementManager.swift：@Observable 管理器，负责加载、过滤、跟踪关闭状态
AnnouncementProvider.swift：协议以及带缓存的本地/远程实现
AnnouncementBannerView.swift：SwiftUI 横幅视图，支持按样式着色与动画
AnnouncementBannerModifier.swift：用于覆盖层放置和动作路由的 ViewModifier
AnnouncementScheduler.swift：若选择调度功能，则提供日期范围过滤与时区处理

系统支持三种横幅位置：顶部（推荐用于提醒）、底部、浮动居中遮罩。内容来源可选本地硬编码、远程 JSON 或两者结合（推荐）。动作类型支持深链接、URL 打开、仅关闭或全部。还可选择是否启用开始/结束日期的调度，并支持优先级排序、关闭状态持久化。

使用方式

技能激活时，会先进行预生成检查：检测 Swift 版本（要求 5.9+）、部署目标（iOS 16+ / macOS 13+）、@Observable 支持（iOS 17+ / macOS 14+）、源文件位置；搜索已存在的横幅/Toast 代码（如 /Banner.swift、/Announcement.swift 等），若发现 Firebase In-App Messaging、Braze、Intercom 等第三方库，会询问用户是否替换或保留；检测现有深链接设置（deepLink、universalLink、openURL、onOpenURL 等），有则集成，无则生成独立动作处理。

随后通过 AskUserQuestion 询问横幅位置、内容来源、动作类型、是否包含调度。生成时先读取 templates.md，再依次创建核心文件、UI 文件、可选文件，并确定文件位置（优先 Sources/AnnouncementBanner/，其次 App/AnnouncementBanner/，否则 AnnouncementBanner/）。

集成时在根视图添加横幅覆盖层：

ContentView()
    .announcementBanner()

自定义位置：

ContentView()
    .announcementBanner(position: .bottom)

自定义深链接动作处理：

ContentView()
    .announcementBanner { action in
        switch action {
        case .deepLink(let destination):
            router.navigate(to: destination)
        case .url(let url):
            openURL(url)
        case .dismiss:
            break
        }
    }

本地公告定义示例：

let provider = LocalAnnouncementProvider(announcements: [
    Announcement(
        id: "maintenance-2024",
        title: "Scheduled Maintenance",
        message: "We'll be performing maintenance on Saturday 9-11 AM EST.",
        style: .warning,
        action: .dismiss,
        priority: 10,
        startDate: maintenanceStart,
        endDate: maintenanceEnd
    ),
    Announcement(
        id: "new-feature-photos",
        title: "New: Photo Library",
        message: "Check out our new photo library with AI-powered search!",
        style: .promotion,
        action: .deepLink("app://features/photos"),
        priority: 5,
        isDismissible: true
    )
])

远程配置获取示例：

let provider = RemoteAnnouncementProvider(
    url: URL(string: "https://api.example.com/announcements")!,
    cacheDuration: 3600  // 1 hour
)

测试使用 Swift Testing 框架编写，例如验证关闭后的公告被隐藏、高优先级公告优先显示、过期公告被过滤。

常见模式包括维护横幅（高优先级、不可关闭）、新功能推广（深链接、可关闭）、限时促销（带开始/结束日期、目标受众）。

适用场景

当用户提出以下需求时可激活：添加公告横幅或应用内横幅、想要应用公告或通知横幅、提到促销横幅、询问维护通知或维护提醒、想要应用内消息或上下文横幅、要求显示公告或向用户展示提醒、提到功能亮点横幅或“新功能”横幅。

限制与注意事项

要求 Swift 5.9+，部署目标 iOS 16+ / macOS 13+；若使用 @Observable 需要 iOS 17+ / macOS 14+。
横幅不应堆叠：同一时间只显示一个横幅，用优先级决定显示哪个，其余排队等待关闭后再显示。
不要遮挡关键 UI：避免覆盖导航栏、标签栏或交互元素，应使用安全区插入。
尊重用户关闭：持久化已关闭公告 ID，避免应用重启后再次出现，可用 UserDefaults 或轻量存储。
远程配置缓存：缓存获取到的公告，避免每次启动都发起网络请求，遵循缓存时长但允许强制刷新。
日期/时区处理：远程配置中的开始/结束日期始终使用 UTC，仅在展示时转换为本地时区。
无障碍：使用 AccessibilityNotification.Announcement 宣告横幅出现，确保关闭按钮有正确标签。
动画中断：若用户在动画中途离开，需确保横幅状态正确重置，可将 .task 绑定到视图生命周期。

参考文件：templates.md（所有生产级 Swift 模板）；相关：generators/deep-linking（深链接路由集成）、generators/whats-new（功能亮点“新功能”界面）。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项