Flutter 3.38 版本发布了，看看有哪些新特性

介绍

欢迎回到我们定期发布的季度版本 Flutter 3.38。本次更新旨在通过点简写和 Widget 预览的更新来提升您的开发效率并优化开发者体验。感谢社区的贡献，本次版本共包含来自 145 位贡献者的 825 次提交，其中 37 位是首次贡献者。让我们深入了解一下本次版本更新的内容。

Dot shorthands

编写更简洁的 Dart 代码！我们很高兴地宣布 Dart 的一项新特性------点简写！简写允许您省略 Dart 可以推断的类型，从而减少样板代码。

例如，你可以使用简写.start来代替MainAxisAlignment.start。

less 复制代码

// 使用简写
Column ( 
  mainAxisAlignment : .start, 
  crossAxisAlignment : .center, 
  children : [ /* ... */ ], 
), 

// 不使用简写
Column ( 
  mainAxisAlignment : MainAxisAlignment.start, 
  crossAxisAlignment : CrossAxisAlignment.center, 
  children : [ /* ... */ ], 
),

这同样适用于命名构造函数！你可以.all这样写EdgeInsets.all：

arduino 复制代码

填充（
  填充：.全部（8.0），
  子元素：文本（'Hello world'），
），

Dart 3.10 和 Flutter 3.38 默认启用此功能。更多信息，请查看dart.dev 上的dot 简写页面。您还可以在 Dart 3.10 发布博文中了解更多相关内容（例如 Dart hooks！）。

web

Web 开发配置文件

该flutter run命令现在支持 Web 设置配置文件。您可以在web_dev_config.yaml项目根目录的文件中指定主机、端口、证书和标头信息。将该文件检入，以便团队中的每个人都能使用相同的设置进行调试。有关更多信息，请访问"设置 Web 开发配置文件"。

Web 开发代理设置

除了现有的命令行参数外，Web 开发配置文件还支持新的代理设置。代理设置允许将对已配置路径的请求转发到另一台服务器。这使得开发能够连接到同一主机上动态端点的 Web 客户端变得更加容易。

有关代理设置的详细信息，请参阅设置 Web 开发配置文件。

扩展了对网页热重载的支持

现在，当您在浏览器中打开 Flutter 应用的链接并运行该应用时，状态热重载功能默认启用-d web-server。即使同时连接多个浏览器，此功能也能正常工作。

与之前一样-d chrome，此功能可以使用标志暂时禁用--no-web-experimental-hot-reload。禁用此功能的功能将在未来的版本中移除，因此，如果您在开发流程中遇到问题，请使用 Dart 的Web 热重载问题模板提交错误报告。更多信息，请参阅Web 热重载文档。

框架

此版本包含框架中的许多强大的新功能和改进，使开发人员能够对高级 UI、导航和平台交互进行更精细的控制。

现在，开发者在使用 Overlay.of 创建弹出窗口、对话框和其他浮动 UI 元素时拥有了更大的控制权OverlayPortal。现在可以Overlay使用 Overlay.of 在组件树的任何上级组件中渲染子组件OverlayPortal.overlayChildLayoutBuilder（#174239），从而更轻松地显示应用范围的通知或其他需要突破父组件布局限制的 UI。底层 Overlay.of 方法也得到了增强，变得更加健壮高效（#174315）。

为了提供更现代化的 Android 导航体验，预测性返回路径过渡效果现已默认启用MaterialApp（#173860）。当用户执行返回手势时，当前路径会以动画形式消失，同时用户会看到主屏幕的预览。此外，默认页面过渡效果也已更新，以FadeForwardsPageTransitionsBuilder反映ZoomPageTransitionsBuilder原生应用的行为。

此次版本更新还深化了桌面集成。在 Windows 系统上，开发者现在可以访问已连接显示器的列表，并查询每个显示器的详细属性，例如分辨率、刷新率和物理尺寸（#164460）。这使得创建具有复杂窗口管理功能的应用程序成为可能。

最后，框架本身的容错性也得到了提升。组件生命周期回调中发生的错误（例如 get_errors( didUpdateWidget)）现在能够得到更优雅的处理，从而避免在元素树中引发级联故障（#173148）。此外，get_errors() 也正确实现了相等性判断，确保相同的提供程序得到相同的处理，ResizeImage从而使图像缓存和比较更加可预测（ #172643）。ResizeImage

在网页上，UI 的优化仍在继续，修复了RSuperellipse当圆角半径大于小部件本身时出现的渲染错误（#172254），现在，这种情况将被处理，以按预期生成药丸形状。

对于国际用户而言，检测浏览器首选语言环境的功能现在更加强大。引擎现在使用标准Intl.LocaleWeb API 来解析浏览器语言，取代了之前手动且较为脆弱的实现方式（#172964）。这一改进带来了更可靠的语言环境检测，并为全球用户提供了更佳的体验。

一个特定于 Android 系统的漏洞（#171973）已修复，该漏洞主要影响配备硬件键盘的三星设备。此前，用户与文本框交互后TextField，Android 输入法编辑器 (IME) 可能会卡在"过期"状态。这会导致 IME 错误地拦截"回车"或"空格"键的按下，从而阻止非文本控件（例如文本框Checkbox或Radio按钮）接收到事件。此修复程序确保InputMethodManager在文本连接关闭时正确重置 IME，清除其"过期"状态，并恢复用户可预期的硬件键盘交互。

材料和库比蒂诺更新

Material 和 Cupertino 库持续发展，专注于 API 的一致性和优化的用户体验。此次版本更新带来了重要的 API 迁移、全新的组件功能以及诸多改进，让构建美观实用的用户界面变得更加轻松。

基于已弃用的旧版本MaterialState，本次版本继续推进内部向更统一的版本的迁移。这提供了一种一致且富有表现力的方式来定义控件在不同交互状态（例如按下、悬停或禁用）下WidgetState的外观，并且无需对现有应用进行任何更改。此次迁移已应用于多种控件及其主题，包括IconButton、、和（#173893）。新的 API 还增强了功能和灵活性；例如，现在包含一个属性（#169821），允许以编程方式控制其视觉状态，从而为更自定义和交互式的设计打开了大门。ElevatedButton``Checkbox``SwitchIconButton``statesController

此次版本更新还引入了几个新特性和便捷的 API。Badge.count构造函数现在包含一个maxCount参数（#171054），可以轻松限制显示的数量（例如，显示"99+"而不是"100"）。

为了实现更精细的手势控制，该InkWell小部件现在具有onLongPressUp回调功能（#173221），可用于触发仅在用户抬起手指时才应完成的操作。

Cupertino 库也在不断努力提升其 iOS 兼容性。CupertinoSlidingSegmentedControl新增了一个isMomentary属性（#164262），允许控件在不保持选中状态的情况下触发操作。为了更好地匹配原生 iOS 的行为，该控件CupertinoSheet在完全展开状态下向上拖动时，现在会呈现微妙的"拉伸"效果（#168547）。

最后，本次版本更新包含多项改进，优化了核心组件的行为。亮点包括修复了DropdownMenuFormField表单重置时正确清除文本字段的问题（#174937），以及更新了组件以SegmentedButton改进焦点处理（#173953）并确保其边框能够正确反映组件的状态（#172754）。

解耦 Material and Cupertino

我们一直在进行大量的规划工作，旨在将 Material 和 Cupertino 库与框架解耦。以下列表包含了围绕近期发布的一些设计文档展开的讨论。

改进 flutter/packages 的发布流程，解耦后将包含 Material 和 Cupertino。

颜色和点阵速记

状态：已决定
Flutter 基础配色方案（公开分享）

解耦测试

文本

状态：讨论中
Flutter 将设计与文本解耦（公开分享）

滚动：更稳健、更可预测的条形滚动

此版本带来了一系列修复，使得构建复杂的滚动布局（尤其是使用SliverMainAxisGroup和的布局SliverCrossAxisGroup）更加稳健和可预测。

使用这些组件将多个 Sliver 分组的开发者会发现，手势处理现在更加可靠。现在可以正确计算这些组内 Sliver 的点击和其他指针事件的命中测试，确保用户交互按预期运行（#174265）。

其他几项修复也使得滚动行为更加准确SliverMainAxisGroup。使用固定标题时过度滚动的问题已得到解决（#173349），调用showOnScreen显示小片段现在可以正常工作（#171339），并且内部滚动偏移计算更加精确（#174369）。

对于构建自定义滚动视图的开发者来说，新的SliverGrid.list构造函数（#173925）提供了一种更简洁的方式，可以从简单的子列表创建网格。

此次更新还改进了复杂布局中键盘和方向键用户的焦点导航体验。在具有不同滚动轴的嵌套滚动视图（例如水平轮播图的垂直列表）中，方向性焦点导航现在更加可预测，防止焦点在不同部分之间意外跳转（#172875）。

无障碍设计：为所有用户提供更具包容性的体验

确保所有用户都能访问应用程序是 Flutter 框架的基石。此次版本更新延续了这一承诺，赋予开发者更多程序控制权，改善了国际用户的体验，并优化了核心组件的可访问性。

对于构建复杂应用程序的开发者而言，此版本引入了在 iOS 上默认启用辅助功能的功能WidgetsFlutterBinding.instance.ensureSemantics（#174163debugDumpSemanticsTree ）。此外，由于新增了文本输入验证结果信息，有助于更快地诊断问题（#174677 ），因此调试辅助功能问题也变得更加容易。

为了增强基于 Sliver 的滚动视图的辅助功能，我们新增了一个SliverSemantics组件（#167300）。与现有组件类似，开发者可以在滚动视图中Semantics使用该组件，为 Sliver 树的各个部分添加特定的语义信息。这对于标注标题、分配语义角色以及为屏幕阅读器添加描述性标签尤为有用，从而为用户提供更易于理解和访问的体验。SliverSemantics``CustomScrollView

最后，核心组件的辅助功能持续改进。CupertinoExpansionTile现在默认情况下可访问（#174480），并且该AutoComplete组件现在会向用户播报搜索结果的状态（#173480）。其他改进，例如增大触摸目标TimePicker（#170060），也有助于提供更便捷的开箱即用体验。

iOS

我们很高兴地确认，Flutter 完全支持最新的平台版本：iOS 26、Xcode 26 和 macOS 26，这些版本均于 9 月发布。这确保您可以立即在 Apple 最新的操作系统和工具上开始开发和测试您的应用。

您可能已经注意到，Flutter 最新版本为 iOS 开发者带来了显著的体验提升，解决了用户长期以来的一个痛点：在物理设备上运行 Flutter 应用时，Xcode 应用必须自动启动flutter run。我们引入了一种新的部署方式，使用 Xcode 26 命令行工具 npm run devicectldev 来进行应用的安装、启动和调试。这种方式无需在部署过程中调用 Xcode 应用，大多数情况下完全依赖于命令行 Xcode 构建工具。如果您遇到任何问题，可以使用 npm run dev 禁用此部署方式flutter config --no-enable-lldb-debugging，并请提交 issue告知我们！

此前，此功能依赖于 Xcode 自动化，但在 Xcode 26 中变得不稳定且容易出错，尤其是在连续运行命令时。如果您现在正在为最新的 Apple 版本进行开发，我们强烈建议您将 Flutter 版本更新到 3.38 或更高版本。

UIScene 生命周期迁移

Flutter 3.38 包含了对苹果强制要求的UIScene 生命周期的重要支持。这是继苹果在 WWDC25 上宣布"在 iOS 26 之后的版本中，任何使用最新 SDK 构建的 UIKit 应用都必须使用 UIScene 生命周期，否则将无法启动"之后的一项关键且积极的更新。

为确保您的 iOS Flutter 应用程序在未来的 iOS 版本上保持兼容性并成功启动，需要进行迁移。

迁移 Flutter 应用程序

所有现有的 iOS Flutter 应用都必须迁移到新的生命周期。您可以通过两种方式完成此迁移：

手动迁移：请按照 Flutter网站上提供的手动迁移说明进行操作。
自动迁移（实验性功能）：启用此实验性功能可自动处理迁移。此功能将在未来的版本中默认启用。运行以下命令：

flutter config --enable-uiscene-migration

迁移 Flutter 插件

依赖应用程序生命周期事件的 Flutter 插件必须更新为使用 UIScene 生命周期事件。插件开发者应参考迁移指南。未迁移的插件将在未来的版本中显示警告。

迁移嵌入式 Flutter（可选）

对于将 Flutter 嵌入原生宿主应用程序的项目，迁移是可选的，但强烈建议进行。使用"添加到应用程序迁移指南"采用 Flutter 新的 UIScene API ，可以为您的插件启用场景生命周期事件，从而确保与 Flutter 生态系统的兼容性。

安卓

16KB页面大小兼容性

升级到 Flutter 3.38 是满足Google Play 16 KB 页面大小兼容性要求的必要准备。从2025 年 11 月 1 日起，面向 Android 15 及更高版本的应用必须支持 16 KB 页面。此项变更可确保您的应用在高内存设备上正常运行，并带来性能提升，例如启动速度提升高达 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 插件 (AGP)、Kotlin Gradle 插件 (KGP)、Java 等。对于 Flutter 3.38 版本，我们在持续集成 (CI) 环境中测试并确认了以下 Android 依赖项版本组合的兼容性：

Java 17：Flutter 3.38 中 Android 开发的最低版本要求。
KGP 2.2.20 ：该工具支持的最高Kotlin Gradle 插件版本。
AGP 8.11.1 ：最新的 Android Gradle 插件版本，与 KGP 2.2.20兼容。
Gradle 8.14：此版本与所选的 Java、KGP 和 AGP 版本兼容。请注意，AGP 8.11.1 的最低版本要求为 Gradle 8.13。

为了确保您的应用能够在不同的 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 系统中已移除选择退出线程合并的功能。欲了解更多信息，请观看精彩的线程合并视频。

开发者工具和集成开发环境

实验性小部件预览 --- 更新

Flutter 3.35 引入了 Widget Previews（组件预览），这是一项实验性功能，旨在收集社区的早期反馈。Flutter 3.38 版本对 Widget Previews 进行了重大改进，包括：

IDE 集成：我们的 VSCode 和 IntelliJ/Android Studio 插件均已更新，初步支持 Widget 预览。现在，您可以直接在 IDE 中查看预览，从而获得更流畅的开发体验。

按回车键或点击查看完整尺寸的图片

VSCode 中嵌入了小部件预览。

在集成开发环境 (IDE) 中使用时，控件预览环境默认配置为根据当前选定的源文件筛选显示的预览：

按回车键或点击查看完整尺寸的图片

小部件预览环境主题和控件改进：小部件预览环境现在支持浅色和深色模式，以及自定义 IDE 配色方案，以匹配您的开发环境。小部件预览环境中的控件也进行了调整，以减少占用空间，从而为渲染预览腾出更多空间。

按回车键或点击查看完整尺寸的图片

为小部件预览环境提供自定义主题支持。

预览可扩展性：预览注解类不再标记为 final，现在可以扩展以创建自定义预览注解，从而减少常见预览类型的样板代码。

按回车键或点击查看完整尺寸的图片

自定义注解示例 BrightnessPreview 。

多预览支持 ：新增的MultiPreview基类允许从单个自定义注释创建多个预览变体。

按回车键或点击查看完整尺寸的图片

预览组 ：类中的新分组参数Preview允许对相关的预览进行分组。

按回车键或点击查看完整尺寸的图片

预览组中多个"亮度"预览的示例。

放宽了对 @Preview 注解参数的限制 ：现在支持将私有常量作为Preview注解的参数。函数参数（例如 wrapper 和 theme）仍然需要具有公开的、静态可访问的名称。

小部件预览功能目前仍处于实验阶段，您的反馈对塑造其未来至关重要。API 和用户体验尚不稳定，我们会根据您的反馈不断改进。

根据早期反馈，我们计划进行更多改进以提升组件预览体验，包括：

Flutter DevTools Widget Inspector 支持：Widget Inspector 正在更新，以支持在 widget 预览环境中检查预览效果。我们计划将检查器直接嵌入到 widget 预览器中，使其无论您处于何种开发环境都能轻松访问。
IDE中的多项目支持 ：目前，组件预览器仅支持显示单个项目或Pub工作区内的预览。我们正在积极研究如何支持在IDE会话中包含多个Flutter项目的方案（问题#173550）。
提升启动性能：我们正在研究提升启动性能的机会，以缩短初始启动时间，包括：

首次运行后启动预编译的组件预览环境
并行化预览检测逻辑以更好地处理大型项目

首先，请查看文档，然后告诉我们您的想法！

阅读文档 ：Flutter Widget 预览（实验性功能）入门指南
提供反馈：在 Flutter GitHub 存储库中提交问题和功能请求。
了解更多 ：如需深入了解技术细节，请参阅Flutter Widget Previews 架构文档。

重要提示 ：已知 Widget Previewer 在执行某些操作后可能会崩溃或停止更新 flutter pub get 。如果遇到此问题，请 flutter pub get在项目中运行相关命令并重启 IDE。 详情请参阅 #178317 。**

开发者工具更新

Flutter 3.38 修复了 2025 年 DevTools 用户调查中用户指出的一些主要痛点，包括：

网络面板改进

使用户更容易了解面板何时正在记录网络流量。（#9495）
修复了复制粘贴网络请求相关的问题。（#9472、#9482、#9485、#8588）

Flutter Inspector 修复

修复了选择控件时有时会打开底层框架源代码而不是用户源代码的错误。（#176530）
修复了偶尔会导致无法与检查器面板顶部按钮进行交互的错误。（#9327）

弃用和重大变更

作为 Flutter 框架现代化和改进工作的一部分，本次版本更新包含了几个重要的弃用项和重大变更。

关键的构建和工具变更可能会影响自定义构建脚本。Flutter versionSDK 根目录下的文件已被移除，取而代之的是位于 [flutter.version.json此处应填写路径] 的新文件bin/cache（#172793）。此外，该AssetManifest.json文件不再默认生成（#172594）。

其他显著变化包括：

为了使行为更可预测，包含操作的 SnackBar 将不再自动关闭（#173084）。
构造函数OverlayPortal.targetsRootOverlay已被弃用，取而代之的是更灵活的OverlayPortal（overlayLocation: OverlayChildLocation.rootOverlay）。
的几个属性CupertinoDynamicColor，例如withAlpha和withOpacity，现在已被弃用，取而代之的是标准Color方法（#171160）。
Flutter 3.38 要求 Android 的最低 Java 版本为 17，与Gradle 8.14（2025 年 7 月发布）的最低要求一致。

有关这些变更和其他变更的更多详细信息和迁移指南，请查看重大变更页面。

结尾

Flutter 3.38 改动还是挺多的，要升级的还得等等看看，避免在生产环境使用。