[Swift] available を指定して、使用開始・非推奨・廃止 情報を付与する

     
⌛️ 2 min.
Swift の言語機能として用意されている @available を使って、API を更新していく方法を再確認します。

環境&対象

以下の環境で動作確認を行なっています。

  • macOS14.1
  • Xcode 15.0.1
  • iOS 17
  • Swift 5.9

@available

Swift には、@available という attribute が用意されています。

対象要素が 使用できる条件を付与することができます。

例えば、以下のような情報を付与できます。
・関数 A は、macOS 12.0 以降でのみ利用可能
・関数 B は、macOS 14.0 以降では、使用不可
・関数 C は、macOS 13.1 では、非推奨

追加情報として、以下を追加できます。
・置き換え先
・任意 メッセージ

以降では順番に記述方法を確認していきます。

新規導入(introduced)を明示する available

以下のように記述することで、どのバージョンから利用可能になったかを明示することができます。

@available(macOS, introduced: 12.0)
func testFunc12() -> Int {
  return 0
}

上記は、testFunc12 という関数が、macOS 12.0 以降で利用可能になっていることを意味します。

compileOKatmacOS12

同じコードを macOS 11.x 向けにコンパイルしようとすると、testFunc12 を使用している行が、以下のようなエラーになります。
`testFunc12()` is only available in macOS12 or newer

つまり、定義部分は、macOS11 向けにコンパイルしてもエラーになりませんが、利用しようとするとエラーになるということです。

onlyAvailablerOrNewer

introduced の簡易記述

@available(#platform name#, introduced: #version number# ) は、簡易化して書くことができるようになっています。

先ほどの記述は以下のように記述するのと同じ意味を持ちます。

@available(macOS 12.0, *)
func testFunc12() -> Int {
  return 0
}

廃止予定(obsoleted) を明示する available

特定のバージョン以降で利用不可になる API というのも よく(?) あります。
以下のように記述します。

先ほどの testFunc12 が macOS 13 では、利用できなくなったとすると、以下のように記述します。

@available(macOS, introduced: 12, obsoleted: 13)
func testFunc12() -> Int {
    return 0
}

testFunc12という関数は、macOS12 で導入され、macOS13 で廃止になった(利用不可になった) という意味になります。

macOS 12.x 向けにコンパイルする時には、エラーになりませんが、macOS13 向けにコンパイルしようとすると、testFunc12 を使用している行が、以下のようなエラーになります。
`testFunc12()` is unavailable in macOS

obsoleted_unavailable

代替関数 renamed

単純に使用不可になるのではなく、別途 新規関数が用意されるケースもあります。
その関数を使用するように切り替えてくれというケースです。

そのような時にヒントを表示できるように renamed という指定ができるようになっています。

@available(macOS, introduced: 12, obsoleted: 13, renamed: "testFunc13")
func testFunc12() -> Int {
    return 0
}

以下のような表示がされ、示唆的なメッセージが表示されます。”Fix It” を使うと、自動で修正もしてくれます。

ObsoletedRenamed

非推奨(deprecated) を明示する available

関数が、使用不可になるのではなく、使用することが推奨されないというパターンもあります。
そのような時には、obsoleted ではなく、deprecated 指定を使用します。

@available(macOS, introduced: 12, deprecated: 13, renamed: "testFunc13")
func testFunc12() -> Int {
    return 0
}

上記のように指定すると、使用箇所ではエラーではなく、ワーニングが表示されます。

renamed が指定されているとそのようなメッセージが表示されるのは、obsoleted と同じです。

deprecatedRenamed

メッセージ追記

renamed を使用することで、代替要素の名称を指定することができましたが、一般的なメッセージを表示させることもできます。

@available(macOS, introduced: 12, deprecated: 13, message: "say Hello")
func testFunc12() -> Int {
    return 0
}

以下のように エラー/ワーニングメッセージに追記されます。

message

@available 追記

上記のサンプルでは macOS を指定して試していましたが、platform/ version としては、以下のように指定可能な範囲が設定されています。

platform 指定対象

platform としては、以下を指定できます。
・iOS
・iOSApplicationExtension
・macOS
・macOSApplicationExtension
・macCatalyst
・macCatalystApplicationExtension
・watchOS
・watchOSApplicationExtension
・tvOS
・tvOSApplicationExtension
・visionOS
・swift

version 指定対象

version としては、. (ピリオド) 区切りの 1 ~ 3 つの数値を指定できます。

例:12.1.1

まとめ

@available の introduced/deprecated/obsoleted を指定して 利用可能対象を明示する方法を確認しました。

@available の使い方
  • @available を付与することで、利用可能対象を明示できる
  • introduced を使用すると、利用可能開始バージョンを指定できる
  • obsoleted を使用すると、廃止されたバージョンを指定できる
  • deprecated を使用すると、非推奨になったバージョンを指定できる
  • renamed を指定すると、簡単に代替要素への乗り換えをサポートできる
  • message を使用すると、注記事項等を表示できる

説明は以上です。
不明な点やおかしな点ありましたら、こちらまで。

SwiftUI おすすめ本

SwiftUI を理解するには、以下の本がおすすめです。

SwiftUI ViewMatery

SwiftUI で開発していくときに、ViewやLayoutのための適切なmodifierを探すのが大変です。
英語での説明になってしまいますが、以下の”SwiftUI Views Mastery Bundle”という本がビジュアル的に確認して探せるので、便利です。

英語ではありますが、1ページに コードと画面が並んでいるので、非常にわかりやすいです。

View に適用できる modifier もわかりやすく説明されているので、ビューの理解だけではなく、どのような装飾ができるかも簡単にわかります。

超便利です

SwiftUIViewsMastery

販売元のページは、こちらです。

SwiftUI 徹底入門

# SwiftUI は、毎年大きく改善されていますので、少し古くなってしまいましたが、いまでも 定番本です。

Swift学習におすすめの本

詳解Swift

Swift の学習には、詳解 Swift という書籍が、おすすめです。

著者は、Swift の初期から書籍を出していますし、Swift の前に主力言語だった Objective-C という言語についても同様の書籍を出しています。

最新版を購入するのがおすすめです。

現時点では、上記の Swift 5 に対応した第5版が最新版です。

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です