標準小工具版面配置

請先找出核心內容，再設計有效的動態小工具版面配置。版面配置決定資訊和互動式元素在小工具中的排列方式。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`。
文字和圖片版面配置
  • 請遵循回應式版面配置大小規則，根據可用的小工具尺寸，並排或堆疊顯示文字和圖片。