如何在Dart 3.8中配置更新后的代码格式化工具

2025年2月，Flutter 3.29和Dart 3.7正式发布，带来了许多新功能和改进。虽然有些变化可能不会立即对您产生影响，但有一项更新会影响到每一位Flutter开发者：新的Dart格式化工具。这一变化影响重大，除非您明确选择退出，否则您的代码库中将出现大量的格式更改。本文将引导您了解这些新变化以及所有配置选项，帮助您顺利应对。

我们开始吧！

更新内容：Dart 3.8（作为Flutter 3.32的一部分）添加了一个新的格式化选项，用于保留尾随逗号。这一点非常重要，因为这意味着您可以升级SDK，但如果不喜欢新风格，仍然可以选择退出。下面将详细介绍这一点。

旧的格式化工具是如何工作的？

在Dart 3.7之前，您可以控制尾随逗号的使用。以这个部件构造函数为例：

以下是旧格式化工具的行为：

添加尾随逗号→格式化工具会将其拆分为多行。
删除尾随逗号→格式化工具会将代码内联（如果适合页面宽度）。

虽然这种方式具有一致性，但它要求您为代码库中的所有参数列表和Widgets 决定是否添加或删除尾随逗号（并且在代码审查时可能会为此争论😞）。为了解决这个问题，Dart 3.7引入了新的格式化风格。

新的格式化工具是如何工作的？

现在，格式化工具会自动决定是否添加或删除尾随逗号。

如果参数列表适合最大页面宽度 ，格式化工具会删除尾随逗号并将其保持内联：

如果参数列表超过最大页面宽度，格式化工具会添加尾随逗号并将其拆分为多行：

总结：新旧格式化工具对比

旧格式化工具	新格式化工具
添加尾随逗号→拆分为多行	代码适合单行→删除尾随逗号并内联代码
删除尾随逗号→内联代码	代码超过页面宽度→添加尾随逗号并拆分为多行

这对您意味着什么？

如果您的pubspec.yaml仍然使用Dart 3.6或更低版本，目前不会有任何变化：

yaml 复制代码

environment:
  sdk: ^3.6.0

但一旦您明确升级到Dart 3.7或更高版本，新的格式化工具就会生效：

yaml 复制代码

environment:
  sdk: ^3.7.0

届时...您的代码库中将出现大量差异。

⚠️ 重要提示 ：格式化在保存时应用一旦您保存文件，新的格式化风格就会应用，导致大量差异：

为避免混乱，请一次性将新格式化工具应用于整个代码库：

bash 复制代码

# 从项目根目录运行
dart format .

这将确保所有格式化更改一致应用。我建议将此作为单个PR推送，并在进行其他更改之前合并：

bash 复制代码

# 一次性推送所有更改
git add .
git commit -m "Apply the new formatter"
git push

供参考，当我将新格式化工具应用于我的Flutter Tips App应用时，最终得到了一个包含1200多个更改的PR，约占总行数的25%：

页面宽度呢？

我们回顾一下，新的格式化工具会根据最大页面宽度（也就是行长度）来决定如何格式化代码。这可以在您的analysis_options.yaml文件中配置：

yaml 复制代码

formatter:
  page_width: 120

更改此设置并再次运行dart format将相应地重新格式化整个代码库。

关键要点：为您的项目和团队选择一个合适的页面宽度，并保持一致。👍

代码生成的文件呢？

当您运行dart format .时，它会应用于项目中的所有Dart文件，包括生成的文件。但有一个问题：build_runner不遵循您的page_width设置。大多数代码生成器会以固定的80字符行宽格式化输出，这意味着生成的文件可能与您项目的格式不匹配。

这对您来说意味着什么：

如果您的page_width为80（默认值），一切都不会有问题。
如果您使用自定义页面宽度，每当您运行build_runner时，生成的文件将恢复为80字符的换行。

这并不是一个大问题，因为您只需要对整个项目运行一次格式化工具（如前所述）。

未来改进 ：根据这条评论，未来的Dart格式化工具更新将允许从格式化中排除特定文件，这可能有助于解决这个问题。

Dart 3.8中更新的格式化工具呢？

当2023年首次讨论新格式化工具时，有人担心由于换行不考虑代码的语义含义，会导致格式不一致。经过更多讨论后，Dart团队同意在Dart 3.8中添加一个新的格式化选项来保留尾随逗号。

这意味着您可以升级到Dart 3.8：

yaml 复制代码

# pubspec.yaml
environment:
  sdk: ^3.8.0

然后，您必须在两个选项之间做出选择：

保留尾随逗号 在您的analysis_options.yaml文件中启用此选项：

yaml 复制代码

# analysis_options.yaml
formatter:
  trailing_commas: preserve

实际上，这会禁用新格式化工具的行为，并让您重新控制尾随逗号。

不保留尾随逗号（默认格式化风格） 如前所述，新的格式化风格会在适合页面宽度的代码中去除尾随逗号，因此您的代码库中会出现大量差异。

为了顺利处理这一点，请按照以下步骤操作：

在analysis_options.yaml中设置自定义page_width（可选但推荐）：

yaml 复制代码

# analysis_options.yaml
formatter:
  page_width: 120

将格式化工具应用于整个代码库：

bash 复制代码

# 从项目根目录运行
dart format .

再次运行build_runner以更新生成的文件：

bash 复制代码

# 更新代码生成的文件
dart run build_runner watch -d

将更改作为单个PR推送，然后在继续开发之前合并：

bash 复制代码

# 一次性推送所有更改
git add .
git commit -m "Apply the new formatter"
git push

虽然新的格式化工具可以安全使用，但Flutter 3.32是全新发布的，可能仍会出现错误。如果您不着急，建议等待热修复版本发布后再升级。