【文章翻譯】What’s new in Flutter 3.38

【文章內容使用 Gemini 2.5 Flash 自動翻譯產生】

寫更少，看更多，建構更快

介紹

歡迎回到我們的定期季度發佈，Flutter 3.38。此更新旨在透過點符號簡寫和 Widget 預覽的更新來提高您的生產力並完善開發者體驗。感謝我們的社群，此版本總共包含來自 145 位獨特貢獻者的 825 次提交，其中 37 位是首次貢獻者。讓我們深入探討此版本中的內容。

點符號簡寫

撰寫更簡潔的 Dart 程式碼！我們很高興地宣布一項新的 Dart 功能——點符號簡寫！簡寫可以讓您省略 Dart 可以推斷的型別，從而減少樣板程式碼。

例如，您可以使用簡寫來撰寫 .start 而不是 MainAxisAlignment.start。

// With shorthands
Column(
  mainAxisAlignment: .start,
  crossAxisAlignment: .center,
  children: [ /* ... */ ],
),

// Without shorthands
Column(
  mainAxisAlignment: MainAxisAlignment.start,
  crossAxisAlignment: CrossAxisAlignment.center,
  children: [ /* … */ ],
),

這也適用於具名建構函式！您可以撰寫 .all 而不是 EdgeInsets.all：

Padding(
  padding: .all(8.0),
  child: Text('Hello world'),
),

此功能在 Dart 3.10 和 Flutter 3.38 中預設啟用。如需更多資訊，請查看 dart.dev 上的 點符號簡寫 頁面。您也可以在 Dart 3.10 發行部落格 文章中閱讀有關此內容及更多資訊（例如 Dart 鉤子！）。

網頁

網頁開發組態檔

flutter run 命令現在支援網頁設定的組態檔。這使您可以在專案根目錄的 web_dev_config.yaml 檔案中指定主機、埠、憑證和標頭資訊。將檔案提交到版本控制，以便您的團隊中的每個人都使用相同的設定進行除錯。如需更多資訊，請造訪 設定網頁開發組態檔。

網頁開發代理設定

除了現有的命令列旗標之外，網頁開發組態檔還支援新的代理設定。代理設定可以將對配置路徑的請求轉發到另一個伺服器。這使得開發連接到相同主機上動態端點的網頁用戶端變得更容易。

有關代理設定的詳細資訊也在 設定網頁開發組態檔 中。

擴展網頁熱重載支援

當使用 -d web-server 運行並在瀏覽器中開啟 Flutter 應用程式的連結時，有狀態熱重載現在預設啟用。這甚至適用於同時連接多個瀏覽器。

與 -d chrome 一樣，此功能可以使用 --no-web-experimental-hot-reload 旗標暫時禁用。禁用此功能的能力將在未來的版本中移除，因此，如果您在開發工作流程中遇到問題，請使用 Dart 的 網頁熱重載問題範本 提交錯誤。如需更多資訊，請參閱 網頁熱重載文件。

框架

此版本包含許多強大的新功能和框架改進，為開發人員提供對進階 UI、導航和平台互動的更精細控制。

開發人員現在在建立彈出視窗、對話框和其他浮動 UI 元素時擁有更大的權力，透過 OverlayPortal。現在可以使用 OverlayPortal.overlayChildLayoutBuilder (#174239) 在 Widget 樹中向上渲染任何 Overlay 中的子 Widget，從而更容易顯示應用程式範圍的通知或需要脫離其父 Widget 的佈局限制的其他 UI。底層的 Overlay.of 方法也變得更加健壯和高效 (#174315)。

為了獲得更現代的 Android 導航體驗，MaterialApp 中現在預設啟用預測性返回路由轉換 (#173860)。當使用者執行返回手勢時，他們現在會看到主螢幕的預覽，因為當前路由會動畫離開。此外，預設頁面轉換已從 ZoomPageTransitionsBuilder 更新為 FadeForwardsPageTransitionsBuilder，以反映原生行為。

此版本還深化了桌面整合。在 Windows 上，開發人員現在可以存取連接顯示器的列表，並查詢每個顯示器的詳細屬性，例如解析度、刷新率和實體大小 (#164460)。這使得能夠建立具有複雜視窗管理功能的應用程式。

最後，框架本身現在更具彈性。Widget 生命週期回呼中發生的錯誤（例如 didUpdateWidget）現在處理得更優雅，防止它們在元素樹中導致連鎖故障 (#173148)。ResizeImage 現在正確實作相等性，這透過確保相同的 ResizeImage 供應商被視為相同，使圖片快取和比較更具可預測性 (#172643)。

在網頁上，UI 優化持續進行，修復了 RSuperellipse 以防止當圓角半徑大於 Widget 本身時的渲染錯誤 (#172254)，相反，這種情況將被處理以產生預期的藥丸形狀。

對於國際使用者，偵測瀏覽器偏好區域設定現在更為穩健。引擎現在使用標準的 Intl.Locale 網頁 API 來解析瀏覽器語言，取代了以前手動且更脆弱的實作 (#172964)。此變更導致更可靠的區域設定偵測和為全球受眾提供更好的體驗。

解決了一個 Android 特定的錯誤 (#171973)，主要影響帶有硬體鍵盤的三星設備。以前，在使用者與 TextField 互動後，Android 輸入法編輯器 (IME) 可能會卡在過時狀態。這導致 IME 錯誤地攔截「Enter」或「Space」鍵盤按鍵，從而阻止非文字 Widget（例如 Checkbox 或 Radio 按鈕）接收事件。此修復確保在文字連接關閉時 InputMethodManager 會正確重置，清除 IME 的過時狀態並恢復使用者可預測的硬體鍵盤互動。

Material 和 Cupertino 更新

Material 和 Cupertino 函式庫持續發展，專注於 API 一致性和優質使用者體驗。此版本帶來了主要的 API 遷移、新的 Widget 功能和眾多改進，使建構美觀、實用的 UI 更加簡單。

在 MaterialState 棄用的基礎上，此版本繼續內部遷移到更統一的 WidgetState。這提供了一種一致、富有表現力的方式來定義 Widget 在不同互動狀態（例如按下、懸停或禁用）下的外觀，並且對現有應用程式無需更改。此遷移已應用於各種 Widget 及其主題，包括 IconButton、ElevatedButton、Checkbox 和 Switch (#173893)。新的 API 還增加了功能和靈活性；例如，IconButton 現在包含一個 statesController 屬性 (#169821)，允許程式化控制其視覺狀態，為更多自訂和互動式設計開啟了大門。

此版本還引入了幾項新功能和便利的 API。Badge.count 建構函式現在包含一個 maxCount 參數 (#171054)，可輕鬆限制顯示計數（例如，顯示「99+」而不是「100」）。

為了更精細的手勢控制，InkWell Widget 現在具有 onLongPressUp 回呼 (#173221)，對於僅在使用者抬起手指時才應完成觸發動作非常有用。

Cupertino 函式庫也持續朝著更好的 iOS 保真度邁進。CupertinoSlidingSegmentedControl 加入了 isMomentary 屬性 (#164262)，允許控制項觸發動作而不保留選取。為了更好地符合原生 iOS 行為，CupertinoSheet 現在在完全展開時向上拖動時具有微妙的「拉伸」效果 (#168547)。

最後，此版本充滿了優化，提升了核心組件的行為。重點包括修復 DropdownMenuFormField 以在表單重置時正確清除其文字欄位 (#174937)，以及更新 SegmentedButton 以改進焦點處理 (#173953) 並確保其邊框正確反映 Widget 的狀態 (#172754)。

解耦 Material 和 Cupertino

我們一直在為將 Material 和 Cupertino 函式庫從框架中解耦做很多規劃。以下列表包含一些最近發佈的設計文件的討論。

改進 flutter/packages 的發佈流程，這將在解耦後包含 Material 和 Cupertino。

• 狀態：已決定
• 想法：第一方套件發佈策略
• 決定：批次發佈單頁文件（公開分享）

顏色和點符號簡寫

• 狀態：已決定
• Flutter 的基本顏色集（公開分享）

解耦測試

• 狀態：進行中
• 解耦框架測試（公開分享）
• https://github.com/flutter/flutter/issues/177028

文字

• 狀態：討論中
• 從文字解耦 Flutter 設計（公開分享）

捲軸：更健壯和可預測的 Sliver

此版本帶來了許多修復，使建立複雜的捲軸佈局，特別是那些使用 SliverMainAxisGroup 和 SliverCrossAxisGroup 的佈局，更加健壯和可預測。

使用這些 Widget 組合多個 Sliver 的開發人員會發現手勢處理現在更可靠。這些群組中 Sliver 的點擊測試（用於點擊和其他指標事件）現在已正確計算，確保使用者互動行為符合預期 (#174265)。

其他幾項修復有助於在 SliverMainAxisGroup 中實現更精確的捲軸行為。使用固定標頭時的過度捲軸問題已解決 (#173349)，調用 showOnScreen 以顯示 Sliver 現在可以正常工作 (#171339)，並且內部捲軸偏移計算更精確 (#174369)。

對於建立自訂捲軸視圖的開發人員，新的 SliverGrid.list 建構函式 (#173925) 提供了從簡單子清單建立格線的更簡潔方式。

此版本還改善了複雜佈局中鍵盤和方向鍵使用者的焦點導航。在具有不同捲軸軸的巢狀捲軸視圖中（例如垂直的水平輪播列表），方向性焦點導航現在更具可預測性，防止焦點在各個區塊之間意外跳動 (#172875)。

無障礙功能：為所有使用者提供更具包容性的體驗

使應用程式對所有使用者都可存取是 Flutter 框架的基石。此版本透過為開發人員提供更多程式化控制、改善國際使用者的體驗以及優化核心 Widget 的無障礙功能來延續這一承諾。

對於開發複雜應用程式的開發人員，此版本引入了透過使用 WidgetsFlutterBinding.instance.ensureSemantics 在 iOS 上預設啟用無障礙功能的能力 (#174163)。現在除錯無障礙問題更容易了，因為 debugDumpSemanticsTree 包含了額外的文字輸入驗證結果資訊，以幫助更快地診斷問題 (#174677)。

對於基於 Sliver 的捲軸視圖中的高級無障礙功能，現在可以使用新的 SliverSemantics Widget (#167300)。就像現有的 Semantics Widget 一樣，開發人員可以在 CustomScrollView 中使用 SliverSemantics 來用特定語義資訊註釋其 Sliver 樹的一部分。這對於註釋標頭、分配語義角色以及為螢幕閱讀器向 Sliver 添加描述性標籤特別有用，為使用者提供更易於理解和存取的體驗。

最後，核心 Widget 的無障礙功能持續優化。CupertinoExpansionTile 現在預設可存取 (#174480)，而 AutoComplete Widget 現在會向使用者宣布搜尋結果的狀態 (#173480)。其他改進，例如 TimePicker 中更大的觸控目標 (#170060)，有助於提供更易於存取開箱即用的體驗。

iOS

我們很高興地確認 Flutter 完全支援最新的平台發佈：iOS 26、Xcode 26 和 macOS 26，所有這些都在 9 月發佈。這確保您可以立即開始在 Apple 最新的作業系統和工具上開發和測試您的應用程式。

您可能已經注意到 Flutter 上次發佈時為 iOS 開發人員帶來了顯著的生活品質改進，解決了一個長期以來困擾使用者的問題：在使用 flutter run 在實體設備上運行 Flutter 應用程式時，需要自動啟動 Xcode 應用程式。我們引入了一種新的部署方法，使用 Xcode 26 命令列工具 devicectl 進行應用程式安裝、啟動和除錯。此過渡消除了在部署期間調用 Xcode 應用程式的需要，並且在大多數情況下僅依賴於命令列 Xcode 建構工具。如果您遇到問題，您可以使用 flutter config --no-enable-lldb-debugging 禁用此部署方法，並請 提交問題 讓我們知道！

以前，此功能依賴於 Xcode 自動化，但在 Xcode 26 上變得不穩定且不可靠，尤其是在運行連續命令時。如果您現在正在為最新的 Apple 版本進行開發，我們強烈建議您將 Flutter 版本更新到 3.38 或更高版本。

UIScene 生命週期遷移

Flutter 3.38 包含了對 Apple 強制執行的 UIScene 生命週期 的基本支援。這是 Apple 在 WWDC25 上宣布之後的一項關鍵、主動更新：「在 iOS 26 之後的版本中，任何使用最新 SDK 建構的 UIKit 應用程式都將需要使用 UIScene 生命週期，否則它將無法啟動。」

為了確保您的 iOS Flutter 應用程式在未來的 iOS 版本中保持相容並成功啟動，需要進行遷移。

遷移 Flutter 應用程式

所有現有的 iOS Flutter 應用程式都必須遷移到新的生命週期。您有兩種方法來完成此遷移：

1. 手動遷移：遵循 Flutter 網站 上提供的手動遷移說明。
2. 自動遷移（實驗性）：啟用實驗性功能以自動處理遷移。這將在未來的版本中預設啟用。執行以下命令：

flutter config --enable-uiscene-migration

遷移 Flutter Plugin

依賴應用程式生命週期事件的 Flutter Plugin 必須更新為使用 UIScene 生命週期事件。Plugin 開發人員應參考 遷移指南。未遷移的 Plugin 將在未來的版本中顯示警告。

遷移嵌入式 Flutter（可選）

對於將 Flutter 嵌入原生主機應用程式的專案，遷移是可選的但強烈建議。使用 應用程式遷移指南 採用 Flutter 的新 UIScene API，可以為您的 Plugin 啟用場景生命週期事件，確保與 Flutter 生態系統的相容性。

Android

16KB 頁面大小相容性

升級到 Flutter 3.38 是為 Google Play 的 16 KB 頁面大小相容性要求 做準備的必備條件。從 2025 年 11 月 1 日 開始，針對 Android 15 及更高版本的應用程式必須支援 16 KB 頁面。此更改確保您的應用程式在高 RAM 設備上正常運行，提供性能優勢，例如啟動速度提高 30%。Flutter 3.38 將預設 Android ndkVersion 更新為 NDK r28，這是原生程式碼實現 16 KB 支援的正確對齊所需的最低版本。

記憶體修復

Flutter 3.38 修復了 一個影響所有 Android 上的 Flutter 應用程式的嚴重記憶體洩漏。該問題（在 3.29.0 中引入）發生在 Activity 在退出時被銷毀時，如開發人員設定所配置或當 Activity 因記憶體不足而被系統殺死時。

Android 依賴項更新

通常，要找出適用於您的應用程式的 Android 依賴項的正確版本組合（包括 Gradle、Android Gradle Plugin (AGP)、Kotlin Gradle Plugin (KGP)、Java 等）可能是一個挑戰。對於 Flutter 3.38 版本，我們在我們的持續整合 (CI) 環境中測試並確認了以下 Android 依賴項版本的相容性：

• Java 17：Flutter 3.38 中 Android 開發所需的最低版本。
• KGP 2.2.20：工具鏈 已知和支援 的最大 Kotlin Gradle Plugin 版本。
• AGP 8.11.1：與 KGP 2.2.20 相容 的最新 Android Gradle Plugin 版本。
• Gradle 8.14：此版本與選定的 Java、KGP 和 AGP 版本配合使用。請注意，Gradle 8.13 是 AGP 8.11.1 所需的最低版本。

為了確保您的應用程式在 Flutter 版本之間無縫運作，我們強烈建議您在建構檔案中使用 Flutter SDK 提供的 API 等級變數。此版本配置的值為：

• flutter.compileSdkVersion (API 36)
• flutter.targetSdkVersion (API 36)
• flutter.minSdkVersion (API 24) 或更高

引擎

效能疊加層

效能疊加層已重構，使其在 Skia 和 Impeller 後端上都更高效，減少了其渲染時間。這表示您可以使用更少的開銷獲得更準確的效能資料。(#176364)

Vulkan 和 OpenGL ES

Vulkan 和 OpenGL ES 後端的多項修復和改進提高了在更廣泛設備上的穩定性和效能。這包括更好地處理管道快取 (#176322)、柵欄等待器 (#173085) 和圖片佈局轉換 (#173884)。

渲染器統一

統一 CanvasKit 和 Skwasm 渲染器的工作仍在繼續。此版本包含重要的重構，以在兩者之間共享更多程式碼，這將在未來帶來更一致的體驗和更快的開發 (#174588)。

執行緒合併

已從 iOS 和 Android 中移除選擇退出執行緒合併的功能。如需更多資訊，請查看 大執行緒合併 影片。

DevTools 和 IDE

實驗性 Widget 預覽 — 更新

Flutter 3.35 引入了 Widget 預覽，這是一個實驗性功能，可供社群早期回饋。Flutter 3.38 版本對 Widget 預覽帶來了顯著改進，包括：

• IDE 整合：我們的 VSCode 和 Intellij / Android Studio Plugin 都已更新，並初步支援 Widget 預覽。您現在可以直接在 IDE 中查看預覽，以獲得更流暢的開發體驗。

Widget Previews embedded in VSCode.

在 IDE 中使用時，Widget 預覽環境預設配置為根據當前選定的原始程式檔篩選顯示的預覽：

• Widget 預覽環境主題和控制改進：Widget 預覽環境現在支援淺色和深色模式，以及自訂 IDE 顏色方案以符合您的開發環境。Widget 預覽環境中的控制項也已調整為使用更少的空間，為渲染預覽留下更多空間。

Custom theming support for the Widget Previews environment.

• 預覽可擴展性：Preview 註解類別不再標記為 final，現在可以擴展以建立自訂 Preview 註解，從而減少常見預覽類型的樣板程式碼。

An example of a custom BrightnessPreview annotation.

• MultiPreview 支援：新的 MultiPreview 基礎類別允許從單個自訂註解建立多個預覽變體。

• 預覽群組：Preview 類別中的新 group 參數允許將相關預覽分組。

An example of multiple “Brightness” previews in a preview group.

• 減少 @Preview 註解引數的限制：私有常數現在支援作為 Preview 註解的引數。函式引數（例如 wrapper 和 theme）仍然需要具有公共、靜態可存取的名稱。

Widget 預覽仍是一個實驗性功能，您的回饋對於塑造其未來至關重要。API 和使用者體驗尚不穩定，將隨著我們從您那裡學習而改變。

根據早期回饋，計劃進行更多增強功能以改善 Widget 預覽體驗，包括：

1. Flutter DevTools Widget Inspector 支援：Widget Inspector 正在更新以支援檢查 Widget 預覽環境中的預覽。我們計劃將 Inspector 直接嵌入 Widget 預覽器中，使其無論您的開發環境如何都易於存取。
2. IDE 中的多專案支援：Widget 預覽器目前僅支援顯示單個專案或 Pub 工作區中包含的預覽。我們正在積極研究支援具有多個 Flutter 專案的 IDE 會話的選項（議題 #173550）。
3. 啟動效能改進：正在調查效能改進的機會，以減少初始啟動時間，包括：

• 首次運行後啟動預編譯的 Widget 預覽環境
• 並行化預覽偵測邏輯以更好地處理大型專案

要開始使用，請查看文件並告訴我們您的想法！

• 閱讀文件：Flutter Widget 預覽入門（實驗性）
• 提供回饋：在 Flutter GitHub 儲存庫 中提交問題和功能請求。
• 了解更多：如需深入了解技術細節，請參閱 Flutter Widget 預覽架構文件。

重要提示：已知 Widget 預覽器在 flutter pub get 後可能會崩潰或停止更新。如果您遇到此問題，請在您的專案中運行 flutter pub get 並重新啟動您的 IDE。請參閱 #178317 了解詳細資訊。

DevTools 更新

Flutter 3.38 包含了對 2025 年 DevTools 使用者調查中使用者提出的主要痛點的一些修復，包括：

網路面板改進

• 使面板記錄網路流量的時間更容易理解。(#9495)
• 修復了複製貼上網路請求的問題。(#9472、#9482、#9485、#8588)

Flutter Inspector 修復

• 修復了選取 Widget 有時會開啟底層框架原始碼而不是使用者原始碼的錯誤。(#176530)
• 修復了偶爾阻止與 Inspector 面板頂部按鈕互動的錯誤。(#9327)

棄用和重大變更

此版本包含幾個重要的棄用和重大變更，作為持續努力現代化和改進 Flutter 框架的一部分。

已進行了主要的建構和工具鏈更改，這可能會影響自訂建構指令碼。Flutter SDK 根目錄下的版本檔案已移除，取而代之的是位於 bin/cache 中的新 flutter.version.json 檔案 (#172793)。此外，AssetManifest.json 檔案不再預設生成 (#172594)。

其他值得注意的更改包括：

• 為實現更可預測的行為，包含動作的 SnackBar 將不再自動關閉 (#173084)。
• OverlayPortal.targetsRootOverlay 建構函式已棄用，取而代之的是更靈活的 OverlayPortal(overlayLocation: OverlayChildLocation.rootOverlay)。
• CupertinoDynamicColor 上的幾個屬性，例如 withAlpha 和 withOpacity，現在已棄用，取而代之的是標準的 Color 方法 (#171160)。
• Flutter 3.38 要求 Java 17 作為 Android 的最低版本，與 Gradle 8.14（2025 年 7 月發布）的最低要求相符。

有關這些和其他變更的更多詳細資訊和遷移指南，請查看 重大變更頁面。

結語

Flutter 3.38 專注於讓您的日常開發更快、更愉快。這些增強功能旨在簡化您的建構方式。我們非常感謝為此版本做出貢獻的每位社群成員的辛勤工作和回饋。

有關所有更改的完整列表，請務必查看詳細的重大變更和發行說明。要免費提升您的生產力，只需運行 flutter upgrade！

---

Flutter 3.38 的新功能最初發佈在 Flutter 上的 Medium，人們在那裡透過突出顯示和回應這個故事來繼續討論。