배포 타깃을 올리지 않고 SwiftUI API 백포팅하기

핵심 요약

1. iOS 27.1의 `toolbarVerticalBehavior`를 백포팅하면 앱의 배포 타깃을 올리지 않고도 새 API를 호출할 수 있으며, 이전 OS에서는 API를 사용할 수 없을 때의 동작을 직접 정할 수 있다.
2. `Backport` 네임스페이스로 API를 감싸면 백포팅한 호출을 한곳에 모을 수 있지만, 사용 시 `.backport`를 붙여야 한다. 이 접두어는 향후 백포팅 코드를 찾는 데도 쓰인다.
3. 별도 네임스페이스 대신 `ported` 접두어와 `@available`을 사용하면 새 API가 배포 타깃에 포함될 때 컴파일러 경고나 오류로 제거 시점을 알릴 수 있다.

도입

중간 버전에서 새 API가 드물게 추가되지만, iOS 27.1에는 iPhone Duo 관련 API가 포함됐다. 이 글은 프로젝트의 배포 타깃을 높이지 않고 SwiftUI의 `toolbarVerticalBehavior`를 호출하는 두 가지 백포팅 방식을 소개한다. 하나는 `Backport` 타입으로 API를 네임스페이스화하는 방식이고, 다른 하나는 `ported` 접두어와 가용성 어노테이션으로 제거 시점을 표시하는 방식이다.

상세 요약

백포팅할 API

iOS 27.1에는 iPhone Duo 관련 API가 추가됐다. 예제로 든 toolbarVerticalBehavior는 세로 툴바를 비활성화하고 툴바 항목을 표준 가로 상단 또는 하단 바에 유지하는 뷰 모디파이어다. 글에서는 프로젝트의 배포 타깃을 높이지 않고 이 API를 사용하는 방법을 제시한다.

Backport 네임스페이스 사용

먼저 제네릭 타입 Backport<Content>를 만들고, View 확장에 현재 뷰를 감싼 backport 프로퍼티를 둔다. 그러면 백포팅 API를 Backport 타입에 모을 수 있다.

Backport where Content: View에 toolbarVerticalBehavior를 정의하고, 자체 ToolbarVerticalBehavior 열거형에 .automatic과 .disabled 케이스를 둔다. 함수 안에서 #available(anyAppleOS 27.1, *)을 검사해 사용 가능한 버전에서는 해당 SwiftUI API를 호출한다. 이전 버전에서는 원래 콘텐츠를 반환한다.

이 API는 iPhone Duo에서만 의미가 있으므로 이전 버전에서 대체 동작을 구현하지 않는다. 다른 API를 백포팅할 때는 가용성 조건을 충족하지 못하는 버전에 자체 구현을 제공할 수도 있다. 호출부에서는 .backport.toolbarVerticalBehavior(.disabled)처럼 네임스페이스를 명시한다. 이 방식은 백포팅 API를 모아 나중에 찾아 제거하기 쉽지만, 호출할 때마다 .backport를 써야 한다.

ported 접두어와 가용성 어노테이션

대안은 View 확장에 portedToolbarVerticalBehavior를 직접 추가하고, 관련 열거형에도 ported 접두어를 붙이는 것이다. 두 선언에는 @available(iOS, introduced: 26.0, deprecated: 27.1, obsoleted: 28.0, message: "Get rid of ported version")를 지정한다.

함수는 27.1 이상에서 기본 toolbarVerticalBehavior를 호출하고, 그보다 낮은 버전에서는 self를 반환한다. 어노테이션은 새 API를 사용할 수 있는 배포 타깃에 도달했을 때 컴파일러 경고나 오류가 발생하도록 해, 백포팅한 선언을 찾아 제거할 시점을 알려준다. 별도 네임스페이스는 필요 없지만, 백포팅 API를 구분하는 접두어와 가용성 정보를 각 선언에 붙여 관리한다.

적용 기준

두 방식 모두 배포 타깃을 즉시 올리지 않고 새 SwiftUI API를 도입한다. Backport 방식은 백포팅 API를 한곳에 모으고 호출부에서 네임스페이스를 드러낸다. ported 방식은 API별 접두어와 어노테이션으로 제거 시점을 표시한다. iPhone Duo에 맞춘 레이아웃 조정은 iPhone Duo에 맞춰 SwiftUI 앱 레이아웃 조정하기에서도 다룬다.

결론

백포팅은 새 API를 즉시 쓸 수 없는 OS에서 가용성 검사를 감추거나, 새 동작을 모방하는 별도 구현을 제공하는 방식이다. `toolbarVerticalBehavior`는 iPhone Duo에서만 의미가 있으므로 이전 버전에서는 원래 뷰를 그대로 반환한다. API를 모으는 네임스페이스와 향후 제거를 알리는 `@available` 중 코드베이스에서 관리하기 쉬운 방식을 선택하면 된다.