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-alpha07 版

2025 年 4 月 23 日

發布 androidx.wear.watchface:watchface-*:1.3.0-alpha07。1.3.0-alpha07 版包含這些修訂項目。

新功能

• 您可以定義錶面的 UserStyle 結構定義，並在 XML 中定義 ColorUserStyleSetting。

API 變更

• 使用 Kotlin 2.0 發布的專案需要使用 KGP 2.0.0 以上版本。(Idb6b5)。
• 新增錶面推送 API，讓 Wear OS 應用程式可透過程式輔助方式在手錶上安裝錶面。

修正錯誤

• 使用 1.3.0-alpha06 的疊加元件供應商，建議升級至新版，因為 WearOS 下一個版本已修正 ComplicationDataSourceUpdateRequester 的當機錯誤。

1.3.0-alpha06 版

2025 年 3 月 26 日

發布 androidx.wear.watchface:watchface-*:1.3.0-alpha06。1.3.0-alpha06 版包含這些修訂項目。

新功能

• Wear 錶面 API (watchface、watchface-client、watchface-client-guava、watchface-complications-rendering、watchface-data、watchface-editor、watchface-editor-guava 和 watchface-style) 已淘汰，改用 Wear 錶面格式，並最終會從 AndroidX 中移除。小工具 API 並未淘汰，仍會保留。(Ice960)
• 小工具 API 現在可直接與 WearSDK 通訊，由於 IPC 跳躍次數減少，因此效率更高。

1.3.0-alpha05 版

2025 年 1 月 15 日

發布 androidx.wear.watchface:watchface-*:1.3.0-alpha05。1.3.0-alpha05 版包含這些修訂項目。

新功能

錶面通常會讓使用者使用 ListUserStyle 選取顏色。雖然這麼做可行，但透過藍牙將圖示傳送至隨附編輯器的效率不高，因此我們引進了 ColorUserStyleSetting，其中酬載是每個樣式中一或多個顏色的清單，且線路格式更精簡。

我們新增了原始設備製造商 (OEM) 專屬功能，可讓 OEM 小工具供應商在 ComplicationData 中新增額外內容，供 OEM 錶面使用。

API 變更

• UserStyleSetting 和 UserStyleOption 類別現在都有建構工具，這是建構這類類別的建議方式。(Iacd03)
• 支援在 ComplicationData 中傳遞額外項目。這項功能適用於原始設備製造商 (OEM)，因為他們同時控制小工具供應器和接收錶面。您必須具備 com.google.android.wearable.permission.COMPLICATION_EXTRAS 權限，才能設定額外項目。(I4e3b2)。
• 錶面通常會讓使用者使用 ListUserStyle 選取顏色，每個 ListOption 都有對應的圖示。UserStyle 架構會透過藍牙傳送，因此請務必縮減架構大小，否則如果因所有圖示而提供數十種顏色選項，可能會造成問題。為協助您完成這項操作，我們新增了 ColorUserStyleSetting，其中的選項包含顏色清單，而非圖示，因此更加精簡。(Ib542e)。
• ColorUserStyleSetting 和 ColorOption 需要使用 API 34。(I8771d)

修正錯誤

• 這個程式庫現在使用 JSpecify 空值註解，這是類型用途。Kotlin 開發人員應使用下列編譯器引數，確保正確使用方式：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版起的預設值)。(Ifd363、b/326456246)。

1.3.0-alpha04 版本

2024 年 9 月 18 日

發布 androidx.wear.watchface:watchface-*:1.3.0-alpha04。1.3.0-alpha04 版包含這些修訂項目。

新功能

• 新增對 UserStyleSettings 和 UserStyleOptions 中圖示的延遲載入支援功能，這可提升錶面載入效能。(Iaf43d)。
• 新增選項，可透過新的 Watchface.setUpdateScreenshotOnConfigurationChange 在系統設定變更時 (例如語言代碼變更) 擷取更新的螢幕截圖。這項設定預設為關閉 (I765a1)。

修正錯誤

• 移除新平台 API 存取權的手動設定，因為在使用 AGP 7.3 以上版本 (例如 R8 3.3 版) 的 R8 時，以及在使用 AGP 8.1 以上版本 (例如 D8 8.1 版) 的所有版本時，這項操作會透過 API 模擬功能自動執行。建議未使用 AGP 的用戶端更新至 D8 8.1 以上版本。詳情請參閱這篇文章。(Ia60e0、b/345472586)

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 版包含這些修訂項目。

新功能

• 我們現在使用參照相等性比較 best 和 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 開始，WearOS 將新增對 SystemDataSources.DATA_SOURCE_HEART_RATE 的支援。此小工具僅支援 SHORT_TEXT 小工具，但建議 ComplicationSlot 也接受 SMALL_IMAGE，因為原始設備製造商可能會選擇提供健康應用程式捷徑，而非即時值。(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 和 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 將能夠判斷小工具要求是否來自供應商資訊清單中的錶面，該清單是由供應商資訊清單中的 android.support.wearable.complications.SAFE_WATCH_FACES 中繼資料定義，並由 ComplicationRequest#isForSafeWatchFace 提供。供應商必須具備 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 定義，因此任何依賴 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)
• 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)
• 從列舉 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)。
• 我們已在 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 將能夠判斷小工具要求是否來自供應商資訊清單中的錶面，該清單是由供應商資訊清單中的 android.support.wearable.complications.SAFE_WATCH_FACES 中繼資料定義，並由 ComplicationRequest#isForSafeWatchFace 提供。供應商需要 com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE 權限才能接收 TargetWatchFaceSafety.UNKNOWN 以外的任何內容。

• 另外，您也可以使用 Android T CustomValueUserStyleSetting2，最多可容納 12.5kb。CustomValueUserStyleSetting 的先前限制為 1kb。雖然大小限制已提高，但建議錶面開發人員將資料保持在較小的大小，因為設定會在編輯期間透過藍牙傳送，而藍牙頻寬有限。

API 變更

• 我們已在 GlesRenderer 和 GlesRenderer2 中新增選用參數 eglContextAttribList，讓您設定傳遞至 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 的先前限制為 1kb。(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 版本以來的重要異動

更強大的編輯功能：

• 我們加入了階層式架構的支援，讓編輯器使用者介面可以設定樣式的階層。您現在可以在錶面和隨附編輯器中指定個別的使用圖示。
• 可選擇啟用多個錶面執行個體，每個執行個體都有一個跨所有 API 介面使用的專屬 ID。
• 您現在可以為 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，讓您參考互動智慧搜尋之後獲知下一個互動智慧搜尋，其中小工具的任何欄位可能會隨時變更。這可用於在內部安排頁框以進行小工具更新。例如，如果錶面通常每分鐘更新一次，設定秒錶小工具會導致每秒更新一次。(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)。