システム全体にアプリのコントロールを拡張

アプリのコントロールをコントロールセンターやロック画面などに配置する方法を確認しましょう。WidgetKitを使用して、アプリのコントロールをシステムの利用体験に拡張する方法を解説します。コントロールを作成し、デザインをカスタマイズしたり、構成を変更したりする方法も取り上げます。

リソース

関連ビデオ

WWDC24

ロック画面での優れたカメラキャプチャ体験の構築

ダウンロード

こんにちは Cliffです System Experienceチームでエンジニアをしています今日は iOS 18の新しいウィジェットタイプであるコントロールの作成方法についてお話ししますまずコントロールの概要とユーザーがどのように使用するかを説明します次にコントロールの作成方法を紹介しアクションを実行してその状態を維持する方法構成をサポートする方法システムとの統合を改善する方法を説明します

コントロールはアプリの機能をシステムスペースに拡張する新しい方法ですシステムスペースにはコントロールセンターロック画面アクションボタンなどがありますこれらのコントロールは WidgetKitを用いて作成されます iOS 14でWidgetKitが導入され視覚に訴えるカスタムスタイルのコンテンツを詳細情報とともにアプリに表示できるようになりましたウィジェットを利用すれば天気や次のカレンダーイベントを効果的に表示できます iOS 18ではコントロールが追加され WidgetKitをさらに拡張していますコントロールはアプリからのアクションに迅速にアクセスできる優れた方法ですこれらのコントロールはアクションと簡潔な情報にフォーカスしておりフラッシュライトをオンにしたり時計アプリにディープリンクするなどのユースケースに適していますウィジェットの作成方法を知っていればコントロールも同じように作成できます基盤となるアーキテクチャは同じものだからですコントロールには2種類ありますボタンとトグルですボタンはアプリの起動など個別のアクションを実行しますトグルはブール値の状態を変化させます何かのオンとオフを切り替える場合などです

インタラクティブなウィジェットのようにコントロールはApp Intentを使ってアクションを実行します

基本的にコントロールはシステムスペースに目にみえる形で現れるアクションでアプリから提供される情報が使用されます

アプリはシンボルタイトル色合い追加のコンテンツをシステムに提供しますサポートされているシステムスペースにユーザーがコントロールを追加するとそのコントロールが状況に応じてシステムスペースに表示されます

コントロールセンターではコントロールが 3つの異なるサイズで表示されるためタイトルや値のテキストが常に表示されるとは限りません私は仕事中に集中力を維持しながら休憩を取りたい時によくタイマーを使います今日は作業と休憩を区切って実行できる生産性タイマーコントロールを作成しますタイマーが作動中ライブアクティビティで残り時間が表示されます

ロック画面からタイマーを開始し

コントロールセンターで停止し

さらにアクションボタンを使って開始または停止することができます

生産性を高めるこのタイマーコントロールをゼロから構築してみますまずは基本的なトグルから始めてその後コントロールの様々な機能を活用していきます

既存の生産性ウィジェット用の WidgetBundleが既にあるのでまずこのWidgetBundleに TimerToggle()エントリを追加します次にこの同じWidget Extensionで TimerToggle()コントロールを定義します ControlWidgetに準拠した TimerToggleタイプを追加しますコントロールを定義するためコントロールに表示する情報と実行するアクションを提供します

まずは StaticControlConfiguration から始めますこのコントロールは構成可能ではありません構成は後で追加します

このコントロールは一意の識別子としてkindを取りコントロールのタイプの定義として ControlWidgetToggleを取ります

次にコントロールにタイトルを与えてその状態を提供します

コントロールが操作されたときに実行するアクションも記述しますインタラクティブなウィジェットと同様このコントロールもApp Intentを使用してアクションを実行します

最後にコントロールを定義するシンボル画像を指定します

必要な情報がすべて揃ったのでこのコントロールがシステムに表示されるようになります

コントロールセンターにも配置してタイトルシンボルオン／オフ状態を表示できます

このタイマーコントロールはタイマーが作動中または停止中に異なるシンボルを表示することでさらに改善できます

そのためにはクロージャのisOn引数を使用しコントロールがオンのときは砂時計シンボルを表示して時間がカウントダウンされていることを示します

素晴らしいですね！コントロールが作動中のときのみ砂時計が表示されるようになりました

またこの状態の値のテキストもさらに改善したいと思います現在はオンとオフが表示されています

これはトグルのデフォルトの値のテキストですしかし通常タイマーではオン／オフではなく作動中／停止を使用します

コントロールの値のテキストは画像をラベルに変更してカスタマイズできますラベルには値textと systemImageの両方が含まれますこれでデフォルトのオン／オフではなくコントロールの状態を表す適切で関連性のある値のテキストが表示されるようになりました

この値のテキストはコントロールがロック画面上にあるときやコントロールセンターの小さなサイズ内では表示されないことに注意してくださいその場合はシンボルのみが表示されます

このコントロールの方向性は気に入っていますがカラーについてはオン状態ではシンボルがデフォルトのsystemBlueの色合いなので私の生産性アプリのブランドイメージに合いません

デフォルトのsystemBlueではなく特徴的な色をコントロールで使用するには色合いを指定します

生産性アプリの色合いであるパープルを使用しますパープルは生産性を高めます色合いはトグルがオンのときにシンボルに使用されます

こちらはロック画面上で動作するスタイルが適用されたコントロールとアクションボタンの例ですコントロールセンターで動作させるものと同じコードを使用していますコントロールがオンのときシンボルと任意の値のテキストが指定した色合いになりますトグルがどのように状態を表示し管理するかを調べてみましょうここまで TimerManagerクラスを使って現在のタイマーの状態をコントロールに提供してきていますこの例では TimerManagerは私の生産性アプリと同じデータにアクセスする共有グループコンテナでデータを確認し実行状態を同期的に取得しますコントロールの状態やコンテンツが変更されたときにシステムがコントロールをどのようにリロードするのかを見ていきましょう

システムがコントロールをリロードする必要があるとき Widget Extensionプロセス内でコントロールの本体を実行して現在の値を取得しコントロールのコンテンツを生成しますコントロールの値とコンテンツはシステムに渡されコントロールの表示に使用されますつまり Widget Extensionはコントロールの現在の状態とその状態のコンテンツを提供します

システムがコントロールをリロードする原因となるイベントは3種類ありますコントロールアクションが実行された時

アプリがオンデマンドでコントロールのリロードを要求した時プッシュ通知がコントロールを無効にした時です最初のイベントはコントロールアクションの実行時ですユーザーがコントロールを操作するたびにコントロールのApp Intentの perform()関数が返される時点でコントロールが自動的にリロードされますリターンされる前にすべての更新を完了させてください

このタイマーコントロールではアクションはToggleTimerIntent()です

このインテントはタイマーの「作動中」状態を設定しライブアクティビティを開始または停止します

このApp Intentはタイマーの「作動中」状態をシステムが提供する値に設定するため SetValueIntentになりますタイマーのライブアクティビティを変更するため LiveActivityIntentでもあります perform関数が完了するとシステムは新しい状態でコントロールを更新しますタイマーコントロールを操作することが状態を変更する唯一の方法ではありません生産性アプリを開きそこでタイマーを開始／停止することもできますコントロールを最新の状態に維持したいのですが

そのためにはタイマーの状態が変化したとき ControlCenter APIを使ってコントロールをリフレッシュしますタイマーコントロールの種類を指定してリロードするコントロールを指定するのですこれでアプリでタイマーを開始するとコントロールの状態が常に最新の状態に保たれます

コントロールの状態やコンテンツをリフレッシュする必要がある場合はアプリからシステムにコントロールのリロードを要求できますウィジェットやライブアクティビティに利用できるリフレッシュツールはコントロールにも利用できますコントロールを開発しその状態を頻繁にリフレッシュする際はでを有効にしてシステムポリシーをコントロールから削除しますこのデバイスでは生産性タイマーがうまく作動していますこれを複数のデバイスで作動させすべてのデバイスがサーバ上の同じタイマー状態にアクセスできるようにしたいと思います

このコントロールはデバイスで利用できないサーバの状態を反映するためタイマーの状態を非同期で取得する必要がありますそのためには ValueProviderを使用できます

ControlValueProviderには 2つの要件があります currentValue()とpreviewValueです

currentValue()は非同期であり必要なデータを取得する際はデータベースやサーバからデータを取得できますこの場合 TimerManagerはサーバから非同期でタイマー状態をクエリします

状態を処理できなかった場合はそれを知らせるエラーをスローし後でコントロールをリロードする必要があることを通知できます

previewValueではコントロールが追加される前ユーザーがプレビューしたときに表示する値を選択します例えばコントロールギャラリーロック画面のカスタマイズ時アクションボタンの設定などで使用します previewValueは事前に決定しておき極めて短時間で戻る必要がありますまたコントロールのオフ状態に対応する値を使用する必要があります

ValueProviderを取る別のコントロールイニシャライザでこのValueProviderを使用でき提供された値がトグルを定義するクロージャに渡されますここではその値をコントロールのisOn状態として使用しますこの例では単純なブールを値として使用していますが値にさらに多くの情報を含めることもできますその例は後で紹介しますシステムがValueProviderを使用してコントロールをリロードするとき最初にValueProviderを実行して現在の値を取得しその値をコントロールクロージャに渡してコンテンツを生成しますこれらすべては Widget Extensionプロセスで行われます

これで生産性タイマーの状態がサーバに保存され様々なデバイスから変更できます例えば iPadからタイマーを開始または停止した場合このデバイス外の状態変更が他のデバイス上のコントロールのリロードをトリガするようにしたいとしますその場合は Push Notification APIを使用してコントロールのpushハンドラを定義し外部状態変更のプッシュ通知を受信したときにコントロールがリロードされるように構成しますプッシュ通知の取り扱いに関するドキュメントにはこれを行う方法とベストプラクティスの詳細が記載されています

これで iPadでタイマーを停止すると iPhone上のコントロールも停止するようになりました

私の生産性タイマーは順調に動作していますが仕事とプライベートで別々のタイマーを用意したいと思います例えばバイオリンの練習などですアプリでそれぞれを個別に追跡できるようにしたいと思いますそれぞれのタイマー用に異なるコントロールを用意し両方をコントロールセンターに配置できるといいですね WidgetKitを使用してウィジェットと同じようにコントロールを作成できるためコントロールを構成可能にすることでこれを実現できますコントロールセンターにタイマーコントロールを1つ追加した後仕事用またはプライベート用のどちらを開始／停止するかを選択できるようにしましょうそれでコントロールセンターに仕事用とプライベート用のタイマーコントロールをそれぞれ配置できますまず ValueProviderを新しいプロトコルに準拠するように更新できます AppIntentControlValueProviderですこれで値がインテントの設定に依存するようになります構成を決めるApp Intentは SelectTimerIntentですコントロールを操作するタイマーをユーザーが選択できます構成の特定のタイマーの作動状態が確実に取得されるようにして返す値はタイマーとその作動状態を含むカスタム構造体になります

ConfigurableValueProviderを使用して AppIntentControlConfiguration()でコントロールを構成可能にしますこのクロージャに渡される値は timerState構造体ですトグルを完了するためにそのタイマーと作動状態を使用します特定のタイマーの名前をコントロールのタイトルとして表示したいと思いますまたトグルタイマーのApp Intentはその特定のタイマーに対して動作します

次にユーザーがコントロールセンターをカスタマイズするときこのコントロールでどのタイマーを操作するか選べるようにしますここではコントロールセンターに並べて配置した仕事用とプライベート用のタイマーコントロールが各タイマーをコントロールしています

コントロールを機能させるために構成が必要な場合 promptsForUserConfiguration() モディファイアを使用してシステムがコントロールをシステムスペースに追加した際に構成を促すプロンプトを自動的に表示するようにできます

コントロールをさらに洗練させてシステムのデフォルト値がユースケースに合わない場合に最も理解しやすく関連性のあるコンテンツを提供できます例えばアクションが実行される前にユーザーがアクションボタンを操作するとアクションのヒントが表示されます現在のアクションヒントはとです

なぜそうなっているのかを詳しく見てみましょう

コントロールの値ラベルをかにカスタマイズする前はデフォルトのオン／オフの値のテキストの生成と同じようにとというアクションヒントが生成されていました値のテキストをカスタマイズした際それがアクションヒントの生成にも使われましたシステムでとが生成されましたこれらは確実に改善できますそこでこれをユースケースに合わせてカスタマイズします

controlWidgetActionHintモディファイアを使用してアクションボタンのヒントテキストをカスタマイズしアクションヒントを選びますこれは動詞で始める必要があります提供されたヒントは特定の状態に遷移するアクションですタイマーがオン状態でのアクションヒントはつまりタイマーを開始するヒントはですオフ状態のアクションヒントはつまりタイマーを停止するヒントはです素晴らしいですねタイマーとして自然に感じられます

controlWidgetStatusモディファイアを使用してアクションが実行されたときコントロールセンターに一時的なステータスを表示できますコントロールのアクションに関する追加情報その状態またはその状態の有効期間を伝える場合ステータスの追加をお勧めしますステータステキストは慎重に使用し注意を引くためにコントロールでまだ伝えていない関連情報にのみ使用してください

コントロールギャラリーからコントロールを追加すると現在の名前はこれは私のアプリの名前です

コントロールのアプリ名がコントロールのデフォルト表示名です

コントロールの表示名をにカスタマイズします各コントロールに必ず特定の displayNameを選択してください機能に応じて異なります最後の仕上げとして説明も追加しますコントロールの構成中に表示されるものですわずか数ステップでコントロールセンターロック画面アクションボタンに配置できすべてのデバイスで同期する生産性タイマーコントロールを作成しましたコントロールはパワフルな機能です iOSおよびiPadOS 18のアプリに組み込むことでシステムスペースでアプリの主要アクションに素早くアクセスすることができますここで説明したモディファイアを使用してコントロールのスタイルをアクションに合わせて調整しコントロールに特徴的なシンボルが備わっていることを確認してください

カメラでコンテンツをキャプチャできるコントロールを作成する場合はキャプチャ拡張の作成に関するセッション「Build a great Lock Screen camera capture experience」をご覧ください

ご視聴ありがとうございました

3:13 - Add the control to the Widget Bundle

@main
struct ProductivityExtensionBundle: WidgetBundle {
    
    var body: some Widget {
        ChecklistWidget()
        TaskCounterWidget()
        TimerToggle()
    }
    
}

3:29 - Complete the control

struct TimerToggle: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(
            kind: "com.apple.Productivity.TimerToggle"
        ) {
            ControlWidgetToggle(
                "Work Timer",
                isOn: TimerManager.shared.isRunning,
                action: ToggleTimerIntent()
            ) { _ in
                Image(systemName:
                      "hourglass.bottomhalf.filled")
            }
        }
    }
}

4:41 - Specify different symbols when on and off

struct TimerToggle: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(
            kind: "com.apple.Productivity.TimerToggle"
        ) {
            ControlWidgetToggle(
                "Work Timer",
                isOn: TimerManager.shared.isRunning,
                action: ToggleTimerIntent()
            ) { isOn in
                Image(systemName: isOn
                      ? "hourglass"
                      : "hourglass.bottomhalf.filled")
            }
        }
    }
}

5:21 - Specify custom value text and add a custom tint color

struct TimerToggle: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(
            kind: "com.apple.Productivity.TimerToggle"
        ) {
            ControlWidgetToggle(
                "Work Timer",
                isOn: TimerManager.shared.isRunning,
                action: ToggleTimerIntent()
            ) { isOn in
                Label(isOn ? "Running" : "Stopped",
                      systemImage: isOn
                      ? "hourglass"
                      : "hourglass.bottomhalf.filled")
            }
            .tint(.purple)
        }
    }
}

8:14 - Implement timer toggling

struct ToggleTimerIntent: SetValueIntent, LiveActivityIntent {
    static let title: LocalizedStringResource = "Productivity Timer"
    
    @Parameter(title: "Running")
    var value: Bool  // The timer’s running state
    
    func perform() throws -> some IntentResult {
        TimerManager.shared.setTimerRunning(value)
        return .result()
    }
}

8:54 - Refresh the control from within the app

func timerManager(_ manager: TimerManager,
                  timerDidChange timer: ProductivityTimer) {
    ControlCenter.shared.reloadControls(
        ofKind: "com.apple.Productivity.TimerToggle"
    )
}

10:03 - Define a Value Provider

struct TimerValueProvider: ControlValueProvider {
    
    func currentValue() async throws -> Bool {
        try await TimerManager.shared.fetchRunningState()
    }
    
    let previewValue: Bool = false
}

11:00 - Provide asynchronously fetched state with a Value Provider

struct TimerToggle: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(
            kind: "com.apple.Productivity.TimerToggle",
            provider: TimerValueProvider()
        ) { isRunning in
            ControlWidgetToggle(
                "Work Timer",
                isOn: isRunning,
                action: ToggleTimerIntent()
            ) { isOn in
                Label(isOn ? "Running" : "Stopped",
                      systemImage: isOn
                      ? "hourglass"
                      : "hourglass.bottomhalf.filled")
            }
            .tint(.purple)
        }
    }
}

13:06 - Make the Value Provider configurable

struct ConfigurableTimerValueProvider: AppIntentControlValueProvider {
    func currentValue(configuration: SelectTimerIntent) async throws -> TimerState {
        let timer = configuration.timer
        let isRunning = try await TimerManager.shared.fetchTimerRunning(timer: timer)
        return TimerState(timer: timer, isRunning: isRunning)
    }
    
    func previewValue(configuration: SelectTimerIntent) -> TimerState {
        return TimerState(timer: configuration.timer, isRunning: false)
    }
}

13:40 - Make the timer configurable

struct TimerToggle: ControlWidget {
    var body: some ControlWidgetConfiguration {
        AppIntentControlConfiguration(
            kind: "com.apple.Productivity.TimerToggle",
            provider: ConfigurableTimerValueProvider()
        ) { timerState in
            ControlWidgetToggle(
                timerState.timer.name,
                isOn: timerState.isRunning,
                action: ToggleTimerIntent(timer: timerState.timer)
            ) { isOn in
                Label(isOn ? "Running" : "Stopped",
                      systemImage: isOn
                      ? "hourglass"
                      : "hourglass.bottomhalf.filled")
            }
            .tint(.purple)
        }
    }
}

14:26 - Prompt for user configuration automatically

struct SomeControl: ControlWidget {
    var body: some ControlWidgetConfiguration {
        AppIntentControlConfiguration(
            // ...
        )
        .promptsForUserConfiguration()
    }
}

15:42 - Custom action hint -> hint treated as verb phrase

struct TimerToggle: ControlWidget {
    var body: some ControlWidgetConfiguration {
        AppIntentControlConfiguration(
            kind: "com.apple.Productivity.TimerToggle",
            provider: ConfigurableTimerValueProvider()
        ) { timerState in
            ControlWidgetToggle(
                timerState.timer.name,
                isOn: timerState.isRunning,
                action: ToggleTimerIntent(timer: timerState.timer)
            ) { isOn in
                Label(isOn ? "Running" : "Stopped",
                      systemImage: isOn
                      ? "hourglass"
                      : "hourglass.bottomhalf.filled")
                .controlWidgetActionHint(isOn ?
                                         "Start" : "Stop")
            }
            .tint(.purple)
        }
    }
}

16:56 - Specify a display name and add a description

struct TimerToggle: ControlWidget {
    var body: some ControlWidgetConfiguration {
        AppIntentControlConfiguration(
            kind: "com.apple.Productivity.TimerToggle",
            provider: ConfigurableTimerValueProvider()
        ) { timerState in
            ControlWidgetToggle(
                timerState.timer.name,
                isOn: timerState.isRunning,
                action: ToggleTimerIntent(timer: timerState.timer)
            ) { isOn in
                Label(isOn ? "Running" : "Stopped",
                      systemImage: isOn
                      ? "hourglass"
                      : "hourglass.bottomhalf.filled")
                .controlWidgetActionHint(isOn ?
                                         "Start" : "Stop")
            }
            .tint(.purple)
        }
        .displayName("Productivity Timer")
        .description("Start and stop a productivity timer.")
    }
}

特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。

システム全体にアプリのコントロールを拡張

関連する章

リソース

関連ビデオ

WWDC24