iOS 17 Widget "Please Adopt ContainerBackground API" 해결

🍎 Issue

어느 날 xcode15에서 Widget Preview를 확인해보니, "Please Adopt ContainerBackground Api" 라는 메세지가 노출되면서 Preview 가 보이질 않았다. 자세한 내용을 살펴보니, widget view 에 containerBackground modifier를 사용하지 않아서 발생하는 warning 이였다.

👾 containerBackground가 무엇이고, 왜 사용하는지?

warning에 링크 되어있는 문서를 확인해봤다.
문서를 간단히 요약하자면, OS에서 우리가 만든 위젯의 background 색상을 없애거나, 반 투명하게 만들 수 있다고 한다. 따라서 각 위젯은 removable 한 background view 를 갖고 있어야 하므로 containerBackground modifier 가 필요하다고 작성되어 있다.

👔 왜 removable background를 만족해야 할까

잠금 화면에서 Widget이 렌더링 될 경우, OS는 위젯의 대비를 높이기 위해 background를 제거하거나, content에 맞춰 반 투명하게 만들 수 있다. 여기서 OS는 해당 위젯의 영역이 어디 까지인지 알아야 하기 때문에 containerBackground 를 통해 위젯의 영역을 알려준다.

wwdc 2023 관련 영상에도 해당 주제가 짧게 언급되니, 시청하면 좋을 것 같다. video 링크 에서 2:57초 부터 확인하면 된다.

🧤 containerBackground Modifier 추가

extension View {
    func widgetBackground(_ backgroundView: some View) -> some View {
        if #available(iOSApplicationExtension 17.0, *) {
            return containerBackground(for: .widget) {
                backgroundView
            }
        } else {
            return background(backgroundView)
        }
    }
}

// ...view.swift
VStack {
    ...
}
.widgetBackground(Color.white)

containerBackground 는 문서에 나와있는 것 처럼 iOS17버전 이상에만 사용 가능하다. 따라서 이전 버전의 위젯과 분기를 시켜줘야 한다. View extension 을 통해 사용하는 방식이 제일 사용성이 좋아보이기에 위 방식을 사용하였다.

참고

• https://www.optimistic-closures.com/adjusting-your-widgets-containerbackground/
• https://developer.apple.com/documentation/widgetkit/preparing-widgets-for-additional-contexts-and-appearances#Change-the-widget-background
• https://developer.apple.com/documentation/SwiftUI/View/containerBackground(_:for:)
• https://developer.apple.com/videos/play/wwdc2023/10027/