行為變更：指定 Android 17 以上版本的應用程式

和先前版本一樣，Android 17 也包含可能會影響應用程式的行為變更。以下行為變更僅適用於指定 Android 17 以上版本的應用程式。如果應用程式指定 Android 17 以上版本，建議您視情況修改應用程式，以支援這些行為。

此外，無論應用程式的 targetSdkVersion 為何，請務必查看對所有 Android 17 應用程式有影響的行為變更清單。

注意： 本頁面列出部分較重要的異動。詳情請參閱 Android 17 版本資訊。

使用者體驗和系統 UI

Android 17 包含下列異動項目，旨在打造更一致、直覺的使用者體驗。

記憶體限制小工具

从 Android 17 开始，系统会对以 Android 17（API 级别 37）或更高版本为目标平台的应用的 RemoteViews 更新强制执行严格的内存限制。当应用将 RemoteViews 对象传递给 AppWidgetManager.updateAppWidget 时，system_server 会计算载荷中每个方向和大小存储桶中所有图片数据的总内存占用。如果总内存超出系统上限 (mMaxWidgetBitmapMemory)，系统会拒绝更新并抛出 IllegalArgumentException：

java.lang.IllegalArgumentException: RemoteViews for widget update exceeds maximum bitmap memory usage (used: XXXXX, max: YYYYY)

对于以 API 级别 36 或更低级别为目标平台的应用，系统会将此内存违规行为记录为警告 (Slog.w)，而不会抛出异常。

Android skills

在 GitHub 上查看

管理 AppWidget 更新和位图内存

使用 AppWidget 更新和内存 Android 技能，对 widget 位图进行降采样，删除重复的自适应图片，并确保 Glance 和传统 AppWidgetProvider widget 均符合 Android 17 RemoteViews 内存限制。

如需从 Android CLI 安装技能，请运行以下命令：

android skills add glance-appwidget-updates-and-memory

系统如何计算内存上限

系统会将活跃显示配置的 widget 位图内存预算设置为 6 * width * height 字节（1.5 * 4 * width * height，相当于全屏 ARGB_8888 缓冲区大小的 1.5 倍）。在 API 级别 37 及更高级别下，此计算包括以下两项：

• 存储在 RemoteViews.mBitmapCache 中的内存中 Bitmap 和位图支持的 Icon 对象（Icon.TYPE_BITMAP 和 Icon.TYPE_ADAPTIVE_BITMAP），例如对 setImageViewBitmap、Icon.createWithBitmap、Icon.createWithAdaptiveBitmap 或 Jetpack Glance ImageProvider(bitmap) 的调用。mBitmapCache 中每个唯一的 Bitmap 或位图支持的 Icon 实例在每个 RemoteViews 层次结构中都会被计数一次。
• URI 支持的图片（Icon.createWithContentUri、setImageViewUri 或 Glance ImageProvider(uri)）不计入 system_server 中的 RemoteViews IPC 字节上限，但 widget 宿主进程会以完整分辨率将引用的 content:// 文件解码到其自己的堆中。在通过 FileProvider URI 公开降采样图片之前，请务必先将其写入 context.cacheDir。

缓解步骤

为了确保在手机、平板电脑和可折叠设备上，微件更新不会超出内存上限，请执行以下操作：

1. 根据 WindowMetrics 计算运行时内存预算：在 API 级别 30 及更高级别，从 WindowManager.currentWindowMetrics.bounds 而不是 resources.displayMetrics 读取活动窗口边界。在多分辨率设备和可折叠设备上，displayMetrics 可能会报告非活动显示屏尺寸。将总微件图片预算估算为 6L * bounds.width() * bounds.height()，如以下示例所示：

   private const val FALLBACK_MAX_BYTES = 15_000_000L
   
   fun calculateWidgetMemoryCapBytes(context: Context): Long {
       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
           val wm = context.getSystemService(WindowManager::class.java)
               ?: return FALLBACK_MAX_BYTES
           val bounds = wm.currentWindowMetrics.bounds
           return 6L * bounds.width().toLong() * bounds.height().toLong()
       }
       val dm = context.resources.displayMetrics
       return 6L * dm.widthPixels.toLong() * dm.heightPixels.toLong()
   }
   

2. 将图片降采样到微件的可查看尺寸，并使用 RGB_565：使用 2 的幂 BitmapFactory.Options.inSampleSize 值（大小为微件的最大显示尺寸 [maxWidthDp x maxHeightDp]）解码位图，并对不透明的照片和缩略图使用 Bitmap.Config.RGB_565（每个像素 2 字节）而不是 ARGB_8888（每个像素 4 字节）。

3. 在 Jetpack Glance 中，将位图解码提升到 provideContent 之外：使用 SizeMode.Responsive 或 SizeMode.Exact 时，Glance 会针对每个尺寸分桶调用一次 provideContent lambda。在调用 provideContent 之前，在 provideGlance 中对每个共享的 Bitmap 解码一次，以便所有大小存储桶都引用 RemoteViews.mBitmapCache 中的同一 Bitmap 实例。

4. 替换图片时使用完整的 updateAppWidget 调用：在传统 AppWidgetProvider 实现中，避免调用 AppWidgetManager.partiallyUpdateAppWidget 来交换 Bitmap 或 Icon 视图。部分更新会将新操作合并到 system_server 中的现有 RemoteViews 树中，而不会逐出之前缓存的映像操作。构建完整的 RemoteViews 布局，并改为调用 updateAppWidget。

5. 提供错误后备布局：在 Jetpack Glance 中，替换 onCompositionError，以便在更新失败时呈现零位图 RemoteViews 后备。

您可以通过运行以下命令，在已连接的设备上检查微件当前的序列化位图内存用量：

adb shell dumpsys appwidget

核心功能

Android 17 包含下列異動項目，這類變更會修改或擴充 Android 系統的各種核心功能。

MessageQueue 的新無鎖定實作

从 Android 17 开始，以 Android 17（API 级别 37）或更高版本为目标平台的应用会收到 android.os.MessageQueue 的全新无锁实现。新实现可提升性能并减少丢帧，但可能会破坏反映 MessageQueue 私有字段和方法的客户端。

如需了解详情（包括缓解措施），请参阅 MessageQueue 行为变更指南。

靜態最終欄位現在無法修改

Apps running on Android 17 or higher that target Android 17 (API level 37) or higher cannot change static final fields. If an app attempts to change a static final field by using reflection, it will cause an IllegalAccessException. Attempting to modify one of these fields through JNI APIs (such as SetStaticLongField()) will cause the app to crash.

無障礙設定

Android 17 進行下列變更，提升無障礙功能。

支援複雜輸入法實體鍵盤輸入的無障礙功能

This feature introduces new AccessibilityEvent and TextAttribute APIs to enhance screen reader spoken feedback for CJKV language input. CJKV IME apps can now signal whether a text conversion candidate has been selected during text composition. Apps with edit fields can specify text change types when sending text changed accessibility events. For example, apps can specify that a text change occurred during text composition, or that a text change resulted from a commit. Doing this enables accessibility services such as screen readers to deliver more precise feedback based on the nature of the text modification.

App adoption

• IME Apps: When setting composing text in edit fields, IMEs can use TextAttribute.Builder.setTextSuggestionSelected() to indicate whether a specific conversion candidate was selected.

• Apps with Edit Fields: Apps that maintain a custom InputConnection can retrieve candidate selection data by calling TextAttribute.isTextSuggestionSelected(). These apps should then call AccessibilityEvent.setTextChangeTypes() when dispatching TYPE_VIEW_TEXT_CHANGED events. Apps targeting Android 17 (API level 37) that use the standard TextView will have this feature enabled by default. (That is, TextView will handle retrieving data from the IME and setting text change types when sending events to accessibility services).

• Accessibility Services: Accessibility services that process TYPE_VIEW_TEXT_CHANGED events can call AccessibilityEvent.getTextChangeTypes() to identify the nature of the modification and adjust their feedback strategies accordingly.

隱私權

Android 17 包含下列異動，可提升使用者隱私。

已啟用 ECH (Encrypted Client Hello)

Android 17 introduces platform support for Encrypted Client Hello (ECH), a TLS extension that enhances user privacy by encrypting the Server Name Indication (SNI) in the TLS handshake. This encryption helps prevent network observers from easily identifying the specific domain your app is connecting to.

For apps targeting Android 17 (API level 37) or higher, ECH is used for TLS connections. ECH is active only if the networking library used by the app (for example, HttpEngine, WebView, or OkHttp) has integrated ECH support and the remote server also supports the ECH protocol. If ECH cannot be negotiated, the client sends an ECH extension with randomized contents (a mechanism called ECH GREASE). See RFC 9849 for more details on how ECH GREASE works.

To allow apps to customize this behavior, Android 17 adds a new <domainEncryption> element to the Network Security Configuration file. Developers can use <domainEncryption> within <base-config> or <domain-config> tags to select an ECH mode (for example, "enabled" or "disabled") on a global or per-domain basis.

For more information, see the Encrypted Client Hello documentation.

指定 Android 17 的應用程式需要區域網路權限

Android 17 introduces the ACCESS_LOCAL_NETWORK runtime permission to protect users from unauthorized local network access. Because this falls under the existing NEARBY_DEVICES permission group, users who have already granted other NEARBY_DEVICES permissions aren't prompted again. This new requirement prevents malicious apps from exploiting unrestricted local network access for covert user tracking and fingerprinting. By declaring and requesting this permission, your app can discover and connect to devices on the local area network (LAN), such as smart home devices or casting receivers.

Apps targeting Android 17 (API level 37) or higher now have two paths to maintain communication with LAN devices: Adopt system-mediated, privacy-preserving device pickers to skip the permission prompt, or explicitly request this new permission at runtime to maintain local network communication.

For more information, see the Local network permission documentation.

Note: In Android 16, apps could opt in to local network permissions. Beginning with Android 17, enforcement is mandatory for apps that target Android 17 (API level 37) or higher.

在實體裝置上隱藏密碼

如果應用程式指定 Android 17 (API 級別 37) 以上版本，且使用者使用實體輸入裝置 (例如外接鍵盤)，Android 作業系統會將新的 show_passwords_physical 設定套用至密碼欄位中的所有字元。根據預設，這項設定會隱藏所有密碼字元。

Android 系統會顯示最後輸入的密碼字元，協助使用者確認是否輸入錯誤。不過，如果使用較大的外接鍵盤，就不太需要這麼做。此外，配備外接鍵盤的裝置通常螢幕較大，因此輸入的密碼更容易被他人看到。

如果使用者正在使用裝置的觸控螢幕，系統會套用新的 show_passwords_touch 設定。

標準簡訊動態密碼防護

從 Android 17 開始，Android 將擴大簡訊動態密碼保護功能，適用於標準簡訊 (包含動態密碼，但不使用 WebOTP 或簡訊擷取器格式的簡訊)。對於大多數指定 Android 17 (API 級別 37) 以上版本的應用程式，這些簡訊在收到後三小時內無法使用。這項延遲措施旨在防止動態密碼遭劫持。在這三小時的延遲期間，系統會保留 SMS_RECEIVED_ACTION 廣播，並篩選簡訊供應商資料庫查詢。延遲時間過後，這些應用程式就能取得簡訊。

某些應用程式 (例如預設簡訊小幫手應用程式、連結裝置隨附應用程式等) 不受這項延遲限制。所有需要讀取簡訊來擷取動態密碼的應用程式，都應改用 SMS Retriever 或 SMS User Consent API，確保功能持續運作。

注意： 無論目標 API 級別為何，所有應用程式都必須針對 WebOTP 和簡訊擷取器格式訊息，採取額外的簡訊動態密碼保護措施。詳情請參閱「所有應用程式的行為變更」說明文件中的「簡訊動態密碼保護」一節。

安全性

Android 17 對裝置和應用程式安全性進行了以下改善。

Activity 安全性

在 Android 17 中，平台持續朝向「預設安全」架構發展，推出一系列強化功能，旨在緩解高嚴重性漏洞，例如網路釣魚、互動劫持和混淆代理攻擊。開發人員必須明確選擇加入新的安全性標準，才能維持應用程式相容性並保護使用者。

對開發人員的主要影響包括：

• 強化 BAL 並改善選擇加入機制：我們正在調整背景活動啟動 (BAL) 限制，將保護措施擴展至 IntentSender。開發人員必須停止使用舊版 MODE_BACKGROUND_ACTIVITY_START_ALLOWED 常數。建議改用 MODE_BACKGROUND_ACTIVITY_START_ALLOW_IF_VISIBLE 等精細控制項，限制只有在呼叫端應用程式可見時，才能啟動活動，大幅縮小攻擊面。
• 採用工具：開發人員應使用嚴格模式和更新後的 Lint 檢查，找出舊版模式，確保能因應未來的目標 SDK 規定。

預設啟用 CT

如果應用程式指定 Android 17 (API 級別 37) 以上版本，系統會預設啟用憑證透明化 (CT)。(在 Android 16 中，CT 可用，但應用程式必須選擇加入)。

更安全的原生 DCL - C

If your app targets Android 17 (API level 37) or higher, the Safer Dynamic Code Loading (DCL) protection introduced in Android 14 for DEX and JAR files now extends to native libraries.

All native files loaded using System.load() must be marked as read-only. Otherwise, the system throws UnsatisfiedLinkError.

We recommend that apps avoid dynamically loading code whenever possible, as doing so greatly increases the risk that an app can be compromised by code injection or code tampering.

限制 CP2 資料檢視中的 PII 欄位

如果應用程式指定 Android 17 (API 級別 37) 以上版本，聯絡人供應程式 2 (CP2) 會限制資料檢視中包含個人識別資訊 (PII) 的特定資料欄。這項異動生效後，系統會從資料檢視中移除這些資料欄，進一步保護使用者隱私。受限制的資料欄包括：

• ACCOUNT_NAME
• ACCOUNT_TYPE
• ACCOUNT_TYPE_AND_DATA_SET

如果應用程式使用 ContactsContract.Data 中的這些資料欄，可以改為與 RAW_CONTACT_ID 彙整，從 ContactsContract.RawContacts 擷取這些資料欄。

在 CP2 中強制執行嚴格的 SQL 檢查

对于以 Android 17（API 级别 37）及更高版本为目标平台的应用，如果在没有 READ_CONTACTS 权限的情况下访问 ContactsContract.Data 表，Contacts Provider 2 (CP2) 会强制执行严格的 SQL 查询验证。

做出此项更改后，如果应用没有 READ_CONTACTS 权限，则在查询 ContactsContract.Data 表时会设置 StrictColumns 和 StrictGrammar 选项。如果查询使用的模式与这些模式不兼容，则会被拒绝并导致抛出异常。

情報

Android 17 對系統智慧功能進行了下列變更。

setContentCaptureEnabled 淘汰

部分裝置預設會啟用內容擷取功能，讓裝置端 AI 功能分析畫面內容，提供智慧型體驗。

自 Android 17 起，ContentCaptureManager.setContentCaptureEnabled(boolean) API 方法已淘汰。如果應用程式指定 Android 17 (API 級別 37) 以上版本，呼叫 setContentCaptureEnabled(false) 不會再停用內容擷取功能。

如果應用程式需要繼續停用內容擷取功能，或限制系統擷取螢幕內容，請改用 FLAG_SECURE 視窗版面配置參數。

如要停用內容擷取功能，請在視窗中設定 FLAG_SECURE 標記，如以下範例所示：

Kotlin

window.setFlags(
    WindowManager.LayoutParams.FLAG_SECURE,
    WindowManager.LayoutParams.FLAG_SECURE
)

Java

getWindow().setFlags(
    WindowManager.LayoutParams.FLAG_SECURE,
    WindowManager.LayoutParams.FLAG_SECURE
);

詳情請參閱 WindowManager.LayoutParams.FLAG_SECURE 參考文件。

媒體

Android 17 包含下列媒體行為變更。

背景音訊強化

Beginning with Android 17, the audio framework enforces restrictions on background audio interactions including audio playback, audio focus requests, and volume change APIs to ensure that these changes are started intentionally by the user.

Some audio restrictions apply to all apps. However, the restrictions are more stringent if an app targets Android 17 (API level 37). If one of these apps interacts with audio while it is in the background, it must have a foreground service running. In addition, the app must meet one or both of these requirements:

• The foreground service must have while-in-use (WIU) capabilities.
• The app must have the exact alarm permission and be interacting with USAGE_ALARM audio streams.

For more information, including mitigation strategies, see Background audio hardening.

裝置板型規格

Android 17 包含下列異動項目，可改善各種裝置尺寸和板型規格的使用者體驗。

平台 API 異動：在大螢幕 (sw>=600dp) 上忽略螢幕方向、大小調整和顯示比例限制

我們在 Android 16 中變更平台 API，針對指定目標 API 級別 36 以上版本的應用程式，忽略大螢幕 (sw >= 600dp) 的螢幕方向、大小調整和顯示比例限制。開發人員可以選擇不採用 SDK 36 的這些變更，但如果應用程式指定 Android 17 (API 級別 37) 以上版本，就無法再選擇不採用。

詳情請參閱「系統會忽略螢幕方向和大小調整限制」。

連線能力

Android 17 推出下列異動，提升藍牙 RFCOMM 通訊端的一致性，並與標準 Java InputStream 行為保持一致。

RFCOMM 的 BluetoothSocket read() 行為一致

For apps targeting Android 17 (API level 37), the read() method of the InputStream obtained from an RFCOMM-based BluetoothSocket now returns -1 when the socket is closed or the connection is dropped.

This change makes RFCOMM socket behavior consistent with LE CoC sockets and aligns with the standard InputStream.read() documentation, which states that -1 is returned when the end of the stream is reached.

Apps that rely solely on catching an IOException to break out of a read loop may be impacted by this change and should update the BluetoothSocket read loops to explicitly check for a return value of -1. This ensures the loop terminates correctly when the remote device disconnects or the socket is closed. For an example of the recommended implementation, see the code snippet in the Transfer Bluetooth data guide.