visionos-widgetkit-developer

visionOS WidgetKit 開発

クイックスタート

visionOS ウィジェットは、小さな 2D サーフェスではなく、まず空間オブジェクトとして捉えてください。

1. 最初にプラットフォームとファミリーの範囲を決めます。
2. ビジュアルを仕上げる前に、近距離と遠距離の両方のレイアウトを定義します。
3. タイムラインエントリー、共有ストレージ、App Intents を連携の境界として扱い、実行中のホストアプリの状態には依存しないでください。
4. 現在の問題に合ったリファレンスファイルだけを読み込みます。

リファレンスを読み込むタイミング

リファレンス	使用するタイミング
widget-overview.md	Vision Pro ウィジェットの概要、判断ポイント、クイックチェックリストを確認するとき。
families-and-platforms.md	ネイティブの visionOS ファミリー、互換性のある iOS ファミリー、または特大ウィジェットのサポートを選ぶとき。
mounting-styles.md	浮き上がった表示と埋め込み表示のどちらにするかを決め、レイアウトの崩れを避けるとき。
visionos-rendering-styles.md	visionOS ウィジェットの公式なレンダリングモード、背景、ファミリー、テクスチャを確認し、共通のボタン形状ポリシーへの案内を確認するとき。
textures-and-rendering.md	ガラスと紙のどちらを選ぶかを決め、異なるレンダリングモードで読みやすさを確保するとき。
proximity-levelofdetail.md	LevelOfDetail を使って近距離／遠距離のレイアウトを実装するとき。
interactive-widgets.md	ウィジェットに Button、Toggle、または AppIntent による操作を追加するとき。
debugging-and-updates.md	ウィジェットが更新されない、表示されない、古い状態のまま、または壊れているように見えるとき。
widget-animation.md	タイムラインエントリーと Canvas のクロスフェードを使ってウィジェットのコンテンツをアニメーション化するとき、フレームレートを調整するとき、またはバンドルや計算の予算制限に達したとき。

ワークフロー

1. ウィジェットのプラットフォームとファミリー構成を確認します。
2. マウントスタイル、テクスチャ、近距離／遠距離のレイアウト戦略を選びます。
3. データ経路を決めます。タイムラインのみ、App Group／共有ストレージ、バックグラウンド URL セッション、または WidgetKit プッシュ通知から選択します。
4. ウィジェットをひと目で把握できる状態に保てる場合に限り、操作を追加します。
5. 構成が決まったら、タイムライン、再読み込み、レンダリングモード、拡張機能のログを検証します。

ガードレール

• 距離が離れていても読みやすくなるよう、常に .simplified の使用を検討します。
• ネイティブの visionOS ファミリーは意図的に使用します。ネイティブの visionOS 特大ウィジェットには .systemExtraLargePortrait を使用し、互換性のある iOS／iPadOS ウィジェットには .systemExtraLarge を引き続き使用します。
• 明示的にレイアウトを確認せずに、埋め込み表示が機能すると想定しないでください。
• 情報を詰め込みすぎた、コントラストの低いレイアウトは避けてください。
• アプリを開くためのナビゲーションには Link または widgetURL(_:) を使用し、Button と Toggle は実際の AppIntent アクションに使用します。
• 各 WidgetBundle のウィジェット構成は、実用的な上限の範囲内に保ちます。

出力要件

以下を提示してください。

• ウィジェットのプラットフォームとファミリーの範囲
• 使用したリファレンス
• 選択した表示戦略
• 主なレンダリング、操作、またはタイムラインの制約
• 次に行う検証手順