iOS方法功能描述生成器

方法概述 在指定的 UIViewController 上以线程安全的方式展示 UIAlertController，统一在主线程执行，支持多个按钮（UIAlertAction）及其样式配置（default/cancel/destructive）。方法会自动处理 iPad 上的弹出锚点（popover sourceView/sourceRect）与横竖屏适配，避免因缺少锚点导致的崩溃；具备重复弹出防护，若目标控制器当前已有警告弹窗正在展示，将跳过重复呈现。提供 completion 回调以便在弹窗完全消失后获知结束时机。适用于错误提示、权限引导、确认操作等通用场景。

可参考的签名形式（示例）：

• Swift: func presentAlert(on presenter: UIViewController, title: String?, message: String?, actions: [UIAlertAction], completion: (() -> Void)?)
• Objective-C:
  • (void)presentAlertOn:(UIViewController *)presenter title:(nullable NSString *)title message:(nullable NSString *)message actions:(NSArray<UIAlertAction *> *)actions completion:(void (^ _Nullable)(void))completion;

参数说明

• on / presenter

  • 类型：UIViewController
  • 作用：作为弹窗的呈现者（presenting view controller）。
  • 要求：应处于可见或即将可见的视图层级；方法内部在主线程安全调用。若该控制器当前正展示其他 UIAlertController，方法将避免再次弹出重复警告。

• title

  • 类型：String? / NSString * _Nullable
  • 作用：弹窗标题，显示为加粗文本。
  • 取值：可为空；建议简洁明确，避免过长文本影响可读性。

• message

  • 类型：String? / NSString * _Nullable
  • 作用：弹窗正文内容。
  • 取值：可为空；建议控制在若干行内，必要时考虑换行或更详细的说明链接。

• actions

  • 类型：[UIAlertAction] / NSArray<UIAlertAction *>
  • 作用：用户可交互的按钮集合，按数组顺序展示。
  • 取值与规则：
    • 至少提供一个按钮以保证可关闭性（通常包括一个 .default 或 .cancel）。
    • 样式支持：.default、.cancel（最多一个）、.destructive。
    • 按钮的 handler 在用户点选后执行，随后弹窗关闭。

• completion

  • 类型：(()->Void)? / void (^ _Nullable)(void)
  • 作用：在 UIAlertController 完全消失（dismiss 完成）后回调，用于后续流程衔接（如导航跳转、重试等）。
  • 线程：在主线程回调。

返回值

• 无（Void）。显示与关闭的结果通过用户操作与 completion 回调获知。

使用示例

• 示例一：错误提示（单按钮确认） Swift: let ok = UIAlertAction(title: "确定", style: .default) { _ in // 记录日志或清理状态 } presentAlert(on: self, title: "网络错误", message: "请求失败，请检查网络连接后重试。", actions: [ok], completion: nil)

• 示例二：权限引导（跳转系统设置） Swift: let cancel = UIAlertAction(title: "取消", style: .cancel, handler: nil) let settings = UIAlertAction(title: "前往设置", style: .default) { _ in if let url = URL(string: UIApplication.openSettingsURLString), UIApplication.shared.canOpenURL(url) { UIApplication.shared.open(url) } } presentAlert(on: self, title: "需要相机权限", message: "请在系统设置中开启相机访问权限以继续拍摄。", actions: [cancel, settings]) { // 弹窗关闭后的后续处理（如刷新权限状态） }

Objective-C（同场景）： UIAlertAction *cancel = [UIAlertAction actionWithTitle:@"取消" style:UIAlertActionStyleCancel handler:nil]; UIAlertAction *settings = [UIAlertAction actionWithTitle:@"前往设置" style:UIAlertActionStyleDefault handler:^(__unused UIAlertAction *action) { NSURL *url = [NSURL URLWithString:UIApplicationOpenSettingsURLString]; if (url && [[UIApplication sharedApplication] canOpenURL:url]) { [[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil]; } }]; [Helper presentAlertOn:self title:@"需要相机权限" message:@"请在系统设置中开启相机访问权限以继续拍摄。" actions:@[cancel, settings] completion:^{ // 弹窗关闭回调 }];

注意事项

• 主线程调用：方法内部已确保在主线程执行 UI 呈现；若在后台线程调用，将自动切换至主线程。
• 重复弹出防护：在同一 presenter 上已有 UIAlertController 正在显示时，本方法会跳过后续相同时机的展示，避免多层警告叠加或竞争呈现。
• iPad 适配：当使用需要 popover 锚点的呈现形式（如 Action Sheet）时，本方法将为 popoverPresentationController 自动设置合适的 sourceView/sourceRect，避免在 iPad 上因缺失锚点导致的崩溃；横竖屏切换场景下能保持锚点有效。
• 操作规范：
  • actions 中最多只包含一个 .cancel 按钮，并建议置于数组末尾以符合人机界面指南。
  • 在按钮 handler 中避免强引用循环（使用 [weak self] / __weak），并谨慎执行耗时操作。
• 展示时机：确保 presenter 已加入窗口层级并可展示。若在 viewDidLoad 等过早时机调用，可能不会出现弹窗；建议在视图出现后调用（如 viewDidAppear）或在可见性已确认的业务回调中调用。
• 文本与本地化：标题与正文建议本地化处理，并在多语言与动态字体（Dynamic Type）场景下进行可读性验证。

相关方法

• UIKit：UIAlertController、UIAlertAction
• UIApplication.openSettingsURLString（跳转系统设置）
• UIViewController.present(_:animated:completion:)（系统呈现接口，用于理解底层行为）

• 方法概述 提供通用的去抖动工具：在指定的 delay 时间窗口内合并多次触发，仅在窗口结束时执行最后一次动作。支持自定义执行所用的 DispatchQueue，并在新触发到来时自动取消上一次尚未执行的计划任务。方法设计为线程安全，可在任意线程调用，适用于搜索输入联想、滚动事件统计、文本校验等高频事件场景，以减少无效调用并提升性能。

• 参数说明

1. delay: TimeInterval

   • 作用：去抖时间窗口长度（秒）
   • 取值范围：建议使用非负数；通常 0.1~0.6 秒适用于用户输入与滚动等UI场景
   • 含义：在该时间窗口内若再次触发，将取消上一次未执行的计划，并重新计时

2. queue: DispatchQueue

   • 作用：执行最终动作的目标队列
   • 取值范围：任意 DispatchQueue；默认通常为 .main
   • 建议：涉及UI更新请选择 .main；纯计算或网络请求可使用后台队列

3. _: () -> Void

   • 作用：时间窗口结束后要执行的动作闭包
   • 行为：不会在触发时立即执行；只有在窗口内不再有新的触发时才执行

• 返回值

• 类型：() -> Void

• 含义：返回一个可重复调用的“触发闭包”。每次调用该触发闭包都会：

  • 取消（如果存在）上一次尚未执行的计划任务
  • 重新开始一个新的 delay 计时
  • 在 delay 结束且期间无再次触发时，于指定 queue 上执行传入的动作闭包

• 使用示例 示例一：搜索输入联想（在主线程合并快速输入）

final class SearchViewController: UIViewController, UITextFieldDelegate {
    @IBOutlet private weak var textField: UITextField!
    private var currentQuery: String = ""

    // 1) 创建去抖触发器，动作在主队列执行（更新UI安全）
    private lazy var debouncedSearch = debounce(delay: 0.35, queue: .main) { [weak self] in
        guard let self else { return }
        self.performSearch(query: self.currentQuery)
    }

    func textField(_ textField: UITextField, shouldChangeCharactersIn range: NSRange, replacementString string: String) -> Bool {
        if let r = Range(range, in: textField.text ?? "") {
            currentQuery = (textField.text ?? "").replacingCharacters(in: r, with: string)
        }
        // 2) 高频输入时仅在用户短暂停顿后触发搜索
        debouncedSearch()
        return true
    }

    private func performSearch(query: String) {
        // 发起搜索请求并更新UI
    }
}

示例二：滚动事件统计（在后台队列做聚合处理）

final class AnalyticsScrollDelegate: NSObject, UIScrollViewDelegate {
    private lazy var debouncedLog = debounce(delay: 0.5, queue: .global(qos: .utility)) {
        Analytics.logEvent("scroll_stopped", parameters: nil)
    }

    func scrollViewDidScroll(_ scrollView: UIScrollView) {
        // 高频调用：仅在用户停止滚动后再上报一次
        debouncedLog()
    }
}

• 注意事项

• 仅执行尾缘（trailing）调用：在时间窗口内的多次触发会被合并，最终只执行最后一次动作

• 可能“永不触发”：若触发频率始终高于 delay（窗口未能结束），动作将一直被取消且不会执行；若需要限制最小间隔但保证一定执行，请考虑使用节流（throttle）

• 线程与队列：

  • 触发闭包可在任意线程调用，内部保证状态一致性与线程安全
  • 动作闭包在传入的 queue 上执行；若动作包含UI更新，请选择 .main 或在动作内切回主线程

• 内存管理：动作闭包如捕获 self，请使用 [weak self] 以避免循环引用

• 参数建议：delay 使用正数以获得稳定的去抖效果；过小的窗口在高频触发下可能等同于“几乎每次都执行”

• 生命周期：请确保对返回的触发闭包保持有效引用；一旦触发闭包被释放，已有的计划任务可能被取消且不再执行

• 相关方法

• throttle(delay:queue:_:)：节流工具，在固定间隔内限制执行频率，常与去抖互补使用

• Timer/DispatchSourceTimer：用于自定义时序控制的底层计时工具（可实现更复杂的节流/去抖策略）