Wear Watchface

建立 Wear OS by Google 智慧型手錶的應用程式。

注意： 自 2024 年 7 月 10 日起，錶面必須使用 錶面格式必須 安裝在已預先安裝 Wear OS 5 的新手錶上。瞭解詳情 將對 說明中心 一文。

此外，自 2025 年初起 (預計於 2024 年第 4 季) 推出後，所有在 Google Play 發布的新錶面都必須使用錶面 格式。

最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2024 年 4 月 17 日 1.2.1 - - 1.3.0-alpha03

宣告依附元件

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

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

Groovy

dependencies {
    // Use to implement wear watchfaces
    implementation "androidx.wear.watchface:watchface:1.2.1"

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.2.1"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1"

    // Use to implement a watchface style and complication editor
    implementation "androidx.wear.watchface:watchface-editor:1.2.1"

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.1"
}

Kotlin

dependencies {
    // Use to implement wear watchfaces
    implementation("androidx.wear.watchface:watchface:1.2.1")

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.2.1"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1"

    // Use to implement a watchface style and complication editor
    implementation("androidx.wear.watchface:watchface-editor:1.2.1")

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.1"
}

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

意見回饋

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

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.3 版

1.3.0-alpha03 版

2024 年 4 月 17 日

發布 androidx.wear.watchface:watchface-*:1.3.0-alpha03。1.3.0-alpha03 版包含這些修訂版本。

API 變更

  • 已新增 EditorSession#setOverrideComplications，可在編輯時暫時設定基礎錶面執行個體的 ComplicationData。如果小工具不常變更，這會比透過 EditorSession#renderWatchFaceToBitmap 傳入覆寫更有效率。(I19384)。

修正錯誤

  • 先前 selectComplicationDataForInstant 會針對任何時間軸呼叫 toApiComplicationData，也就是說，後續的 === 參照等式測試一律會失敗。也就是說，每個影格都會重新載入，導致電池耗電。 (717406)。

1.3.0-alpha02 版本

2024 年 4 月 3 日

發布 androidx.wear.watchface:watchface-*:1.3.0-alpha02。1.3.0-alpha02 版包含這些修訂版本。

新功能

  • 我們現在使用參照相等來比較最佳結果，且 selectedData 運算子昂貴。(446b00)。

API 變更

  • 我們已為 GoalProgressComplicationData 新增免備用動態 API。(c33264)。

1.3.0-alpha01 版本

2024 年 2 月 7 日

發布 androidx.wear.watchface:watchface-*:1.3.0-alpha01。1.3.0-alpha01 版包含此連結所列的修訂項目。

新功能

  • WatchFaceServices 可以並行初始化，因此應為無狀態，因此我們新增了 StatefulWatchFaceService，其中由 createExtra() 建立的額外項目傳遞到所有初始化時呼叫的覆寫值中。
  • GlesRenderer2 現在提供建構函式超載功能，可讓您指定要使用 eglChooseConfig 嘗試並嘗試的屬性清單。

API 變更

  • StatefulWatchFaceService 現在支援 getComplicationSlotInflationFactory 覆寫，其中會傳遞 createExtra() 建立的使用者定義額外項目。(I82d9f)。
  • 部分錶面需要與其他初始化方法共用 createUserStyleSchema 期間建立的輔助資料。由於沒有更好的替代方案，開發人員通常會將 WatchFaceServices 設為有狀態。這種做法不安全，因為可以同時建立多個執行個體，進而造成錯誤。為解決這個問題，我們已引入 StatefulWatchFaceService 和 StatefulWatchFaceRuntimeService，其中使用者定義類型是由 createExtra() 建立，並傳遞至各種建立方法做為參數。(If8a99)。
  • 我們已將 getUserStyleFlavors 新增至 InteractiveWatchFaceClient，該功能主要是供原始設備製造商 (OEM) 使用。(I0f5d8)。
  • GlesRenderer2 現在提供建構函式超載功能，可讓您指定要使用 eglChooseConfig 嘗試並嘗試的屬性清單。例如，您可以先嘗試使用具備反鋸齒的設定，然後視需要改回原設定。(I1ba74)。
  • 從 Android U 之後，Wear OS 將新增對 SystemDataSources.DATA_SOURCE_HEART_RATE 的支援。這個小工具只能保證支援 SHORT_TEXT 小工具，但建議讓 ComplicationSlot 也接受 SMALL_IMAGE，因為原始設備製造商 (OEM) 可能會選擇為其健康應用程式提供捷徑，而非即時值。(I34223)。
  • 我們已新增 METADATA_KEY_CONFIG_RESTORE_SUPPORTED，從 Android U 以上版本開始，利用 METADATA_KEY_DATA_SOURCE_CONFIG_ACTION 控管系統從備份資料來源還原系統時會發生什麼事。根據預設，系統會假設小工具資料來源服務支援任何設定資料的備份作業，但如果沒有備份資料，則可將中繼資料設定 METADATA_KEY_DATA_SOURCE_CONFIG_ACTION 設為 false，藉此將小工具版位標示為未設定。(I6c505)。

1.2 版本

1.2.1 版本

2024 年 1 月 24 日

發布 androidx.wear.watchface:watchface-*:1.2.1。查看 1.2.1 版的修訂項目。

修正錯誤

  • 修正 Samsung Galaxy Watch 4、5 和 Samsung 手錶的當機問題6.(43f0b0)。

1.2.0 版本

2023 年 11 月 29 日

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

自 1.1.0 版以來的重要異動

  • 我們已新增一些適用於 Android T 的小工具類型：
    • GoalProgressComplicationData 與 RangedValueComplicationData 類似，但其用途是實現隱含最小值為零，且值可以大於 targetValue 的目標。
    • WeightedElementsComplicationData，包含元素陣列 (權重和顏色的配對) 和選用文字/標題/圖片。這些顏色可能會以圓餅圖的形式呈現，其中顏色必須根據背景資訊產生意義，因為小工具通常沒有轉譯標籤的空間。
  • 我們已在 RangedValueComplicationData 中新增選用的 ColorRanges。一般來說，小工具會以錶面選擇的顏色顯示，但有時 ComplicationDataSource 最適合用來設定顏色，例如：有特定語意含意例如：用紅色到藍色表示溫度
  • 幾乎所有 ComplicationData 類型現在都支援 SmallImages。
  • 已新增 ComplicationDisplayPolicy，其中 DO_NOT_SHOW_WHEN_DEVICE_LOCKED 會指示相容的錶面在裝置鎖定時不顯示小工具。
  • 從 Android T 開始，原始設備製造商 (OEM) 將可判斷小工具要求是否來自 ComplicationRequest#isForSafeWatchFace 在供應商資訊清單中 android.support.wearable.complications.SAFE_WATCH_FACES 中繼資料定義的錶面上。提供者需要 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 權限才能接收 TargetWatchFaceSafety.UNKNOWN` 以外的任何內容。
  • UserStyleFlavors 已成為非實驗功能。

1.2.0-rc01 版本

2023 年 10 月 18 日

發布 androidx.wear.watchface:watchface-*:1.2.0-rc01。查看 1.2.0-rc01 版的修訂項目。

1.2.0-beta02 版

2023 年 9 月 6 日

發布 androidx.wear.watchface:watchface-*:1.2.0-beta02。1.2.0-beta02 版包含此連結所列的修訂項目。

新功能

  • 「SuspendingComplicationDataSourceService#onDestroy」現已營業。請注意，系統預設天氣小工具已停止支援。

API 變更

  • 還原「公開天氣小工具的新資料來源」。(I6f335)。

1.2.0-beta01 版本

2023 年 8 月 23 日

發布 androidx.wear.watchface:watchface-*:1.2.0-beta01。查看 1.2.0-beta01 版的修訂項目。

新功能

  • 從 Android T 開始，Wear OS 將支援預設的天氣系統小工具。

API 變更

  • 為小工具新增天氣預設系統備用選項。(Ia0994)。
  • 這個修補程式會新增 WatchFaceRuntimeService、WatchFaceControlClient.createWatchFaceRuntimeControlClient 以及 Guava 包裝函式。這些元件新增對錶面執行階段的支援，這類執行階段會從其他套件載入其定義。WearOS 目前僅支援 Android 錶面格式的執行階段。(I2799f)。
  • 這個修補程式是後續追蹤 aosp/2636578，我們將重新命名 int 定義，因此任何依 WatchFaceType、CanvasType、TapType 或 ComplicationsSlotBoundsType 執行的程式碼都不需要變更。(I4098b)。
  • 更新 API 檔案，為抑制相容性抑制加上註解。(I8e87a、b/287516207)
  • 此修補程式會公開 WatchFaceTypes 中的 WatchFaceType 常數、CanvasTypes 中的 CanvasType 常數、TapTypes 中的 TapType 常數，以及 ComplicationsSlotBoundsType 中的 ComplicationsSlotBoundsType 常數。(I3b85a、b/288750666)
  • WatchFace.OverlayStyle 的使用率極低，而且原始設備製造商 (OEM) 並未提供妥善支援，因此我們決定淘汰這項功能，以便日後移除。(I7344a)。

1.2.0-alpha09 版本

2023 年 6 月 21 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha09。查看 1.2.0-alpha09 版的修訂項。

新功能

  • RangedValueComplicationData.Builder 現在接受 DynamicFloat，而新的 DynamicComplicationText 可做為 ComplicationText 的子類別，兩者都能使用動態運算式和平台繫結 (在支援的 Wear 4 裝置上以 1hz 更新)。

API 變更

  • 新增每日距離、每日卡路里和每日樓層數的動態類型。平台健康狀態來源的金鑰現在屬於 PlatformHealthSources.Keys (Ib7637)
  • 實作 PlatformDataProvider 來提供心率和每日步數。已從公用 API 中移除 SensorGateway 介面。(I55b84)。
  • 將 StateEntryValue 重新命名為 DynamicDataValue，並將狀態 API 更新為使用 DynamicDataKey(If1c01)。
  • 新增 AppDataKey 以存取應用程式推送狀態；新增 PlatformDataKey 以存取平台資料；在 StateStore 新增命名空間支援。(I7985e)。
  • enable 個方法 (共 disablePlatformSource 個) 已從「DynamicTypeEvaluator」中移除。呼叫端應負責更新。(I78c6d)。
  • 允許繫結資料類型的大小上限。(Ie2966)。

1.2.0-alpha08 版

2023 年 4 月 19 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha08。查看 1.2.0-alpha08 版的修訂項。

新功能

  • 自 Android T 起，具有 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 特殊權限的小工具供應商可以註冊 androidx.wear.watchface.complications.datasource.SAFE_WATCH_FACE_SUPPORTED_TYPES 中繼資料，覆寫 android.support.wearable.complications.SUPPORTED_TYPES 以提供安全的錶面。這表示小工具供應商可能會選擇為可信任及不受信任的錶面提供不同類型。

API 變更

  • 將 @Deprecated 類別套用至屬性 (I882d1、b/271441831)
  • Enum.valueOf 的值參數名稱已變更 (Ia9b89)
  • 更多從 enum valueOf 擲回的例外狀況 (I818fe)
  • 我們移除了 renderWatchFaceToSurface，改用以 SurfaceControlViewHost 為基礎建構的 createRemoteWatchFaceView，並允許呼叫端嵌入錶面 (在用戶端呼叫 RemoteWatchFaceViewHost#renderWatchFace 時算繪) 的檢視畫面。(Ib311d)。
  • 我們已將 renderWatchFaceToSurface 新增至 InteractiveWatchFaceClient、HeadlessWatchFaceClient 和 EditorSession。一般而言，此效果比算繪到點陣圖更有效率。(Ieacad)。
  • ObservableStateStore 已重新命名為 StateStore。(Ieb0e2)。
  • 新增了 DynamicTypeEvaluator.Builder 而非建構函式引數，以允許更多選用引數，包括 ObservableStateStore，現在預設為空白儲存庫。(I6f832)。
  • 重構 DynamicTypeEvaluator 中的參數順序。(Ic1ba4)。
  • 已將執行程式新增至 DynamicTypeEvaluator.bind 方法。(I346ab)。
  • 我們已在 BoundDynamicType 中新增 startEvaluation 方法，以便在動態類型繫結後觸發評估作業。(I19908)。
  • 具備 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 特殊權限的小工具供應商可以註冊 androidx.wear.watchface.complications.datasource.SAFE_WATCH_FACE_SUPPORTED_TYPES 中繼資料，覆寫 android.support.wearable.complications.SUPPORTED_TYPES 以提供安全的錶面。(Id1c73)。
  • 我們已將「CustomValueUserStyleSettings2」重新命名為「LargeCustomValueUserStyleSettings」。(Ic17ac)。

修正錯誤

  • 已移除 DynamicTypeValueReceiver#onPreUpdate。(I2dc35)。

1.2.0-alpha07 版

2023 年 2 月 22 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha07。查看 1.2.0-alpha07 版的修訂項。

新功能

  • 從 Android T 開始，原始設備製造商 (OEM) 將可判斷小工具要求是否來自 ComplicationRequest#isForSafeWatchFace 在供應商資訊清單中 android.support.wearable.complications.SAFE_WATCH_FACES 中繼資料定義的錶面上。提供者需要 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 權限才能接收 TargetWatchFaceSafety.UNKNOWN 以外的任何內容。

  • 此外，Android T CustomValueUserStyleSetting2 也開放使用 (最高 12.5 KB)。「CustomValueUserStyleSetting」先前的限制為 1 KB。雖然大小限制已增加，我們仍建議錶面開發人員盡量減少資料，因為在編輯時透過藍牙傳送設定，且藍牙頻寬有限。

API 變更

  • 我們為 GlesRenderer & 新增了選用參數 eglContextAttribListGlesRenderer2，可讓您設定傳遞至 EGL14.eglCreateContext 的 EGL14.EGL_CONTEXT_CLIENT_VERSION。(I2a83e)。
  • 已將錶面程式庫遷移至 androidx.core.util.Consumer，而非 java.util.function.Consumer。(I273f5)。
  • 更多 KT 屬性存取子擲回的例外狀況 (Iff9d9)
  • 我們新增了 InteractiveWatchFaceClient.isComplicationDisplayPolicySupported，方便用戶端判斷是否必須模擬舊錶面支援功能。(I24c89)。
  • 我們決定 isForSafeWatchFace 應為三州 IntDef。(Ief2f7)。
  • 我們針對 Android T 導入了 ComplicationRequest.isForSafeWatchFace，這是供 OEM 使用，且需要 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE。針對系統映像檔中的資料來源，如果在資訊清單中資料來源指定的安全錶面清單內，則此值會傳回 true。(I0cbb6)。
  • 我們已為 Android T 新增 CustomValueUserStyleSetting2，最大可達 12.5KB。「CustomValueUserStyleSetting」先前的限制為 1 KB。(I0b100)。

1.2.0-alpha06 版本

2023 年 1 月 25 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha06。1.2.0-alpha06 版本包含這些修訂版本。

新功能

  • 我們正努力新增對小工具平台繫結的支援功能，目前此功能尚未就緒，敬請期待！
  • 我們已針對 GOAL_PROGRESS 和 WEIGHTED_ELEMENTS 這兩種新的小工具類型，新增 XML ComplicationSlot 支援。

修正錯誤

  • 修正錶面編輯器未在 Samsung 裝置上正確發布的漏洞。(3b5987)。
  • 修正在切換有多項常用工具的錶面時，有時小工具無法正確顯示的錯誤。(b38ece)。
  • 修正會導致錶面當機的 perOptionScreenReaderNames 序列化錯誤(e9f466)。

1.2.0-alpha05 版本

2022 年 12 月 7 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha05。查看 1.2.0-alpha05 版的修訂項。

新功能

  • 我們不久前新增了階層 UserStyleSettings 的支援功能，從 Android T 開始，階層中現在可以有多個 ComplicationSlotsUserStyleSetting。視使用者選擇的樣式而定，只有一個 ComplicationSlotsUserStyleSetting 會處於啟用狀態。

  • 我們將新增 screenReaderName 欄位，提升對 ListOption 和 ComplicationSlotsOption 的螢幕閱讀器支援，請注意，在 Android T 之前，隨附編輯器會忽略這個欄位。

API 變更

  • 我們為 ListOption 和 ComplicationSlotsOption 新增了選用的 screenReaderName 欄位供編輯器使用。在 Android T 之前，裝置上的隨附編輯器會忽略這個欄位(I75326)。
  • 從 Android T 開始，樣式階層現在支援多個 ComplicationSlotsUserStyleSettings，但一次最多只有一個能夠啟用。我們已將公用函式 findComplicationSlotsOptionForUserStyle 新增至 UserStyleSchema，以利找出啟用的 ComplicationSlotsOption (如有)。(Ic2b06)。
  • RangedValuesTypes 已提取到 RangedValueComplicationData 的隨附物件中，並重新命名為 TYPE_UNDEFINED，另外也添加 TYPE_RATING 和新的 TYPE_PERCENTAGE(I55d02)。
  • 我們已將實驗性的 DynamicFloat 重新命名為 FloatExpression，並標示為 @hide(Idf4f1)。
  • 新增 @JvmDefaultWithCompatibility 註解 (I8f206)

1.2.0-alpha04 版本

2022 年 11 月 9 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha04。1.2.0-alpha04 版包含此連結所列的修訂項目。

新功能

  • 在 Android T 中，我們已對以下兩個全新小工具類型新增支援：GoalProgressComplicationData 和 WeightedElementsComplicationData。
  • GoalProgressComplicationData 與 RangedValueComplicationData 相似，但其值可以超出目標值 (RangedValueComplicationData 的值限制在 [最小值 .. 最大值] 的範圍中)，這會影響可能不適用於所有錶面的視覺設計。
  • GoalProgressComplicationData 新增圓餅圖支援，以及簡易資料的類似細目。
  • 我們已為 RangedValueComplicationData 新增 ColorRamps 的選用支援。
  • 針對 Android T，我們已在 ComplicationData 中新增 ComplicationPersistencePolicy 和 setCachePolicy，讓供應商能夠控制是否要保留小工具，例如是否在重新啟動後進行快取。大部分小工具不必設定快取控制項，但對於一些頻繁更新的小工具 (例如健康資料小工具)，這樣做可以修正帶有過時資料的邊角案例。我們還新增了 ComplicationDisplayPolicy，其中 DO_NOT_SHOW_WHEN_DEVICE_LOCKED 會指示相容的錶面在裝置鎖定時不顯示小工具。(Ic9574)。

API 變更

  • GoalProgressComplicationData、WeightedElementsComplicationData 及 ColorRamp 不再是實驗功能。(Ica9e2)。
  • ComplicationPersistencePolicy 和 ComplicationDisplayPolicy 現已正確標示為 T API。(I31d88)。
  • 淘汰的 ComplicationSlotOverlay 建構函式現在有了 DeprecationLevel.WARNING，可以再次從 Java 呼叫。(Ib308c)。
  • 我們透過使用 @JvmDefaultWithCompatibility 加上註解，已修正 ComplicationRequestListener、CanvasComplication、ComplicationTapFilter 和 InteractiveWatchFaceClient 的 Java 相容性問題 (Id94fc)
  • 我們移除了實驗性的 ProtoLayoutComplicationData 和 ListComplicationData，其追蹤報導並不明確，我們希望以後再探討。(I9df05)。
  • 我們將 ValueType 重新新增至 RangedValueComplicationData。WeightedElementsComplicationData 現在支援背景顏色。我們已移除 DiscreteRangedValueComplicationData，因為其功能為 WeightedElementsComplicationData 的子集。(I6446c)。

修正錯誤

  • 在「等於」和「雜湊碼」中加入 isForScreenShot。確認 onRenderParametersChanged 取得正確的 isForScreenshot 值 (I04a41)
  • 修正了 WatchFaceControlService 從無頭用戶端外洩的問題。(e90e00)。

1.2.0-alpha03 版本

2022 年 10 月 5 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha03。查看 1.2.0-alpha03 版的修訂項。

新功能

  • 沒有新功能，但修正了幾個錶面編輯器錯誤。

API 變更

  • 淘汰了 UserStyleSchema.userStyleSettings，因為 rootUserStyleSettings 不再是實驗性質 (Ie96e3)
  • 讓 rootUserStyleSettings 脫離實驗階段 (I8d6b3)
  • 我們已將 WatchFaceColors 標示為實驗功能，因為不是所有系統都支援此類別 (I6d75d)
  • 在公用 API 中公開 DisconnectReasons，使其能夠與 IntDef 搭配使用。(I791f8)。

修正錯誤

  • SysUI 失敗時關閉任何開啟的手錶編輯器。如果 SysUI 失敗且錶面編輯器並未關閉，錶面可能會處於不一致的狀態，這是因為系統會依賴 SysUI 來保存使用者的樣式變更 (ba762a)。
  • 修正 ComplicationDataSourceInfoRetriever 中的記憶體流失問題。在這個錯誤中，Kotlin 協同程式接續操作會做為 GCS 根目錄，且會保留編輯者活動 (33ee06)。

1.2.0-alpha02 版本

2022 年 9 月 21 日

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

新功能

  • 某些錶面在 UserStyle 以外的設定會影響視覺呈現 (例如選取背景相片)。我們已新增 Renderer.sendPreviewImageNeedsUpdateRequest，可讓錶面要求更新的預覽圖片。請注意，這需要對應的系統最新版本才能運作。

  • 此外，我們也為錶面新增一個 API，以便向系統公開顏色，由系統據此選擇調色盤。請注意，我們已在修補程式的後續追蹤中進行實驗。

  • 幾乎所有 ComplicationData 類型都支援 SmallImages。

API 變更

  • 有時桌布管理工具可以與引擎中斷連結，用來製作另一個引擎。新增 DisconnectReason int def 並透過包含 DisconnectReason 的新方法擴充 ClientDisconnectListener，讓事件監聽器能觀察到引擎中斷連結。(I45cce)。
  • 在 ComplicationSlotOverlay 建構函式中加入兩個選用參數 nameResourceId 和 screenReaderResourceId (I157e8)
  • 我們已新增 Guava 包裝函式，以用於包含 PreviewImageUpdateRequestedListener 的 getOrCreateInteractiveWatchFaceClient 新超載。(Ic31f0)。
  • 我們已新增 Renderer.sendPreviewImageNeedsUpdateRequest，如果狀態並非為 UserStyleSchema 會影響外觀 (例如具有可選取背景圖片的錶面)，就能派上用場。在用戶端上，我們已將 PreviewImageUpdateRequestedListener 新增為 getOrCreateInteractiveWatchFaceClient 的選用參數，以觀察這些要求。(Iff44a)。
  • 我們已簡化 API 以公開 WatchFaceColors，現在轉譯器上有一個稱為 watchFaceColors 的簡單屬性，錶面可以設定，且應隨著任何樣式變更而視需要更新。為避免使用 WallpaperManager 觀察顏色變化，我們已在 InteractiveWatchFaceClient 中新增 OnWatchFaceColorsListener。(I490bc)。
  • 我們已新增 WatchFaceColors 類別，其包含三種最醒目的錶面顏色，並新增了開放式方法 watchfaceColors 和notifyWatchFaceColorsChanged 提供給轉譯器，讓系統透過 WallpaperManager.getWallpaperColors 取得錶面顏色。(I3d611)。
  • ShortTextComplicationData、RangedValueComplicationData、NoPermissionComplicationData (以及實驗性 DiscreteRangedValueComplicationData、GoalProgressComplicationData 和 WeightedElementsComplicationData) 現在都支援 SmallImages。如果錶面選擇算繪具有多種顏色的小工具，現在可選擇使用多色 SmallImage，先前必須使用單色圖片。(I257df)。
  • 將 PreviewImageUpdateRequestedListener 重構為 Consumer<> (Ia875d)
  • 用一般 Java SAM 類型 (消費者) 取代自訂單一抽象方法 (SAM) 類型 OnWatchfaceColorsListener (I0c489)
  • 我們淘汰了未指定 PreviewImageUpdateRequestedListener 的舊版 getOrCreateInteractiveWatchFaceClient 和 listenableGetOrCreateInteractiveWatchFaceClient 方法。(Iec502)。

修正錯誤

  • 「DisconnectReason.BINDER_DIED」已重新命名為「DisconnectReason.ENGINE_DIED」。(I4eb0e)。

1.2.0-alpha01 版本

2022 年 8 月 10 日

發布 androidx.wear.watchface:watchface-*:1.2.0-alpha01。1.2.0-alpha01 版包含此連結所列的修訂項目。

新功能

  • 我們已針對多種新的小工具格式新增實驗性的支援功能。這可能是積極開發的領域我們可能會隨時變更這些新格式，恕不另行通知。此外，CanvasComplicationDrawable 目前並未提供轉譯器支援。
  • 我們也讓開發人員能選擇小工具版位的邊界，使小型小工具更易於點選。

API 變更

  • 實驗性的 BoundingArc 類別現在屬於不可變類別 (If624a)。
  • 某些小工具的圖示非常小，使用者很難點選。為緩解此問題，我們開始支援邊界，在不影響算繪的情況下增加可輕觸區域的邊界。除非專程透過程式碼或 XML 指定，否則 ComplciationSlots 預設的邊界大小為零 (I14089)。
  • 變更 getComplicationSlotInflationFactory(CurrentUserStyleRepository) 簽名，使其回傳非空值的工廠執行個體。之前會回傳空值是一種錯誤，所以這樣做只是讓 API 合約更清楚 (I0fcc0)。
  • 我們已為 WatchFaceService.getComplicationSlotInflationFactory 方法新增 currentUserStyleRepository 引數，以便和 createComplicationSlotsManager 保持一致(I2ddd2)。
  • UserStyleFlavors 已成為非實驗功能 (I69cdc)。
  • 我們已從 RangedValueComplicationData 中移除實驗性的 ValueType，並導入實驗性的 DiscreteRangedValueComplicationData，這個項目和 RangedValueComplicationData 相似，只有整數範圍和值。我們也導入了實驗性的 GoalProgressComplicationData，這個項目和 RangedValueComplicationData 相似，差別在其用途是實現隱含最小值為零，且值可以大於 targetValue 的目標。請注意，所有 RangedValue 變數都必須至少指定一個 monochromeImage、文字或名稱 (I9590c)。
  • 由於系統軟體沒有相關用途，我們已從 ComplicationSlotState 中移除 boundsWithMargins (I42e26)。
  • 我們為 WeightedElementsComplicationData 新增實驗性的支援功能，其中有元素陣列 (權重和色彩的配對) 和選填文字/名稱/圖片。您可以用圓餅圖顯示這些內容，而圖表的顏色意義必須符合脈絡，因為小工具在一般情況下沒有轉譯標籤的所需的空間 (I87eea)。
  • 之前 RangedValueComplicationData 和 GoalProgressComplicationData 選擇性使用的實驗性 ColorRamps 現在可以讓您指定一系列的顏色 (最多七種)，並可以透過標記指定顏色應該採用漸變顏色，或是轉譯同等大小且有固定的變色程度 (I9f5bf)。
  • RangedValueComplicationData.drawSegmented 已變更為 valueType，這是一個包含對應 ValueType IntDef 的 int，其可為範圍值提供語意含義，小工具轉譯器可能會使用它來影響樣式。(I0616b)。
  • 我們已為 RangedValueComplicationData 新增非必要的 ColorRanges 支援功能。在一般情況下，小工具轉譯時會使用錶面指定的顏色，但是有時候最合適的做法是藉由置放 ComplicationDataSource 設定顏色，例如當這些小工具有特定的語意含義時。例如：用紅色到藍色表示溫度 (I5153a)。
  • 我們為 RangedValueComplicationData 新增實驗性的 drawSegmented 微調設定。這個設定可以讓轉譯器用片段繪製一個範圍的值指標，其中每 1 個片段 = 1 個單位 (I7d7c1)。

修正錯誤

  • 新增可以定義和預先定義的螢幕座標系統相關的 ComplicationSlotBounds 的功能 (I0985d)。

1.1 版本

1.1.1 版本

2022 年 8 月 10 日

發布 androidx.wear.watchface:watchface-*:1.1.1。1.1.1 版本包含以下修訂項目。

  • 我們在此版本中修正了錯誤，並強烈建議 1.1.0 版本的使用者升級版本。

修正錯誤

  • 錶面初始化是非同步的過程，若系統在錶面未準備好的情況下接收到小工具，系統就會把這個小工具放到 pendingInitialComplications 清單並改在之後套用。不巧的是 pendingInitialComplications 的套用速度過快，導致錶面初始化過程中有一段時間會讓系統照樣把小工具放到 pendingInitialComplications 並就此忽略。我們已經修正此問題。本修補程式也修正了 ComplicationRenderer 會錯誤嘗試用非同步方式載入預留位置，進而在失敗後導致小工具圖像無法更新的問題。最後，本修補程式還修正了多個 pendingInitialComplications 需要合併這個希望只是理論範圍的錯誤 (0d03ba3)。

  • 修正 InteractiveInstanceManager 可能會導致 getExistingInstanceOrSetPendingWallpaperInteractiveWatchFaceInstance 保留鎖定時間過長的死結。我們通常預期 engine.setUserStyle 很快就能處理，但如果出於某些原因無法快速處理，就可能會發生死結/ANR。本修補程式會把非必要的工作移出鎖定，防止系統發生這類死結 (5a2adca)。

  • 修正數個保留 WatchFaceService 的問題。WakeLock 有時會保留 WatchFaceService，加入 release() 呼叫可以修復此問題。StateFlows 也能保留 WatchFaceService，取消基礎的 CoroutineScopes 可以修復此問題 (fd48138)。

  • 為 awaitDeferredWatchFace* 新增逾時，並修正了 watchfaceOverlayStyle NullPointerException。這個項目在一般情況下不應該逾時，包括新安裝和 DirectBoot 等 CPU 負載量較高的情況。我們也修正了在 close() 之後呼叫 getWatchfaceOverlayStyle 會發生的 NPE (a4c3a5a)。

1.1.0 版本

2022 年 6 月 15 日

發布 androidx.wear.watchface:watchface-*:1.1.0。查看 1.1.0 版的修訂項。

自 1.0.0 版本以來的重要異動

更強大的編輯功能：

  • 我們加入了階層式架構的支援，讓編輯器使用者介面可以設定樣式的階層。您現在可以在錶面和隨附編輯器中指定個別的使用圖示。
  • 使用者選擇支援錶面的多個執行個體，每個執行個體都有一組專屬 ID，可在所有 API 介面使用。
  • 您現在可以為 ComplicationSlots 指定人類可讀的名稱，以在編輯器中使用。
  • 實驗性支援「特色」樣式，這些精選樣式可以從配套編輯器中查看。
  • 錶面的兩個執行個體編輯內容載入後，錶面執行個體現在可以共用資源，進而節省記憶體
  • 在錶面編輯器選取小工具時，系統會預先選取目前的供應程式。

改善的小工具：

  • 您現在可以為主要和次要資料來源指定 ComplicationType，讓開發人員享有更靈活的使用體驗。
  • 我們新增了 ComplicationDataTimeline，以將定時的資料傳遞至錶面，並自動快取及更新。例如本日不同時段的天氣預報，或是多個即將到來的日曆活動。
  • 小工具提供者的 ComponentName 屬於 ComplicationData 的一部分。
  • 小工具現在可以進行快取，因此在不同的錶面之間切換時可以提供更好的體驗。

其他變更：

  • 現在可以在 XML 中定義 UserStyleSchema 和 ComplicationSlots。這可以簡化錶面建立作業，並且能加快系統查詢中繼資料的速度。
  • 現在，錶面可以影響系統重疊顯示系統重疊色彩。

1.1.0-rc01 版本

2022 年 5 月 18 日

發布 androidx.wear.watchface:watchface-*:1.1.0-rc01。1.1.0-rc01 版包含此連結所列的修訂項目。

新功能

  • 我們針對錶面 XML 支援功能進行了一些可用性調整，方便您指定 ComplicationSlotBounds 及支援參考資料。邊緣小工具 BoundingArc 的實驗將繼續並推進至 drawHighlight，但目前不建議使用。

API 變更

  • 我們已新增 drawHighlight 的實驗性超載，接受 BoundingArc 參數(I705f8)。
  • 錶面 XML 現在支援資源參照，讓您可在 XML 和程式碼中使用相同的常數 (I3ef61)。
  • 我們已新增在 center_x、center_y、size_x 和 size_y 表單中定義 ComplicationSlotBounds 的功能。現在，您也可以使用資源參照來使用不同的單位，例如 dp (Iace98)。

修正錯誤

  • 修正在錯誤情境中執行工作的 runBlockingWithTracing。(4f595fe)
  • 將 BaseEditorSession.close 設為同步。BaseEditorSession.close 不同步的問題在於，我們太晚發布 ComplicationDataSourceInfoRetriever，導致 Logcat 中出現警告垃圾訊息。這可能是無害的，但 Logcat 的垃圾郵件會使人分心，因此應避免 (35a5308)。

1.1.0-beta02 版本

2022 年 5 月 11 日

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

新功能

  • 我們已針對新的 ComplicationData 類型提供實驗性支援，目前還不開放使用，但請密切留意。

API 變更

  • 我們新增了 BoundingArc 這個實驗性類別，用來說明邊緣小工具版位的幾何圖形。這已新增至 ComplicationSlot，而且連接至 ComplicationSlotState 和 WatchFaceMetadataClient (I61a40)。
  • 我們已新增沿用 UserStyleSetting XML 設定的功能。可降低詳細程度，並在錶面之間分享設定 (Ief841)。
  • 我們已新增兩種 ComplicationData 實驗性類型：ListComplicationData 和ProtoLayoutComplicationData。目前不支援這些類型的算繪，而且如果已新增至 ComplicationDataSource's 資訊清單，Wear OS 目前無法識別這些類型。(I1811c)。

修正錯誤

  • 修正 TimeLineEntry 類型的序列化。我們並未序列化 TimeLineEntry 類型，這表示在存取不存在的必填欄位時，NoData 類型的快取 TimeLineEntries 會被誤解為具有導致 NPE 的父項小工具類型。(55ffdf5)。
  • 修正 setComplicationData 已捨棄時間軸欄位的錯誤 (fb392f5)
  • 修正極少數情況下 runBlockingWithTracing 會引發 NPE 的錯誤(12ca62e)
  • 修正在接收小工具時，有時會取得 ClassNotFoundException: android.support.wearable.complications.ComplicationText 的錯誤 (217942d9)。
  • 修正 GlesRenderer.backgroundThreadInitInternal 中只有在呼叫 EGL14.eglCreateContext 時，才會呼叫 onBackgroundThreadGlContextCreated 的錯誤。修正其他錯誤：verticalFlip 造成螢幕截圖中有視覺故障。(c674ad2)
  • 修正 WatchFaceService XML 版本檢查：從錯誤的套件中載入 (dfa06f3)。
  • 預留位置傳輸格式現在使用內部組合。我們不希望預留位置破壞可能使用隱藏的內部 a.s.w.c.ComplicationData 的現有錶面。先前，NoDataComplication 資料的傳輸格式會將預留位置儲存在一般欄位中 (發生問題，因為舊錶面會轉譯非預期的預留位置字串)，而現在則是使用內部套件來完全隔離 (d5e7bd2)。

1.1.0-beta01 版本

2022 年 4 月 20 日

發布 androidx.wear.watchface:watchface-*:1.1.0-beta01。查看 1.1.0-beta01 版的修訂項。

API 變更

  • 現在 WatchFaceMetadataClient 方法 (getUserStyleSchema、getComplicationSlotMetadataMap、getUserStyleFlavors) 和 HeadlessWatchFaceClient.getUserStyleFlavors 會擲回未檢查的 RuntimeException，而不是 WatchFaceException。(I0718a)
  • WatchFaceMetadataClient.WatchFaceException 已移出類別，因此無法重複使用。(I4e869)

修正錯誤

  • 傳送部分 ComplicationSlotBounds 時，WatchFaceMetadataClient 不會再當機。(Iaafd)

1.1.0-alpha05 版本

2022 年 4 月 6 日

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

新功能

  • 您現在只要檢查 ComplicationData.dataSource，即可判斷傳送 ComplicationData 的資料來源，部分錶面可能會藉此自訂小工具顯示功能。(I44a73)

API 變更

  • Renderer.CanvasRenderer 和 Renderer.GlesRenderer 已淘汰，並改用 Renderer.CanvasRenderer2 和 Renderer.GlesRenderer2 (支援傳遞給轉譯方式的 SharedAssets)。我們針對 Java 互通性引入了 ListenableCanvasRenderer2 和 ListenableGlesRenderer2。(I31ffa)
  • 已新增 @WatchFaceFlavorsExperimental 功能，用於定義變種版本 - 預先設定樣式化錶面清單 (I04dd0)
  • Renderer.sharedAssets 現在是 StateFlow，我們移除了未使用的 Renderer.SharedAssetsFactory (I12ac5)
  • 不再淘汰 UserStyleSchema.userStyleSettings (Iba7e3)
  • 已新增 HeadlessWatchFaceClient.getUserStyleSchemaDigestHash，讓 HeadlessWatchFaceClient 避免在計算摘要雜湊之前，透過 AIDL 傳遞結構定義時產生相對較低的負擔。(I33597)
  • 已將 isUserStyleSchemaStatic 新增至 WatchFaceMetadataClient，只有在確信 UserStyleSchema 不會發生變更時 (除非更新錶面 APK)，這個參數的值才為 true。(I45a3f)
  • 我們已將 getDigestHash 新增至 UserStyleSchema，以便計算結構定義的摘要雜湊值。這可以有效地判斷 UserStyleSchema 是否已變更。(I2063d)
  • METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIGURATION_SUPPORTED 已重新命名為 METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIG_SUPPORTED (I9ba5d)
  • UserStyleSetting.OnWatchEditorData 已重新命名為「UserStyleSetting.WatchFaceEditorData」，其中包含僅供錶面編輯器使用的資料。(If3afb)

1.1.0-alpha04 版本

2022 年 3 月 9 日

發布 androidx.wear.watchface:watchface-*:1.1.0-alpha04。查看 1.1.0-alpha04 版的修訂項。

API 變更

  • 可能無法隨時提供最新的 ComplicationData 版本 (例如快取的 ComplicationData 已過期)，因此我們已透過選用預留位置 ComplicationData 擴充 NoDataComplication，並新增了 ComplicationText.PLACEHOLDER、MonochromaticImage.PLACEHOLDER、SmallImage.PLACEHOLDER、PhotoImage.PLACEHOLDER，這只能用於 NoDataComplicationData 預留位置的內容中。如果選取這類預留位置，建議以灰色方塊/弧形顯示 (I6285d)
  • 已新增 ComplicationData.getNextChangeInstant，讓您參考互動智慧搜尋之後獲知下一個 Instant，其中小工具的任何欄位可能會隨時變更。這可用於在內部安排頁框以進行小工具更新。例如，如果錶面通常每分鐘更新一次，設定秒錶小工具會導致每秒更新一次。(I7ceb2)
  • EditorSession.watchFaceId 現在可用於所有 API 級別，而且其值將始終與 WatchState.watchFaceInstanceId 一致。(I323b9)
  • 由於架構的基礎問題已修正，不再需要使用 getPendingIntentForTouchEvent API，因此所有相關的 API 都已移除。即使剛按下主畫面按鈕，錶面也不需要額外執行任何動作來啟動 PendingIntents(I1f2e8)。
  • 我們已新增 RendererParameters.isForScreenShot，如果轉譯是針對螢幕截圖，該參數的值將為 True。某些含有動畫的錶面需要知道這個值，才能做出調整，以確保呈現最佳效果 (I96d99)。
  • 我們已將 WatchFaceExceptionReason 新增至 WatchFaceException，以提供錯誤的背景資訊。(I01d15)
  • 已移除 ComplicationDataSourceService.onImmediateComplicationRequest，ComplicationRequest.immediateResponseRequired 已新增至信號，供應商必須快速回應此信號 (最好少於 100 毫秒)。請注意，這項功能受到 com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE 特殊權限限制。(Ie6b23)
  • 根據 Tiramisu DP2 (I0cbb7) 更新核心和 appcompat 的可空值性

修正錯誤

  • 現在，如果結構定義驗證失敗，就會意外觸發錶面應用程式當機 (Ia400f)

1.1.0-alpha03 版本

2022 年 2 月 9 日

發布 androidx.wear.watchface:watchface-*:1.1.0-alpha03。1.1.0-alpha03 版包含此連結所列的修訂項目。

API 變更

  • 我們已為階層式樣式結構定義新增實驗性支援。我們已將新的屬性新增至 androidx.wear.watchface.style.UserStyleSetting.Option，這個子項設定最初僅供 ListOption 使用。這樣一來，即可描述樣式的階層結構，以供編輯器 UI 使用；基礎 UserStyle 則保持不變，仍然是 Map<String, ByteArray>。(Iaf6f4)
  • 我們新增了 WatchFace.OverlayStyle，可讓錶面設定系統狀態疊加層的算繪方式 (I8520d)。
  • 我們為 CanvasRenderer 推出了 clearWithBackgroundTintBeforeRenderingHighlightLayer，這是新的選用建構函式參數 (預設為 false)，如果設為 True，畫布就會以背景色調顏色清除。(Ie01e5)。
  • 新增 androidx.watchface.complications.datasource.DEFAULT_CONFIGURATION_SUPPORTED 中繼資料金鑰，讓小工具資料來源表示可以提供無需設定的預設值 (Icc0d4)
  • 編輯錶面時，常會出現互動式與無頭執行個體。為協助節省記憶體，我們引入了 Renderer.SharedAssets，以允許錶面轉譯器在執行個體之間共用不可變資料 (例如紋理和著色器)。GlesRenderer.setEglConfig 和 GlesRenderer.setEglDisplay 已淘汰，因此不應設定這些項目，這樣做會導致無法定義的行為。(I0d9e7)
  • 我們已新增setNameResourceId和setScreenReaderNameResourceId (參照字串資源) 指向 ComplicationSlot.Builder 和 androidx.wear.watchface.client.ComplicationSlotState 中對應的 getter。這樣一來，系統即可擷取 ComplicationSlots 的名稱，以便在編輯器和螢幕閱讀器中使用。(If6c6a)。
  • WatchfaceMetadataClient.getUserStyleSchema 和 getComplicationSlotMetadataMap 現在擲回 WatchFaceException，而不是 RemoteException。(I86f11)
  • 已將 onSynchronousComplicationRequest 和 ComplicationDataSourceService 中的相關函式重新命名為 onImmediateComplicationRequest 等等。(I87ba0)
  • 與隨附編輯器相比，錶面編輯器的螢幕空間較少，因此它可以支援在錶面編輯器中使用不同的圖示。此修補程式會將 OnWatchEditorData (目前只包含圖示) 新增至所有 UserStyleSettings 和適當的 Option 類別 (If1886)。
  • 我們已將 @JvmOverloads 新增至 ListenableGlesRenderer 的建構函式，以便改善 Java 互通性。(I2974a)

修正錯誤

  • ListenableGlesRenderer 的建構函式現已正確標示為 @Throws(GlesException::class)，現在可以在 Java 中擴充此類別(Iac6d0)。
  • 修正 PhotoImageComplicationData tapAction 的錯誤 正確處理 (I1cc30)

1.1.0-alpha02 版本

2022 年 1 月 12 日

發布 androidx.wear.watchface:watchface-*:1.1.0-alpha02。查看 1.1.0-alpha02 版的修訂項。

新功能

  • 為便於偵錯及測試，ComplicationData 和相關子類別現已覆寫雜湊碼、equals 方法和 toString 方法，讓這些類別更容易使用。

API 變更

  • WatchfaceMetadataClient 方法會視情況再次擲回 RemoteExceptions，以便用戶端程式碼能夠更輕鬆地從錶面擷取錯誤。(I78785)
  • ComplicationData 和子類別現已採用雜湊碼、等於和 toString。(I24bc6)

1.1.0-alpha01 版本

2021 年 12 月 15 日

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

新功能

  • 現在可以在 XML 中定義 UserStyleSchema 和 ComplicationSlots。這項功能可簡化錶面的結構。此外，由於 WatchFaceMetadataClient 查詢不必繫結至服務就能取得中繼資料，因此查詢速度會更快。WatchFaceMetadataClient 和 ListenableWatchFaceMetadataClient 已不再為實驗性功能，因此將加入穩定版 API 中。系統將能選擇是否支援錶面的多個執行個體，而這些執行個體分別有使用者定義的不同樣式選項。這些內容會顯示在錶面挑選器中。如要加入錶面，必須在資訊清單中加入下列中繼資料標記。

        <meta-data
        android:name="androidx.wear.watchface.MULTIPLE_INSTANCES_ALLOWED"
        android:value="true" />

  • 有些錶面具有 UserStyle 中未擷取的狀態，為了支援這種情況和多個執行個體的情況，現在可以透過 WatchState.watchFaceInstanceId 取得錶面的執行個體 ID。

  • 系統正在快取 ComplicationData，以便在資料載入時立即顯示小工具。有時候系統會在記憶體中快取 ComplicationData，有時是由錶面程式庫序列化。序列化任何相關的 tapAction 時，如果發生這種情況，ComplicationData.tapActionLostDueToSerialization 會傳回 true，且錶面應以不同方式呈現小工具 (例如顯示為灰色或半透明)，以表示使用者不可輕觸。系統會盡快將更新後的 ComplicationData 傳送至 tapAction。

  • 部分 ComplicationData 不應長時間快取，為支援這一點，我們已新增更通用的功能 ComplicationDataTimeline。這可以用來提供一系列有時間限制的 ComplicationData，以便傳遞到可以自動進行快取及更新的錶面上。例如今天的不同時段的天氣預報，或是多個即將到來的日曆活動。ComplicationRequestListener 擴充了新方法 onComplicationDataTimeline，供您用來傳回這項資料。

  • 我們擴充了 DefaultComplicationDataSourcePolicy，方便您指定 ComplicationType 用於主要和次要資料來源。

  • 我們新增了對同步小工具供應商的支援，其中小工具將以高於一般水平的頻率持續更新，當錶面可見並且處於非環境狀態時，最高更新頻率達每秒一次。「注意」：由於記憶體壓力問題，同步小工具供應程式的使用可能會受到限制。

  • 對 PendingIntentTapListener 的變更可能已還原，因為我們已解決架構中的基本問題 (按下主畫面按鈕後 5 秒內錶面仍無法啟動活動)。

API 變更

  • ComplicationData.isCached 已變更為 tapActionLostDueToSerialization；當系統要確定是否應以不同方式轉譯小工具版位，來指出版位不可輕觸時，後者會更有用(I6de2f)。
  • 將 ComplicationDataTimeline 新增至 wear-complication-data-source。這可以用來提供一系列有時間限制的 ComplicationData，以便傳遞到可以自動進行快取及更新的錶面上。例如今天的不同時段的天氣預報，或是多個即將到來的日曆活動。ComplicationRequestListener 擴充了新方法 onComplicationDataTimeline，供您用來傳回這項資料。有新的 Kotlin 包裝函式 SuspendingTimelineComplicationDataSourceService，用來停權資料來源服務。(Idecdc)
  • 新增 PendingIntentTapListener 及 WatchFaceControlClient.getPendingIntentForTouchEvent。這可以協助需要啟動意圖以回應輕觸動作的錶面解決以下問題：使用者輕觸主畫面按鈕後，架構會阻止在 5 秒內啟動新活動 (I98074)。
  • 引入每個錶面 ComplicationData 的快取。這麼做的用意是允許錶面在載入期間顯示最終的小工具資料值，直到系統有機會更新為止。有一個新的 API 方法 WatchFaceControlClient.hasComplicationCache，適用於原始設備製造商 (OEM)。這可能會影響系統傳送小工具到錶面的策略。此外，ComplicationData 具有 isCached 屬性，建議以不同方式算繪快取的小工具，因為 tapAction 無法快取，且在快取小工具中為 null。(I404b0)。
  • 現在可以透過 WatchState.watchFaceInstanceId 取得錶面的執行個體 ID。大部分的錶面不需要使用這項屬性，但如果錶面狀態未儲存在結構定義中，就必須使用這個索引鍵來識別錶面例項。為方便支援這項功能，現在可以在呼叫 WatchFaceControlClient.createHeadlessWatchFaceClient 時提供 ID。(I1ff98)
  • 擴充 DefaultComplicationDataSourcePolicy，可設定主要、次要供應商和備用系統供應商的預設 ComplicationTypes。ComplicationSlot.defaultDataSourceType 現已淘汰 (If0ce3)。
  • ComplicationSlot.configExtras 現在可以變更，而且在呼叫 EditorSession.openComplicationDataSourceChooser() 之前都可以更新。(I6f852)
  • 新增 WatchFace.setComplicationDeniedDialogIntent 及 setComplicationRationaleDialogIntent。系統在要求小工具權限之前會啟動這些意圖以顯示對話方塊，此外，系統還會顯示另一個對話方塊，說明在權限遭拒時編輯小工具所需的權限 (供應商選擇工具無法開啟，因此需要顯示對話方塊) (I3a29c)。
  • 現在可以在 XML 中定義 UserStyleSchema 和 ComplicationSlots。這可簡化錶面建構功能，並加快 WatchFaceMetadataClient 查詢的速度，因為這類查詢不需要與服務繫結而取得中繼資料。(I85bfa)
  • 已新增 InteractiveWatchFaceClient.supportsPendingIntentForTouchEvent，以便用戶端判斷錶面是否支援 getPendingIntentForTouchEvent。(I0b917)
  • WatchFaceMetadataClient 及 ListenableWatchFaceMetadataClient 不再是實驗版，可用來盡量高效地取得錶面中繼資料，無需開啟錶面繫結器 (Ibb827)。
  • 新增同步小工具供應商的支援，小工具的更新頻率高於正常頻率，當錶面可見並且處於非環境狀態時，最高更新頻率達每秒一次。如要使用這個供應商，必須在資訊清單中加入新的 androidx.wear.watchface.complications.data.source.SYNCHRONOUS_UPDATE_PERIOD_SECONDS 中繼資料標記並覆寫 onSynchronousComplicationRequest。視資料來源的性質而定，可能還必須覆寫 onStartSynchronousComplicationRequests 及 onStopInteractiveComplicationRequests，以便在小工具進出互動模式下獲取通知。(I8fe9d)

1.0 版本

1.0.1 版本

2022 年 2 月 9 日

發布 androidx.wear.watchface:watchface-*:1.0.1。1.0.1 版包含以下修訂項目。

修正錯誤

  • 修正 PhotoImageComplicationData tapAction 的錯誤 正確處理 (I1cc30)

1.0.0 版本

2021 年 12 月 1 日

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

1.0.0 的主要功能

androidx.wear.watchface 套件是建議的最新程式庫，用於開發 WearOS 錶面。相較於舊版穿戴式裝置支援程式庫，這個版本推出了許多新功能。

  • 程式庫直接支援使用者樣式 (例如變更調色盤、指針的樣式、小時標記的外觀等) (請參閱 androidx.wear.watchface.style)。現在使用 androidx.wear.watchface.editor 可以更輕鬆地開發錶面編輯器，而且無須編寫任何額外程式碼，即可透過系統隨附應用程式編輯錶面。
  • 應用最佳做法。這個程式庫會針對小工具自動產生螢幕閱讀器內容標籤 (您也可以自行新增標籤)，而且當電池電量不足且無法充電時，影格速率會自動降低以延長電池使用壽命。
  • 減少了開發錶面所需的程式碼，尤其小工具數量，它們將許多樣板移至程式庫。

修正錯誤

  • 修正 EditorSession.userStyle.compareAndSet (I6f676)
  • 修正錶面的短期延遲 (Iffb97)
  • 在 UI 執行緒中分配 InteractiveWatchFaceImpl.onDestroy (I83340)
  • 修正廣播接收器的多個問題 (I7d25f)

1.0.0-rc01 版本

2021 年 11 月 3 日

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

修正錯誤

  • 修正因流程遷移而中斷的 dump() (由 adb shell dumpsys 呼叫)。(087cf9e)

  • 確保 writeDirectBootPrefs 的正確排序。我們希望一律在 initStyleAndComplications 之後執行 writeDirectBootPrefs，或者我們可能延遲 UI 執行緒 init (37650ac)。

  • 請務必呼叫 Renderer.onDestroy。如果已建立轉譯器，但 WF init 尚未完成且呼叫了 Engine.onDestroy，則必須呼叫 Renderer.onDestroy (f9952dc)。

  • 最佳化/修正為 isBatteryLowAndNotCharging。此修補程式會提前開始 isBatteryLowAndNotCharging 的初始化設定，這表示使用者可以與 createWatchFace 並行執行這項作業。此外，我們現在可以監聽 ACTION_POWER_DISCONNECTED。(ddffd80)

  • InteractiveWatchFaceClientImpl.isConnectionAlive 在關閉後將變為 false (ab9774e)

1.0.0-beta01 版

2021 年 10 月 27 日

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

1.0.0-alpha24 版本

2021 年 10 月 13 日

發布 androidx.wear.watchface:watchface-*:1.0.0-alpha24。1.0.0-alpha24 版包含以下修訂項目。

API 變更

  • 套件 androidx.wear.watchface.complications 中的類別已移至新的 wear:watchface:watchface-complications 專案。請注意，這表示您無法包含這個程式庫以及先前的任何 Alpha 版 wear:watchface:watchface-complications-data，因為您會收到類別重複的錯誤訊息。(I97195)。
  • Renderer.dump 已重新命名為 Renderer.onDump，並已透過 @UiThread 加上註解。(I44845)
  • InteractiveWatchFaceClient.addWatchFaceReadyListener 已重新命名為 addOnWatchFaceReadyListener，而 removeWatchFaceReadyListener 已重新命名為 removeOnWatchFaceReadyListener。(I48fea)
  • EditorSession 的 getComplicationsPreviewData 及 getComplicationsDataSourceInfo 不再是停權函式，而是 StateFlow<> 屬性且值初始為空值。已從 ListenableEditorSession 移除 getListenableComplicationPreviewData 和 getListenableComplicationsProviderInfo，並改用基礎類別中的新 StateFlow<> 物件。如果您需要監聽 Java 程式碼中的變更，請考慮使用 androidx.lifecycle.FlowLiveDataConversions.asLiveData 來轉換成 LiveData<> (Ic5483)。

1.0.0-alpha23 版本

2021 年 9 月 29 日

發布 androidx.wear.watchface:watchface-*:1.0.0-alpha23。1.0.0-alpha23 版包含以下修訂項目。

新功能

錶面程式庫現在已經是一個獨立的程式庫群組，因此這些程式庫已移到新位置，您必須按照下列方式更新 Gradle 匯入作業：

舊版 新影片
androidx.wear:wear-complications-data androidx.wear.watchface:watchface-complications-data
androidx.wear:wear-complications-data-source androidx.wear.watchface:watchface-complications-data-source
androidx.wear:wear-watchface androidx.wear.watchface:watchface
androidx.wear:wear-watchface-complications-rendering androidx.wear.watchface:watchface-complications-rendering
androidx.wear:wear-watchface-client androidx.wear.watchface:watchface-client
androidx.wear:wear-watchface-client-guava androidx.wear.watchface:watchface-client-guava
androidx.wear:wear-watchface-data androidx.wear.watchface:watchface-data
androidx.wear:wear-watchface-editor androidx.wear.watchface:watchface-editor
androidx.wear:wear-watchface-editor-guava androidx.wear.watchface:watchface-editor-guava
androidx.wear:wear-watchface-guava androidx.wear.watchface:watchface-guava
androidx.wear:wear-watchface-style androidx.wear.watchface:watchface-style

API 變更

  • 將各自獨立的 androidx.wear 錶面和小工具程式庫遷移至 androidx.wear.watchface 程式庫群組。(b25f3c0)
  • 已新增 EditorRequest.canWatchFaceSupportHeadlessEditing，讓客戶瞭解錶面編輯器是否支援無標題編輯功能。請注意，這樣做會有一些偽陰性，因為 asop/1756809 已新增支援功能，但可為所有未來錶面傳回正確的值。(ca55590)。
  • 轉譯器現在採用 dump() 方法，可覆寫該方法以將自訂資料新增至 ABD shell dumpsys 活動服務 WatchFaceService 產生的資訊。(95235f9)
  • InteractiveWatchFaceClient.addWatchFaceReadyListener 現在會先指定執行工具。(563ac2f)
  • 現已移除 StateFlowCompatHelper。請改用 asLiveData (androidx.lifecycle.asLiveData) (bd35d3)。
  • CurrentUserStyleRepository.userStyle 不再是可變動項目。(I44889)
  • WatchFaceReadyListener 已重新命名為 OnWatchFaceReadyListener (Ic12a9)。

修正錯誤

  • 利用 InteractiveInstanceManager.deleteInstance 呼叫 onDestroy，這是必要步驟，可確保 InteractiveWatchFaceImpl 獲得垃圾收集 (fce4af8、b/199485839)。