glance-canonical-layouts

推奨されるデザインパターンに従うウィジェットの Canonical Layout を実装するには、次の手順に従います。

1. プロジェクトでは Jetpack Glance を必ず使用してください。
2. Canonical Layout Reference Files の一覧から、指定されたレイアウトを必ず見つけてください。
3. レイアウトのリファレンスファイルを、プロジェクトの対象アプリモジュール（例：src/main/java/ および src/main/res/）に一度にコピーして、デザインをそのまま実装し、ツール呼び出しの回数を減らしてください。
4. ウィジェットのプロバイダークラスに override val sizeMode: SizeMode = SizeMode.Exact を必ず設定してください。
5. プロジェクトをビルドできることを確認し、サンプルのパッケージ宣言、インポートパス、クラス名を対象アプリのパッケージ名に合わせて更新してください。
6. プロジェクトのウィジェットコードを整理し、使用されていないクラス（例：未使用のボタン）を削除してください。
7. ウィジェットレシーバーを AndroidManifest.xml の <application> 内で <activity> の後に必ず登録し、android:resource="@xml/..." がコピーした Widget Info XML のファイル名と一致するようにしてください。一致しない場合、ウィジェットはウィジェット選択画面に表示されません。

<receiver android:name=".glance.MyReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data
        android:name="android.appwidget.provider"
        android:resource="@xml/my_app_widget_info" />
</receiver>

依存関係

アプリモジュールの build.gradle.kts の dependencies ブロックに、Jetpack Glance の依存関係を追加してください。

• androidx.glance:glance-appwidget:1.2.0 以上
• androidx.glance:glance-material3:1.2.0 以上
• androidx.glance:glance-appwidget-preview:1.2.0 以上
• androidx.glance:glance-preview:1.2.0 以上

Snap Scrolling を実装する場合は、compileSdk = 37 および Android Gradle Plugin（AGP）9.1.0 以上（例：gradle/libs.versions.toml の agp = "9.1.0"）と組み合わせて、1.3.0-alpha02 以上を使用してください。

Coil でビットマップを読み込むサンプルデータリポジトリ（FakeImageGridDataRepository.kt、FakeImageTextListDataRepository.kt、FakeTextWithImageRepository.kt など）をコピーする場合は、まだ追加されていなければ、io.coil-kt:coil などの画像読み込みライブラリの依存関係も追加してください（例：implementation("io.coil-kt:coil:2.7.0")）。

Canonical layout のリファレンスファイル

アクションリストレイアウト（action_list）

• ウィジェットプロバイダー： ActionListAppWidget.kt
• レイアウトのComposable： ActionListLayout.kt
• ウィジェット情報XML： sample_action_list_widget_info.xml
• データリポジトリ： FakeActionListDataRepository.kt
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_action_list_preview.png, sample_home_icon.xml, sample_power_settings_icon.xml, sample_bulb_icon.xml, sample_thermostat_icon.xml, sample_ac_icon.xml, sample_door_icon.xml, sample_arrow_right_icon.xml, sample_no_data_icon.xml, sample_add_icon.xml
• コンポーネント： RoundedScrollingLazyVerticalGrid.kt, ListItem.kt, VerticalListItem.kt, RoundedScrollingLazyColumn.kt, EmptyListContent.kt, NoDataContent.kt
• ユーティリティ： CollectionsKtx.kt, ActionUtils.kt, PreviewAnnotations.kt
• テーマ： Color.kt, Theme.kt, Type.kt
• 追加のリファレンス： CanonicalLayoutActivity.kt, ActionDemonstrationActivity.kt
• ガイダンス：
  • Glance のアクションコールバックでリスト項目のアクションを処理し、状態が適切に更新されるようにします。

チェックリストレイアウト（check_list）

• ウィジェットプロバイダー：CheckListAppWidget.kt
• レイアウトコンポーザブル：CheckListLayout.kt
• ウィジェット情報 XML：sample_check_list_widget_info.xml
• データリポジトリ：FakeCheckListDataRepository.kt
• 寸法：dimens.xml
• 文字列：strings.xml
• ドローアブル：sample_check_list_preview.png, sample_pin_icon.xml, sample_checked_circle_icon.xml, sample_circle_icon.xml, sample_delete_icon.xml, sample_edit_icon.xml, sample_snooze_icon.xml, sample_no_data_icon.xml, sample_add_icon.xml
• コンポーネント：ListItem.kt, VerticalListItem.kt, RoundedScrollingLazyColumn.kt, EmptyListContent.kt, NoDataContent.kt
• ユーティリティ：CollectionsKtx.kt, ActionUtils.kt, PreviewAnnotations.kt
• テーマ：Color.kt, Theme.kt, Type.kt
• ガイダンス：
  • アクションパラメーターまたはコールバックを使用してコレクションアイテムを更新し、チェックボックスの状態を切り替える処理を実装します。
  • チェックボックスのタップなどのクリックイベントを処理するため、ウィジェットの onClick パラメーターには Glance Action コールバック（たとえば、actionRunCallback、ActionCallback(actionParametersOf(...)、または actionStartActivity(...)）を使用します。

表現力豊かなツールバーのレイアウト（expressive_toolbar）

• ウィジェットプロバイダー： ExpressiveToolbarAppWidget.kt
• レイアウト Composable： ExpressiveToolbarLayout.kt
• ウィジェット情報 XML： sample_expressive_toolbar_widget_info.xml
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_expressive_toolbar_preview.png, four_side_cookie_background.xml, sample_edit_icon.xml, sample_share_icon.xml, sample_delete_icon.xml, sample_info_icon.xml, sample_add_icon.xml, sample_file_upload_icon.xml, sample_mic_icon.xml, sample_camera_icon.xml
• コンポーネント： Buttons.kt, LayoutComponents.kt
• ユーティリティ： ActionUtils.kt, PreviewAnnotations.kt
• テーマ： Color.kt, Theme.kt, Type.kt
• ガイダンス：
  • ColorProvider のインポートエラーを避けるには、androidx.glance.unit.ColorProvider をインポートし、androidx.glance.color.ColorProvider(dayColor, nightColor) を使用してください。
  • 単色の背景には ColorProvider ではなく、GlanceModifier.background(Color) を直接使用してください。

画像グリッドレイアウト（image_grid）

• ウィジェットプロバイダー： ImageGridAppWidget.kt
• レイアウトコンポーザブル： ImageGridLayout.kt
• ウィジェット情報 XML： sample_image_grid_widget_info.xml
• データリポジトリ： FakeImageGridDataRepository.kt
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_image_grid_preview.png、sample_placeholder_image.png、sample_grid_icon.xml、sample_refresh_icon.xml、sample_no_data_icon.xml、sample_add_icon.xml
• コンポーネント： RoundedScrollingLazyVerticalGrid.kt、EmptyListContent.kt、NoDataContent.kt、VerticalListItem.kt
• ユーティリティ： CollectionsKtx.kt、ImageUtils.kt、ImageAspectRatio.kt、PreviewAnnotations.kt
• テーマ： Color.kt、Theme.kt、Type.kt
• ガイダンス：
  • 画像項目には、画像読み込みライブラリが設定されている場合または指定されている場合を除き、単色（GlanceModifier.background）またはローカルのドローアブルを使用してください。

画像テキストリストレイアウト（image_text_list）

• ウィジェットプロバイダー： ImageTextListAppWidget.kt
• レイアウトコンポーザブル： ImageTextListLayout.kt
• ウィジェット情報 XML： sample_image_text_list_widget_info.xml
• データリポジトリ： FakeImageTextListDataRepository.kt
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_image_text_list_preview.png, sample_placeholder_image.png, sample_image_icon.xml, sample_heart_icon.xml, sample_refresh_icon.xml, sample_no_data_icon.xml, sample_add_icon.xml
• コンポーネント： ListItem.kt, VerticalListItem.kt, RoundedScrollingLazyColumn.kt, EmptyListContent.kt, NoDataContent.kt
• ユーティリティ： CollectionsKtx.kt, ImageUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
• テーマ： Color.kt, Theme.kt, Type.kt
• ガイダンス：
  • 一般的なユースケース：ニュースフィード、記事リスト、ワークアウト履歴、メッセージフィード、縦型サムネイルリスト。
  • サムネイル画像と主テキストおよび副テキストを組み合わせる場合は、リスト行の高さとテキストのクリッピングのバランスを取ります。

長文テキストレイアウト（long_text）

• ウィジェットプロバイダー： LongTextAppWidget.kt
• レイアウトコンポーザブル： LongTextLayout.kt
• ウィジェット情報 XML： sample_long_text_widget_info.xml
• データリポジトリ： FakeLongTextRespository.kt
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_long_text_preview.png, sample_text_icon.xml, sample_refresh_icon.xml
• ユーティリティ： FontUtils.kt, PreviewAnnotations.kt
• テーマ： Color.kt, Theme.kt, Type.kt
• ガイダンス：
  • Dp を乗算する場合（例：2 * padding）は、androidx.compose.ui.unit.times をインポートします。
  • サイズ設定のルールに従い、パディングとタイポグラフィのスケーリングには dimens.xml の寸法を使用してください。

検索ツールバーのレイアウト（search_toolbar）

• ウィジェットプロバイダー： SearchToolBarAppWidget.kt
• レイアウトコンポーザブル： SearchToolBarLayout.kt
• ウィジェット情報 XML： sample_search_toolbar_widget_info.xml
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_search_toolbar_preview.png, sample_search_icon.xml, sample_refresh_icon.xml, sample_mic_icon.xml, sample_camera_icon.xml, sample_delete_icon.xml, sample_add_icon.xml, sample_pin_icon.xml
• コンポーネント： Buttons.kt, LayoutComponents.kt
• ユーティリティ： ActionUtils.kt, PreviewAnnotations.kt
• テーマ： Color.kt, Theme.kt, Type.kt
• ガイダンス：
  • ColorProvider のインポートエラーを避けるには、androidx.glance.unit.ColorProvider をインポートし、androidx.glance.color.ColorProvider(dayColor, nightColor) を使用します。
  • 単色の背景色には ColorProvider ではなく、GlanceModifier.background(Color) を直接使用します。

全面画像レイアウトとスナップスクロール（snap_scrolling）

• ウィジェットプロバイダー： FullBleedImageAppWidget.kt
• レイアウトコンポーザブル： FullBleedImageLayout.kt
• ウィジェット情報 XML： sample_full_bleed_image_widget_info.xml
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_full_bleed_image_preview.png, sample_scrim_gradient.xml, sample_placeholder_image.png, sample_app_logo.xml, sample_info_icon.xml, sample_no_data_icon.xml
• ユーティリティ： FontUtils.kt, ImageAspectRatio.kt, PreviewAnnotations.kt
• テーマ： Color.kt, Theme.kt, Type.kt
• ガイダンス：
  • スナップスクロールを有効にするには、LazyColumn に verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height) を設定します。
  • スナップスクロールを実装するには、Glance 1.3.0-alpha02 以降、Compile SDK 37（Baklava）以降、および Android Gradle Plugin（AGP）9.1.0 以降が必要です。
  • ウィジェットプロバイダークラスで override val sizeMode: SizeMode = SizeMode.Exact を設定します。

標準ツールバーのレイアウト（standard_toolbar）

• ウィジェットプロバイダー： ToolBarAppWidget.kt
• レイアウトコンポーザブル： ToolBarLayout.kt
• ウィジェット情報 XML： sample_toolbar_widget_info.xml
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_toolbar_preview.png、sample_app_logo.xml、sample_search_icon.xml、sample_add_icon.xml、sample_edit_icon.xml、sample_share_icon.xml、sample_mic_icon.xml、sample_camera_icon.xml、sample_videocam_icon.xml
• コンポーネント： Buttons.kt、LayoutComponents.kt
• ユーティリティ： ActionUtils.kt、PreviewAnnotations.kt
• テーマ： Color.kt、Theme.kt、Type.kt
• 追加のリファレンス： CanonicalLayoutActivity.kt
• ガイダンス：
  • ColorProvider のインポートエラーを回避するには、「トラブルシューティング」を参照してください。androidx.glance.color.ColorProvider(dayColor, nightColor) を使用します。
  • 単色の背景色には ColorProvider ではなく、GlanceModifier.background(Color) を直接使用します。

画像付きテキストのレイアウト（text_with_image）

• ウィジェットプロバイダー： TextWithImageAppWidget.kt
• レイアウトコンポーザブル： TextWithImageLayout.kt
• ウィジェット情報 XML： sample_text_with_image_widget_info.xml
• データリポジトリ： FakeTextWithImageRepository.kt
• 寸法： dimens.xml
• 文字列： strings.xml
• ドローアブル： sample_text_image_preview.png、sample_text_icon.xml、sample_refresh_icon.xml、sample_placeholder_image.png、sample_info_icon.xml、sample_no_data_icon.xml
• ユーティリティ： FontUtils.kt、ImageAspectRatio.kt、PreviewAnnotations.kt
• テーマ： Color.kt、Theme.kt、Type.kt
• ガイダンス：
  • 利用可能なウィジェットの寸法に応じて、テキストと画像を横並びまたは縦積みにできるよう、レスポンシブなレイアウトのサイズ設定ルールに従ってください。

トラブルシューティング

1. 背景色：単色の背景色には、ColorProvider ではなく GlanceModifier.background(Color) を直接使用してください。そうしないと、背景が透明になります。
2. ColorProvider を使用する場合（背景以外）、インポートエラーを避けるには：
   1. 型をインポートします：import androidx.glance.unit.ColorProvider
   2. 完全修飾された生成関数を使用します：androidx.glance.color.ColorProvider(dayColor, nightColor)

チェックリスト

• [ ] ウィジェットを AndroidManifest に登録しましたか？
• [ ] 対応する ウィジェット情報 XML ファイルをコピーし、minWidth、minHeight、minResizeHeight など、指定された値を変更せずに維持しましたか？
• [ ] 対応する レイアウトコンポーザブル ファイルに記載された Glance テーマの色の値を使用しましたか？
• [ ] appwidget-provider の XML 定義で、android:minWidth と android:minHeight にディメンションリソース参照を使用しましたか？
• [ ] ウィジェットのプロバイダークラスで val sizeMode: SizeMode = SizeMode.Exact をオーバーライドしましたか？