資訊一覽

資訊一覽

  程式碼範例

API 參考資料
androidx.glance

使用 Jetpack Compose 樣式 API 建構遠端介面的版面配置。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2024 年 6 月 12 日	1.1.0	-	-	-

宣告依附元件

如果要為 Glance 新增依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
    // For Glance support
    implementation "androidx.glance:glance:1.1.1"
    // For AppWidgets support
    implementation "androidx.glance:glance-appwidget:1.1.1"

    // For Wear-Tiles support
    implementation "androidx.glance:glance-wear-tiles:1.0.0-alpha05"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.1.0-beta03"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    // For Glance support
    implementation("androidx.glance:glance:1.1.1")
    
    // For AppWidgets support
    implementation("androidx.glance:glance-appwidget:1.1.1")

    // For Wear-Tiles support
    implementation("androidx.glance:glance-wear-tiles:1.0.0-alpha05")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.1.0-beta03"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

1.1 版本

1.1.0 版本

2024 年 6 月 12 日

發布 androidx.glance:glance-*:1.1.0。1.1.0 版包含這些修訂版本。

自 1.0.0 版本以來的重要變更

• 將 Glance 移至 1.1.0 穩定版。

1.1.0-rc01 版本

2024 年 5 月 14 日

發布 androidx.glance:glance-*:1.1.0-rc01。1.1.0-rc01 版包含這些修訂版本。

新功能

• 在 Glance 的預覽註解中新增寬度和高度參數。將 1.1.0 版移至候選版。

API 變更

• 將選用參數新增至 Scaffold。(If753f)。
• 在 Glance @Preview 中新增寬度和高度參數。(Ibabe8)。
• 移除快速 Wear 資訊方塊預覽支援功能。(I3850a)。
• 新增了用於設定 FontStyle 自訂權重值的 API。(I7390a)。
• 重新命名 Viewfinder 的 ImplementationMode 列舉，以更準確地反映基礎實作，並為 TransformationInfo.sourceRotation 新增固定常數 (Ic6149)

修正錯誤

• 修正在回溯相容性模式中導致 ViewGroups 顯示問題的錯誤 (I8de92)

外部貢獻

• 實驗性 SharedTransitionScope 現在是介面，而不是類別。(Iaf856、b/338415048、b/338414702)。

1.1.0-beta02 版本

2024 年 4 月 17 日

發布 androidx.glance:glance-*:1.1.0-beta02。這個版本包含先前版本中缺少的來源 jar。

1.1.0-beta01 版本

2024 年 4 月 3 日

發布 androidx.glance:glance-*:1.1.0-beta01。1.1.0-beta01 版包含這些修訂版本。

1.1.0-alpha01 版

2024 年 2 月 7 日

發布 androidx.glance:glance-*:1.1.0-alpha01。1.1.0-alpha01 版包含以下修訂項目。

新功能

• 不需要 UI Automator 的 Glance 單元測試程式庫。可以直接測試 Glance 程式碼，無須加載檢視畫面。
• 較高層級的元件，可簡化版面配置。
• 新的修飾符和主題選項。
• 新的 API 可用於從組合 runComposition 中取得 RemoteView 資料流

API 變更

• 為 Glance 主題新增 widgetBackground 顏色角色(Ia2ab8)。
• 新增 GlanceAppWidget.runComposition (I6344c、b/298066147)
• 新增 TopBar 元件 (Ibd361)
• 在 clickable 修飾符中新增覆寫值。(Iacecf)。
• 新增用於著色按鈕的 API。到 1.0 艘船艦之前，都屬於實驗性質。(I92523)。
• 新增 runGlanceAppWidgetUnitTest，提供在 GlanceAppWidgetUnitTest 上呼叫方法的範圍 (例如 provideComposable)，提供用於測試的小型獨立可組合項，onNode 可在提供的內容中找到 Glance 可組合項元素。這可讓您為 appWidget 中的個別可組合函式編寫單元測試，以驗證如果輸入特定輸入內容，函式就能輸出想要的一目瞭然元件元素。(I2f682)。
• 在語意中新增 testTag 修飾符，以用於單元測試。(I8f62f)。
• 更新 TitleBar - 文字和圖示個別色調。(Ia0a60)。
• 新增 Scaffold 元件 (I8a736)
• 新增 hasActionRunCallbackClickAction 篩選器和 assertHasActionRunCallbackClickAction 斷言以測試 actionRunCallack。此外，請為動作相關測試篩選器新增額外的簡短變體函式：hasStartActivityClickAction<activityClass>(..)、hasStartServiceAction<receiverClass>(..)、hasSendBroadcastAction<receiverClass>(..)。為相關 assertHasXXX 對應項目新增類似的變體。(Ieca63)。
• 移動未發布的 API。將修飾符從內部變更為公開，但程式庫受到限制 (If2a08)
• 新增 onCompositionError 方法，方便開發人員在發生錯誤時執行程式碼 (I9b56f)
• 新增快速導覽按鈕和 iconbutton API (I0fd6f)
• 新增 isLinearProgressIndicator、isIndeterminateLinearProgressIndicator、isIndeterminateCircularProgressIndicator 篩選器，以便與進度指標相符。額外包含 hasAnyDescendants 篩選器，用於測試節點的子階層中是否含有與特定比對器相符的子系 (Ifd426)
• 新增斷言和篩選器，以測試啟動服務 / 活動或廣播的點擊動作。這也包括測試輸入元素是否已勾選。(I3041c)。

1.0.0 版本

1.0.0-alpha06 版

2024 年 2 月 7 日

發布 androidx.glance:glance-appwidget-preview:1.0.0-alpha06 和 androidx.glance:glance-preview:1.0.0-alpha06。1.0.0-alpha06 版包含此連結所列的修訂項目。

新功能

• 配合主要 Glance 模組更新版本。

1.0.0 版本

2023 年 9 月 6 日

發布 androidx.glance:glance-*:1.0.0。1.0.0 版包含此連結所列的修訂項目。

1.0.0 的主要功能

• 將 Glance 移至穩定版 1.0.0

1.0.0-rc01 版本

2023 年 7 月 26 日

發布 androidx.glance:glance-*:1.0.0-rc01。1.0.0-rc01 版包含以下修訂項目。

將 Glance 移至 rc01，以便支援 1.0.0 穩定版。

新功能

• 為動作 lambda 新增按鍵參數，讓動作叫用更穩定。
• 新增為 startActivity 動作提供 ActvityOptions 的功能。
• 新增對 Android 14 的支援

API 變更

• 為接受 lambda 的所有元素新增選用鍵參數。(Id96c1、b/282445798)
• 支援為 actionStartActivity 設定 ActivityOptions 軟體包的支援功能 (I6a08d)
• 合併了 d,e,f,g-paths 的公開和實驗性 API 檔案 (I03646、b/278769092)
• 不適用，API 檔案變更只是重新排序方法 (I5fa95)
• 新增用於為 GlanceAppWidgetReceiver 要求設定 CoroutineContext 的 API (I0a100)
• 新增了 API，可為 LazyColumn 和 LazyVerticalGrid 提供 ActivityOptions，並用於清單中的所有動作。(Id8d71)。

修正錯誤

• 不適用，API 檔案變更只是重新排序方法 (I5fa95)
• Glance 文字元件樣式示範 (Ie78a4)

1.0.0-beta01 版本

2023 年 5 月 10 日

發布 androidx.glance:glance-*:1.0.0-beta01。1.0.0-beta01 版包含此連結所列的修訂項目。

新功能

• 將程式庫移至 Beta 版。
• 支援使用 GlanceTheme 設定主題，新增 glance-material 和 glance-material3 模組，以支援 Glance 中的 Material 2 和 Material 3 樣式主題。
• 支援 FontFamily 的文字 API。
• 將 GlanceAppWidget 移至 WorkManager 工作階段型更新機制。AppWidgets 的 Glance 使用者現在應覆寫 GlanceAppWidget.provideGlance，而非舊版 Content 方法。正如目前在工作站中進行，因此現在不需要個別工作站，即可載入資源、資料庫或網路項目。

API 變更

• 已為 Button、Checkbox、RadioButton 和 Switch 新增 *Defaults API。此功能與 Jetpack Compose 的模式更加一致。(I94828)。
• 新的 Glance 範本模組 (I94459)
• 正在將 ResourceColorProvider 設為模組內部。破壞性變更。需要原因：ResourceColorProvider 應僅用於動態主題設定，避免部分顏色為動態資源，且部分顏色已完全解析。(Ib0db7)。
• 新增 FontFamily 做為 TextStyle 的選項。(Ic19ba、b/274179837)
• Enum.valueOf 的值參數名稱已變更 (Ia9b89)
• 更多列舉 valueOf 擲回的例外狀況 (I818fe)
• 已更新 GlanceAppWidget，以便使用 provideGlance 做為主要進入點。GlanceAppWidget.Content 現已淘汰 (I202b5)。
• 新增提供圖片色調顏色的選項 (I26192、b/212418562)
• 針對已淘汰的隱藏函式，提供更多傳回類型的「是否可為空值」屬性。(Ibf7b0)。
• 新增 @JvmDefaultWithCompatibility 註解 (I8f206)
• 移除了未使用的 SingleEntityTemplateData.displayHeader。(I7f094)。
• 開始支援使用 lambda 做為回呼 (Ia0bbd)
• 將 DayNightColorProvider 移至 glance 模組 (I1842c、b/256934779)
• 從範本中移除 LocalColorProvider。範本現在會使用 GlanceTheme.colors (Ic15e2)
• 從 Text(style: TextStyle) 中移除是否可為空值 (I7123b、b/237012816)
• 預設文字顏色為黑色。移除是否可為空值 (I3072c、b/237012816)
• 將動態主題 ColorProviders 設為專屬物件。將 ResourceColorProvider 設為模組內部。(Id0e2d、b/237012816)
• 將「未定義」類別新增至 ImageSize。(I2fa39)。
• 移除已淘汰的 GlanceAppWidget.Content 函式 (Ib05f6)
• 將修飾符做為參數新增至 AndroidRemoteViews。(I515d4)。
• 新增 GlanceAppWidget.compose，簡化單元測試 (Ie9b28)

修正錯誤

• 新增 Glance 文字字型的示範小工具 (I5c3d7)
• 讓 AndroidRemoteViews 可透過修飾符調整大小。
• 已解決主題顏色不一致的問題
• 所有資源皆已加上前置字串，以免發生衝突

1.0.0-alpha05 版

2022 年 10 月 5 日

發布 androidx.glance:glance:1.0.0-alpha05、androidx.glance:glance-appwidget:1.0.0-alpha05 和 androidx.glance:glance-wear-tiles:1.0.0-alpha05。查看 1.0.0-alpha05 版的修訂項。

新功能

• 將 requestPinGlanceAppWidget 新增至 GlanceAppWidgetManager，讓應用程式提示使用者將 Glance 型小工具新增至主畫面。(Ic6e47)。
• 將 ACTION_DEBUG_UPDATE 新增至 GlanceAppWidgetReceiver，讓開發人員強制要求小工具從已解鎖裝置和模擬器的 ADB 中更新。(I94ae1)。

API 變更

• 移除 Glance 範本中的標頭動作按鈕，藉此簡化用途。(Ie4387)。
• 重構單一實體範本，以便重複使用區塊子系統設計。(Iecd2c)。
• 重構 Glance 清單範本，以便使用 Text/Image/Action 區塊設計。(If0cc1)。
• 新增 TextBlock 和 ImageBlock 的優先順序值範圍。(I73100)。

修正錯誤

• 已移除 Material3 依附元件。(I28d1c)。
• 改用更加一致的系統，在 Glance 範本版面配置中增加邊界和間距。(I29773)。
• 修正格式錯誤的 Proguard 規則，以免導致無法建構壓縮版本。

1.0.0-alpha04 版

2022 年 8 月 10 日

發布 androidx.glance:glance:1.0.0-alpha04、androidx.glance:glance-appwidget:1.0.0-alpha04 和 androidx.glance:glance-wear-tiles:1.0.0-alpha04。1.0.0-alpha04 版包含以下修訂項目。

新功能

• 新增按鈕顏色功能。
• 新增 GlanceComposable 註解，以改善編譯時間檢查。
• 新增 Wear 專屬 Glance 功能。

API 變更

• 更新 Glance Gallery Data API 和精簡檢視(Ibc7a8)。
• 新增用於設定按鈕的 ButtonColors。(Iea88d、b/236305351)
• 將 ColorProvider.resolve 重新命名為 ColorProvider.getColor (Ic9dfe)
• 將 copy() 方法新增至 TextStyle(I9aef6)。
• 新增 ColorProviders 類別，可做為 Glance 主題的一部分(I848b9、b/237012816)
• 為清單樣式和收合的檢視畫面新增清單範本支援(I50cdc)。
• 在 GlanceModiier 和 GlanceCurvedModifier 中新增語意(Ifda7e)。
• 新增 GlanceComposable 註解(I5dbf0)。
• 將 Glance 範本移至主要的 Glance 專案(I9db94)。
• 新增 ColorProvider.resolve() (Ife532、b/214733442)
• 從現有 appWidgetId 或設定活動中的意圖取得 GlanceId 的新方法 (Icb70c、b/230391946)
• 新增 GlanceComposable 註解(I2c21f)。
• 已新增 GlanceRemoteViews，以便在 GlanceAppWidget 以外的位置執行組合(I18f92)。
• 移除 ProgressIndicatorDefaults 中的顏色(I40299)。
• 按照 API 審查意見回饋的要求，將 ActionCallback 的 onRun 方法重新命名為 onAction，以與公用 API 保持一致(Icfa57)。
• 轉換 glance 範本版面配置以使用地圖 (I46bfd)
• 新增 RadioButton 可組合項 (I4ecce)
• 新增了 GlanceWearTiles 用於撰寫 wear 資訊方塊 (Ia9f65)
• 新增了 GlanceCurvedModifier 的可點擊屬性 (Iec2a0)
• 實作 CurvedRow 範圍，並建立 DSL，以新增一般的可組合元素和/或曲線元素。在 proto 圖塊中一併新增 curvedLine 和 curvedSpacer，並轉換為 ArcLine 和 ArcSpacer (Ib955b)
• 根據 Tiramisu DP2 (I0cbb7) 更新核心和應用程式是否可為空值的作法
• 在 glance-wear-tiles 中新增對 RuncallbackAction 的支援，目前僅支援沒有參數的 RunCallbackAction (Ide64a)

外部貢獻

• 由於 test-coroutines-lib 遷移，更新了 :compose:ui:ui-test API (updateApi) (I3366d)

1.0.0-alpha03 版本

2022 年 2 月 23 日

發布 androidx.glance:glance-*:1.0.0-alpha03。1.0.0-alpha03 版包含以下修訂項目。

新功能

• 將狀態定義簡化為「偏好設定」。

API 變更

• 將 PreferencesGlanceStateDefinition 設為預設狀態處理，藉此簡化狀態處理。移除了 GlanceAppWidget.updateAppWidgetState 及引入 updateAppWidgetState，其預設使用 Preferences(I58963)。
• 新增 Glance TemplateText 類別，並更新範本設計 (I4e146)
• 為任意形式範本新增大綱基礎架構 (If03d6)
• 更新至 SingleEntityTemplate 版面配置 (If925d)
• 新增了 LazyVerticalGrid (I5f442)
• 在 SingleEntityTemplate 上使用 ColorProvider (I01ee0)
• 更新範本類別名稱 (I3720e)
• 新增了 LinearProgressIndicator 及 CircularProgressIndicator 可組合項(Ie116b)。

修正錯誤

• 初始化 glance 範本實作，定義「單一項目範本」資料及範例範本版面配置 (I35837)
• 根據預設，將設定方塊內容置中對齊 (I264be)
• 修正 glance-wear-圖塊中的 fillMaxSize/Width/Height 錯誤 (I0a39f)

1.0.0-alpha02 版

2022 年 1 月 26 日

發布 androidx.glance:glance-*:1.0.0-alpha02。1.0.0-alpha02 版包含此連結所列的修訂項目。

新功能

這個版本包含一組 API，可以使用 Compose 執行階段透過「Glanceable」的最佳化可組合項來建構 Wear 圖塊

• 透過擴充 GlanceTileService 以宣告 Wear 圖塊服務，這是用來在 Composable Content() 函式中建立圖塊的服務。
• Wear 資訊方塊專屬 glance 可組合項：CurvedRow、CurvedText。
• 定義 TimelineMode.SingleEntry 及 TimelineMode.TimeBoundEntries，以處理不同的圖塊時間軸模式。
• LocalTimeInterval，本機組合是指特定時間間隔。
• BorderModifer 是一個 GlanceModifier，會在元素周圍套用框線。

這個版本也會為 AppWidget Glance. 新增進度指標。

API 變更

• 新增了 LinearProgressIndicator 及 CircularProgressIndicator 可組合項(Ie116b)。
• 將 actionStartBroadcastReceiver 變更為 actionSendBroadcast (I7d555)
• 將結構定義傳送至 GlanceAppWidget onDelete 回呼 (I4c795)

修正錯誤

• 正確處理 OPTIONS_APPLABEL_SIZES (如有且為空)(I01f82)。

1.0.0-alpha01 版

2021 年 12 月 15 日

發布 androidx.glance:glance:1.0.0-alpha01、androidx.glance:glance-appwidget:1.0.0-alpha01 和 androidx.glance:glance-appwidget-proto:1.0.0-alpha01。1.0.0-alpha01 版包含以下修訂項目。

初始版本中的功能

• 第一版 Glance 提供第一組 API，用以使用 Compose Runtime 建立 AppWidget，以及一組為「可瀏覽」最佳化的新可組合項。

附註： Glance 使用專屬的一組可組合項。請勿合併 androidx.compose 及 androidx.glance 可組合項。

功能

• 透過 GlanceAppWidget 和 GlanceAppWidgetReceiver 宣告應用程式小工具。
• 使用 Glance 可組合項的初始組合來建立 UI：Box、Row、Column、Text、Button、LazyColumn、Image、空格字元。
• 使用 GlanceModifier 方法將修飾符套用至可組合項。
• 使用預先定義的操作處理使用者互動。
  • actionStartActivity
  • actionRunCallback
  • actionStartService
  • actionStartBroadcastReceiver
• 使用 ActionParameters 為操作提供參數。
• 處理 不同大小模式的方法是，定義 SizeMode.Single、SizeMode.Exact 或 SizeMode.Responsive。
• 透過提供 GlanceStateDefinition，保留 GlanceAppWidget 狀態。
• 本地組合，例如 LocalContext、LocalState、LocalGlanceId、LocalSize。
• 與現有的 RemoteViews 以及 AndroidRemoteViews 可組合元素互通。