iOS首页进度卡开发：状态边界比渐变条更难

前言

在健康、训练与打卡类应用中，首页常展示一种“连续 N 天完成”的状态卡片。表面上看只是一个普通模块，但实际它集成了进度展示、剩余天数提示、完成状态切换、二次操作入口及自定义弹窗等多重功能。若仅临时叠加多个控件，后期维护将变得极其困难。

一个更清晰的思路是：将其设计为一个双状态组件，而非一张“会变色的卡片”。

为何进度卡不能仅靠 isHidden 打补丁

许多开发者在实现进度卡时倾向于：先堆砌所有控件，在tracking状态隐藏部分元素，completed状态再显示另一部分。短期内看似简便，长期却导致两大典型问题：状态逻辑难以维护，交互事件相互干扰。

更推荐的做法是显式建立一个状态枚举模型：

enum ProgressCardStyle {case tracking(remainingDays: Int, completedDays: Int)case completed}

这样，组件在 configure 时无需猜测显示内容，状态清晰明了。

组件层仅处理状态和事件，不涉及业务逻辑

本次设计的进度卡最终暴露了三个清晰的事件：onInfoTap、onRecalculateTap、onUnlockTap。组件只负责传递用户行为，至于点击后弹出内容、是否重置、如何跳转等，全部交由页面控制器处理。

大致结构如下：

final class ProgressCardView: UIView {
    var onInfoTap: (() -> Void)?
    var onRecalculateTap: (() -> Void)?
    var onUnlockTap: (() -> Void)?

    private let infoButton = UIButton(type: .system)
    private let recalculateButton = UIButton(type: .system)
    private let unlockButton = UIButton(type: .system)

    override init(frame: CGRect) {
        super.init(frame: frame)
        infoButton.addTarget(self, action: #selector(infoTapped), for: .touchUpInside)
        recalculateButton.addTarget(self, action: #selector(recalculateTapped), for: .touchUpInside)
        unlockButton.addTarget(self, action: #selector(unlockTapped), for: .touchUpInside)
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    @objc private func infoTapped() { onInfoTap?() }
    @objc private func recalculateTapped() { onRecalculateTap?() }
    @objc private func unlockTapped() { onUnlockTap?() }
}

这一设计的好处是：后续无论页面流程如何变更，卡片本身无需介入任何业务判断。

tracking 与 completed 两个状态如何落地

通常可按如下方式拆分：

tracking 状态

• 白色背景卡片
• 左侧信息图标
• 中部文案显示剩余天数
• 下方进度条与日期刻度

completed 状态

• 高亮卡片背景
• 完成态文案
• Recalculate 按钮
• 主 CTA 按钮

这意味着两种状态共享同一组件入口，但内部布局与交互焦点截然不同。

为何进度条更适合使用 CAGradientLayer

当设计稿中的进度条为渐变色且宽度需动态变化时，强烈推荐使用 CAGradientLayer，而非图片平铺或 patternImage。以下是一个简易实现示例：

final class GradientProgressView: UIView {
    private let trackView = UIView()
    private let fillView = UIView()
    private let gradientLayer = CAGradientLayer()
    private var fillWidthConstraint: NSLayoutConstraint?
    private var progressRatio: CGFloat = 0

    override init(frame: CGRect) {
        super.init(frame: frame)
        trackView.backgroundColor = UIColor(hex: "#ECEBF6")
        trackView.layer.cornerRadius = 5
        trackView.layer.masksToBounds = true
        fillView.layer.cornerRadius = 5
        fillView.layer.masksToBounds = true

        [trackView].forEach {
            $0.translatesAutoresizingMaskIntoConstraints = false
            addSubview($0)
        }
        fillView.translatesAutoresizingMaskIntoConstraints = false
        trackView.addSubview(fillView)
        fillView.layer.addSublayer(gradientLayer)

        NSLayoutConstraint.activate([
            trackView.leadingAnchor.constraint(equalTo: leadingAnchor),
            trackView.trailingAnchor.constraint(equalTo: trailingAnchor),
            trackView.topAnchor.constraint(equalTo: topAnchor),
            trackView.bottomAnchor.constraint(equalTo: bottomAnchor),
            fillView.leadingAnchor.constraint(equalTo: trackView.leadingAnchor),
            fillView.topAnchor.constraint(equalTo: trackView.topAnchor),
            fillView.bottomAnchor.constraint(equalTo: trackView.bottomAnchor)
        ])
        fillWidthConstraint = fillView.widthAnchor.constraint(equalToConstant: 0)
        fillWidthConstraint?.isActive = true

        gradientLayer.colors = [UIColor(hex: "#7B39ED").cgColor, UIColor(hex: "#9B59F0").cgColor]
        gradientLayer.startPoint = CGPoint(x: 0, y: 0.5)
        gradientLayer.endPoint = CGPoint(x: 1, y: 0.5)
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    override func layoutSubviews() {
        super.layoutSubviews()
        fillWidthConstraint?.constant = trackView.bounds.width * progressRatio
        gradientLayer.frame = fillView.bounds
    }

    func updateProgress(_ ratio: CGFloat) {
        progressRatio = max(0, min(1, ratio))
        fillWidthConstraint?.constant = trackView.bounds.width * progressRatio
        layoutIfNeeded()
    }
}

这种方式最主要的优势是：动态宽度控制更稳定，圆角端点更自然，颜色与渐变方向能精准匹配设计稿。

自定义弹窗为何建议挂载到 window

若项目中已存在自定义 tabbar 或底部持续置顶容器，将 overlay 添加到当前页面 view 上时常常遇到一个问题：弹窗显示、页面变暗，但底部导航依然可见。推荐的解决方案是直接将 overlay 挂载到当前 window：

func presentDimOverlay(_ overlay: UIView, from hostView: UIView) {
    guard let window = hostView.window else {
        hostView.addSubview(overlay)
        overlay.frame = hostView.bounds
        return
    }
    window.addSubview(overlay)
    overlay.frame = window.bounds
}

此方法对于“自定义底部导航 + 自定义弹窗”的搭配尤其有效。

一个极易被忽略的问题：显示层不应伪造状态

开发中还遇到一个典型陷阱：进度重置后，视觉上仍显示已完成第1天。原因并非数据未清空，而是 view 层为进度条设置了“最小显示宽度”，导致 0 天 看起来像有部分进度。这里的原则至关重要：若真实状态为 0，则 UI 必须如实显示 0。

总结

这类首页状态卡片看似只是一个模块，实则是一个典型的“小型状态系统”。若希望后期易于维护，请务必遵循以下原则：

1. 显式定义状态枚举，避免依赖大量 isHidden 补丁
2. 组件仅暴露事件接口，不直接参与业务判断
3. 渐变进度条优先使用 CAGradientLayer
4. 全屏 overlay 优先挂载到 window 层级
5. 显示层绝不可伪造真实状态

一句话总结：优秀的状态卡片并非控件堆砌而成，而是具有清晰状态边界、交互边界和显示边界的组件。