Wear Watchface

宣告依附元件

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

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

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"
}

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-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() 建立使用者定義類型，並傳遞至各種 create 方法做為參數。(If8a99)。
• 我們已將 getUserStyleFlavors 新增至 InteractiveWatchFaceClient，主要是為了對原始設備製造商 (OEM) 的客戶感興趣。(I0f5d8)。
• GlesRenderer2 現在有建構函式超載，可讓您指定要與 eglChooseConfig 一起嘗試的屬性清單。比方說，您可以先嘗試使用反鋸齒設定，並視需要改回設定。(I1ba74)。
• 自 Android U 起，WearOS 將新增對 SystemDataSources.DATA_SOURCE_HEART_RATE 的支援。這個小工具只保證支援 SHORT_TEXT 小工具，但建議 ComplicationSlot 也接受 SMALL_IMAGE，因為原始設備製造商 (OEM) 可能會選擇提供其健康應用程式的捷徑，而非即時值。(I34223)。
• 我們新增了 Android U 的 METADATA_KEY_CONFIG_RESTORE_SUPPORTED，用於控制系統從小工具資料來源的備份還原系統時，使用 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 和 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 開始，WearOS 將支援預設的天氣系統小工具。

API 變更

• 為小工具新增天氣預設系統備用系統。(Ia0994)。
• 這個修補程式會新增 WatchFaceRuntimeService 和 WatchFaceControlClient.createWatchFaceRuntimeControlClient 以及 guava 包裝函式。這樣就能為錶面執行階段新增支援功能，這是一種特殊的錶面，可從其他套件載入定義。WearOS 目前僅支援 Android 錶面格式的執行階段。(I2799f)。
• 本修補程式為 aosp/2636578 的後續追蹤，我們會重新命名 int def，因此任何依附於 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 提供心率和每日步數。SensorGateway 介面已從公用 API 中移除。(I55b84)。
• 將 StateEntryValue 重新命名為 DynamicDataValue，並更新狀態 API 以使用 DynamicDataKey。(If1c01)。
• 新增 AppDataKey，用於存取應用程式推送狀態；新增用於存取平台資料的 PlatformDataKey；在 StateStore 中新增命名空間支援。(I7985e)。
• 已從 DynamicTypeEvaluator 中移除 enable 個方法 (共 disablePlatformSource 個)。呼叫端應負責更新。(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，但偏好 createRemoteWatchFaceView 以 SurfaceControlViewHost 為基礎，並允許呼叫端從錶面嵌入錶面 (在用戶端呼叫 RemoteWatchFaceViewHost#renderWatchFace 時顯示)。(Ib311d)。
• 我們已將 renderWatchFaceToSurface 新增至 InteractiveWatchFaceClient、HeadlessWatchFaceClient 和 EditorSession。一般而言，這比算繪為點陣圖時更有效率。(Ieacad)。
• ObservableStateStore 已重新命名為 StateStore。(Ieb0e2)。
• 新增了 DynamicTypeEvaluator.Builder (而非建構函式引數)，以便允許使用更多選用引數，包括現在預設為空白儲存庫的 ObservableStateStore。(I6f832)。
• 重構 DynamicTypeEvaluator 中的參數順序。(Ic1ba4)。
• 執行器已新增至 DynamicTypeEvaluator.bind 方法。(I346ab)。
• 我們已將 startEvaluation 方法新增至 BoundDynamicType，以便在動態類型繫結後觸發評估作業。(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 變更

• 我們已將選用參數 eglContextAttribList 新增至 GlesRenderer 和 GlesRenderer2，以便設定傳送至 EGL14.eglCreateContext 的 EGL14.EGL_CONTEXT_CLIENT_VERSION。(I2a83e)。
• 錶面程式庫已從 java.util.function.Consumer 遷移至 androidx.core.util.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.5 KB。「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 協同程式操作的作用變成 GC 根目錄，且會保留編輯器活動 (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 觀察色彩變更，我們新增了 OnWatchFaceColorsListener 至 InteractiveWatchFaceClient。(I490bc)。
• 我們已新增 WatchFaceColors 類別，其包含三種最醒目的錶面顏色，並為轉譯器新增了開放式方法 watchfaceColors 和 notifyWatchFaceColorsChanged，以便系統透過 WallpaperManager.getWallpaperColors 取得錶面顏色。(I3d611)。
• ShortTextComplicationData、RangedValueComplicationData、NoPermissionComplicationData (以及實驗性 DiscreteRangedValueComplicationData、GoalProgressComplicationData 和 WeightedElementsComplicationData) 現在都支援 SmallImages。如果錶面選擇顯示具有多種顏色的小工具，現在可以選擇使用多彩色 SmallImage，而先前必須使用單色圖片。(I257df)。
• 將 PreviewImageUpdateRequestedListener 重構為 Consumer<> (Ia875d)
• 用一般 Java SAM 類型 (消費者) 取代自訂單一抽象方法 (SAM) 類型 OnWatchfaceColorsListener (I0c489)
• 我們已淘汰舊版 getOrCreateInteractiveWatchFaceClient 和 listenableGetOrCreateInteractiveWatchFaceClient 方法，其未指定 PreviewImageUpdateRequestedListener。(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，這個 int 可以為範圍值提供語意含義，小工具轉譯器也能使用這個 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 之後的下一個 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)
• 在 androidx.wear.watchface.client.ComplicationSlotState 中針對 ComplicationSlot.Builder 和相應的 getter 新增 setNameResourceId 和 setScreenReaderNameResourceId (參照字串資源)。這樣一來，系統即可擷取 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 匯入作業：

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)。