標準小工具版面配置

請先找出核心內容，再設計實用的小工具版面配置。版面配置會決定小工具中資訊和互動元素的排列方式。Android 提供多種預先建構的版面配置，適用於工具列、文字、清單和格線類型的小工具，可簡化這項程序。

文字

文字版面配置最適合用來顯示簡潔資訊。視需要加入圖片和文字，提升小工具的視覺吸引力。

只有文字

適合用於標題、狀態更新、簡短說明，或任何能以單行文字有效傳達訊息的情境。

文字和圖像

加入圖片，增加視覺衝擊力。詳情請參閱「中斷點」，瞭解如何根據不同螢幕大小調整這個版面配置。

工具列

使用工具列版面配置，讓使用者在應用程式中快速存取常用工作，並以彈性版面配置適應各種小工具大小。

搜尋工具列

搜尋工具列版面配置經過精心設計，可將焦點吸引到工具列中的主要動作「搜尋」。其他實用按鈕可讓您快速存取常用功能。

工具列

工具列會顯示應用程式品牌，後面接著最常用工作的按鈕，適合用於可切換的設定或工作連結。調整大小時，系統可能會隱藏較不常用的選項，改為顯示較常用的動作。使用「中斷點」，在有空間時新增最小 48 dp 的可輕觸按鈕。

清單

使用清單版面配置，以清楚且易於瀏覽的格式整理多個項目。這項功能非常適合用於新聞標題、待辦事項清單或訊息。將內容整理成結構化的清單，方便快速瀏覽。根據內容需求，選擇容器化或無容器的呈現方式。

文字和圖片清單

可掃描的文字和圖片清單非常適合展示多種內容類型，例如新聞標題、附有專輯封面的播放清單或訊息。

檢查清單

檢查清單版面配置非常適合用來顯示工作，提供清楚的輕觸目標，讓使用者快速將項目標示為完成。

動作清單

透過動作清單提供直覺式控制項分組，視覺化開/關狀態可立即回饋項目狀態。

全出血圖片

這項版面配置適合在 Android 17 以上版本中展示沉浸式、全出血圖片，並使用貼齊捲動功能，確保每個子項元素與小工具容器的高度完美對齊。

格線

以精簡、靈活且視覺效果豐富的格狀版面呈現圖片，並可選擇是否加上標籤。使用可配合不同螢幕大小調整的欄和列。

僅限圖片

使用純圖片格狀檢視，建立視覺效果強烈、可捲動的圖片庫。資料列和資料欄會自動配合各種螢幕大小調整，以最佳方式呈現。

圖片和文字

您也可以加入文字標籤和說明，為圖片格狀檢視內容提供更多背景資訊。

程式碼範例

下表將每個標準版面配置對應至 Android Platform Samples GitHub 存放區中相應的 Jetpack Glance 實作項目。

標準版面配置 參考檔案 指引
動作清單版面配置
  • 使用 Glance 動作回呼處理清單項目動作，並確保狀態正確更新。
檢查清單版面配置
  • 使用動作參數或回呼切換核取方塊狀態，以更新集合項目。
  • 針對小工具 `onClick` 參數，使用 Glance 動作回呼，例如 `actionRunCallback`、`ActionCallback(actionParametersOf(...))` 或 `actionStartActivity(...)`，處理輕觸核取方塊等點擊事件。
生動工具列版面配置
  • 避免 `ColorProvider` 匯入錯誤：匯入 `androidx.glance.unit.ColorProvider`，並使用 `androidx.glance.color.ColorProvider(dayColor, nightColor)`。
  • 直接使用 `GlanceModifier.background(Color)` 設定純色背景，而非 `ColorProvider`。
圖片格線版面配置
  • 除非已設定或要求圖片載入程式庫，否則請使用純色 (`GlanceModifier.background`) 或圖片項目的本機可繪項目。
圖片文字清單版面配置
  • 常見用途：新聞動態消息、文章清單、健身記錄、訊息動態消息和垂直縮圖清單。
  • 結合縮圖與主要/次要文字時，請平衡清單列高度和文字裁剪。
長文字版面配置
  • 如要乘以 `Dp` 值 (例如 `2 * padding`)，請匯入 `androidx.compose.ui.unit.times`。
  • 遵循大小規則：確保使用 `dimens.xml` 中的維度調整邊框間距和字體排版。
搜尋工具列版面配置
  • 避免 `ColorProvider` 匯入錯誤：匯入 `androidx.glance.unit.ColorProvider` 並使用 `androidx.glance.color.ColorProvider(dayColor, nightColor)`。
  • 直接使用 `GlanceModifier.background(Color)` 設定純色背景，而非 ColorProvider。
全出血圖片版面配置 / 貼齊捲動
  • 在 LazyColumn 上設定 `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)`，即可啟用貼齊捲動功能。
  • 如要導入貼齊捲動功能，必須使用 Glance 1.3.0-alpha02 以上版本、編譯 SDK 37 (Baklava) 以上版本，以及 Android Gradle 外掛程式 (AGP) 9.1.0 以上版本。
  • 在小工具供應器類別中，設定 `override val sizeMode: SizeMode = SizeMode.Exact`。
標準工具列版面配置
  • 請參閱「疑難排解」一節，瞭解如何避免 `ColorProvider` 匯入錯誤：使用 `androidx.glance.color.ColorProvider(dayColor, nightColor)`。
  • 直接使用 `GlanceModifier.background(Color)` 設定純色背景，而非 `ColorProvider`。
文字和圖片版面配置
  • 遵循回應式版面配置大小規則，根據可用的小工具尺寸，並排或堆疊顯示文字和圖片。