WidgetKitの新機能、Controlを最短で実装する

概要

iOS 18でWidgetKitにControlが新機能として追加されました。
このControlに関しては従来のWidget同様、Widget Extensionで追加するだけでデフォルトでコードが生成され、コントロールセンターやロック画面などのシステムスペースに表示させることができます。ただ初期状態ではControlをタップしても状態が維持されず、何も機能しない状態です。
そこでこの記事では上記まで追加行程と、その後どのように実装すれば既存のアプリに組み込めるか、ヒントになるよう、まずは軽量な実装として状態を維持して、Controlに反映させるといった実装を最短で試す方法を紹介したいと思います。
最終的にはボタンをタップすると状態を切り替えられる以下のようなものが実装できるようになります。

​

環境

iOS 18.0 〜
​

Controlを追加する

まずWidget ExtensionでWidgetを追加します。

追加する際に「Include Control」にチェックを入れます。

​

とりあえずこれだけでシステムスペース（コントロールセンター、ロック画面）にコントロールが表示されるよになります。

画面ではInclude Configuration App Intentにチェックが入っていますが、Include Configuration App Intentに対するチェックの有無でStaticControlConfigurationかAppIntentControlConfigurationによる構成となります。この記事ではStaticControlConfigurationをベースに紹介していますのでご注意ください。

コントロールセンターからコントロールを追加できる様子

追加するとコントロールセンターに表示される

ここまでがアプリにControlを追加する手順です。

タップ状態を保持してControlに反映させる

続いては実装していきます。

基本的な構成

上記の手順によりいくつかのファイルが生成されますが、その中でXXControlというファイルを開くとControlWidgetに準拠したstructが生成さているのでそのファイルを見ていきます。

struct HogeControl: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(
            kind: "Hoge",
            provider: Provider()
        ) { value in
            ControlWidgetToggle(
                "Hoge Timer",
                isOn: value,
                action: StartTimerIntent()
            ) { isRunning in
                Label(isRunning ? "On" : "Off", systemImage: "timer")
            }
        }
        .displayName("Hoge")
        .description("A an example control that runs a timer.")
    }
}

上から順に簡単に説明していきます。

• kind：基本的にはWidgetと同じくControlを識別するための文字列です。

• provider：省略可能な引数で、ControlValueProviderもしくはAppIntentControlValueProviderに準拠したProviderというstructを渡します。 Providerを渡すことでControlが更新された時点でcurrentValueの値が渡されす。その値はvalueとしてクロージャーで渡されます。

• ControlWidgetToggle：Controlの表示にあたるContentです。ControlWidgetではControlWidgetToggleとControlWidgetButtonの2種類があり、どちらかを定義する必要があります。今回はControlWidgetToggleをベースに説明します。

  • 第一引数：Controlで表示される文字列です。コントロールセンターに配置時に2×2で表示した場合に表示される文字列です。
  • 第二引数：トグルの状態です。初期コードではProviderから受け取ったものを反映しています。
  • 第三引数：Controlをタップした時に発火するアクションです。

• ControlWidgetToggleのクロージャにあるLabel：第一引数で表示される文字列の上に表示されるシンボルアイコンと第一引数で表示される文字列の下に表示される文字列です。シンボルアイコンは1×1の表示時にやロック画面にも表示されます。

• displayName：Controlを追加する際に表示される文字列です。

• description：Controlの構成中に表示される文字列です。

実装

初期のコードではcurrentValueがtrueになるのでControlをタップしてもすぐにtrueに戻る状態となっています。
ここをローカルで保持して、状態を変更できるように修正してきます。
まず状態を管理、変更できる当なクラスを作ります。

final class TimerManager {
    static let shared = TimerManager()
    private init() {}

    private(set) var isRunning = false

    func setRunning(_ running: Bool) {
        self.isRunning = running
    }
}

続いてStartTimerIntentのperformで状態を変更する処理を追加します。

func perform() async throws -> some IntentResult {
    TimerManager.shared.setRunning(value)
    return .result()
}

余談ですが、performが処理されるとリロードされ、UIが更新されます。よってperform()は非同期処理を完了させてから終了する必要があるため、すべての処理が完了するのを待機させる必要があり、非同期でサーバからデータを取得するケースでは、エラー処理を行い、値の取得に失敗した際は適切なエラーをスローしておくことが推奨されています。

currentValueで現在の状態を受け取るように修正します。

func currentValue() async throws -> Bool {
    TimerManager.shared.isRunning
}

これでControlをタップする度に状態が変更、保持されます。もう少し見やすく可視化したい方は適当にLabelを修正してください。

Label(isOn ? "On" : "Off", systemImage: isOn ? "gauge.with.needle.fill" : "gauge.with.needle") // コントロールを表示する際のシンボル画像や、タイトル下に表示する文字を定義
    .controlWidgetStatus(isOn ? "ON" : "OFF") // 操作後に一瞬表示されるステータスメッセージ
}
.tint(.green) //Imageの色を変更できる

以上です。

参考

https://developer.apple.com/videos/play/wwdc2024/10157/?time=1017

https://developer.apple.com/documentation/swiftui/controlwidget