内容

Dart 3 迁移指南

Dart 3 是一个主要版本,它为 Dart 引入了新的核心功能:记录模式类修饰符

除了这些新功能之外,Dart 3 还包含一些可能会破坏现有代码的更改。

本指南将帮助您解决在升级到 Dart 3后可能遇到的任何迁移问题。

简介

#

未版本化与版本化更改

#

以下列出的潜在重大变更属于以下两种类别之一

  • 未版本化变更:这些变更会影响升级到 Dart 3.0 SDK 或更高版本的任何 Dart 代码。无法“关闭”这些变更。

  • 版本化变更:这些变更仅在包或应用程序的语言版本设置为 >= Dart 3.0 时才适用。 语言版本 来自 pubspec.yaml 文件 中的 sdk 下限约束。像这样的 SDK 约束不会应用 Dart 3 版本化变更

    yaml
    environment:
      sdk: '>=2.14.0 <3.0.0'

    但像这样的 SDK 约束会

    yaml
    environment:
      sdk: '>=3.0.0 <4.0.0'

要使用新的 Dart 3 功能,您必须将语言版本更新到 3.0。这将同时为您提供 Dart 3 版本化变更。

Dart 3 向后兼容性

#

许多使用 Dart 2.12 或更高版本的空安全性的包和应用程序可能与 Dart 3 向后兼容。对于 SDK 约束的下限为 2.12.0 或更高的任何包,这都是可能的。

Dart 的 pub 工具 允许解析,即使上限限制在低于 3.0.0 的版本。例如,具有以下约束的包将被允许解析为 Dart 3.x SDK,因为当下限为 2.12 或更高时,pub 将重新解释上限约束 <3.0.0<4.0.0

yaml
environment:
  sdk: '>=2.14.0 <3.0.0'           # This is interpreted as '>=2.14.0 <4.0.0'

这允许开发人员使用 Dart 3 健全空安全性与已经支持 2.12 空安全性的包,而无需进行第二次迁移,除非代码受到任何其他 Dart 3 变更的影响。

测试影响

#

要了解您的源代码是否受到任何 Dart 3 变更的影响,请使用以下步骤

$ dart --version    # Make sure this reports 3.0.0 or higher.
$ dart pub get      # This should resolve without issues.
$ dart analyze      # This should pass without errors.

如果 pub get 步骤失败,请尝试升级您的依赖项,看看是否有更新的版本可能支持 Dart 3

$ dart pub upgrade
$ dart analyze      # This should pass without errors.

或者,如果需要,还可以包括 主要版本 升级

$ dart pub upgrade --major-versions
$ dart analyze      # This should pass without errors.

Dart 3 语言更改

#

100% 健全的空安全

#

Dart 2.12 在两年前引入了空安全性。在 Dart 2.12 中,用户需要使用 pubspec 设置 启用空安全性。在 Dart 3 中,空安全性是内置的;您无法将其关闭。

范围

#

这是一个 非版本化更改,适用于所有 Dart 3 代码。

症状

#

在没有空安全支持的情况下开发的包在使用 pub get 解析依赖项时会导致问题。

$ dart pub get

Because pkg1 doesn't support null safety, version solving failed.
The lower bound of "sdk: '>=2.9.0 <3.0.0'" must be 2.12.0 or higher to enable null safety.

使用 语言版本注释 选择低于 2.12 的任何语言版本的库将导致分析或编译错误。

$ dart analyze .
Analyzing ....                         0.6s

  error • lib/pkg1.dart:1:1 • The language version must be >=2.12.0. 
  Try removing the language version override and migrating the code.
  • illegal_language_version_override
$ dart run bin/my_app.dart
../pkg1/lib/pkg1.dart:1:1: Error: Library doesn't support null safety.
// @dart=2.9
^^^^^^^^^^^^

迁移

#

在开始任何迁移到 Dart 3 之前,请确保您的应用程序或包已 100% 迁移以启用空安全。这需要 Dart 2.19 SDK,而不是 Dart 3 SDK。要了解如何首先迁移您的应用程序或包以支持空安全,请查看 空安全迁移指南

冒号语法用于默认值

#

出于历史原因,命名可选参数可以使用 := 指定其默认值。在 Dart 3 中,只允许使用 = 语法。

范围

#

这是一个 版本化更改,仅适用于语言版本 3.0 或更高版本。

症状

#

Dart 分析会产生类似的错误

line 2 • Using a colon as a separator before a default value is no longer supported.

迁移

#

从使用冒号

dart
int someInt({int x: 0}) => x;

更改为使用等于号

dart
int someInt({int x = 0}) => x;

此迁移可以手动进行,也可以使用 dart fix 自动进行。

$ dart fix --apply --code=obsolete_colon_for_default_value

mixin

#

在 Dart 3 之前,任何 class 都可以用作 mixin,只要它没有声明的构造函数,并且除了 Object 之外没有超类。

在 Dart 3 中,在语言版本 3.0 或更高版本中声明的类不能用作 mixin,除非标记为 mixin。此限制适用于尝试将该类用作 mixin 的任何库中的代码,无论后者的库语言版本如何。

范围

#

这是一个 版本化更改,仅适用于语言版本 3.0 或更高版本。

症状

#

类似的分析错误

Mixin can only be applied to class.

当在 with 子句中使用既不是 mixin class 也不是 mixin 的类时,分析器会生成此诊断。

迁移

#

确定该类是否打算用作 mixin。

如果该类定义了一个接口,请考虑使用 implements

switch

#

Dart 3.0 将 switch 语句中的 case 解释为 模式,而不是常量表达式。

范围

#

这是一个 版本化更改,仅适用于语言版本 3.0 或更高版本。

症状

#

大多数在 switch 语句中找到的常量表达式都是具有相同含义的有效模式(命名常量、字面量等)。它们的行为将相同,不会出现任何症状。

少数不是有效模式的常量表达式将触发 invalid_case_patterns lint

迁移

#

您可以通过在 case 模式前添加 const 来恢复到原始行为,这样它就不会再被解释为模式。

dart
case const [1, 2]:
case const {'k': 'v'}:
case const {1, 2}:
case const Point(1, 2):

您可以使用 dart fix 或从您的 IDE 中运行快速修复来解决此重大更改。

continue

#

Dart 3 如果 continue 语句的目标不是循环(fordowhile 语句)或 switch 成员,则会报告编译时错误。

范围

#

这是一个 版本化更改,仅适用于语言版本 3.0 或更高版本。

症状

#

您将看到类似的错误

The label used in a 'continue' statement must be defined on either a loop or a switch member.

迁移

#

如果可以接受更改行为,请将 continue 更改为目标为有效标记语句,该语句必须附加到 fordowhile 语句。

如果您想保留行为,请将 continue 语句更改为 break 语句。在 Dart 的早期版本中,continue 语句如果没有目标为循环或 switch 成员,则行为类似于 break

Dart 3 核心库更改

#

已删除的 API

#

重大更改 #49529:核心库已清理,以删除已弃用多年的 API。以下 API 不再存在于 Dart 核心库中。

范围

#

这是一个 非版本化更改,适用于所有 Dart 3 代码。

dart:core

#
  • 已删除已弃用的 List 构造函数,因为它不是空安全。使用列表字面量(例如,对于空列表使用 [],对于空类型列表使用 <int>[])或 List.filled。这只会影响非空安全代码,因为空安全代码已经无法使用此构造函数。
  • 已删除 int.parsedouble.parsenum.parse 上已弃用的 onError 参数。使用 tryParse 方法代替。
  • 已删除已弃用的 proxyProvisional 注释。原始的 proxy 注释在 Dart 2 中没有效果,Provisional 类型和 provisional 常量仅在 Dart 2.0 开发过程中内部使用。
  • 已删除已弃用的 Deprecated.expires getter。使用 Deprecated.message 代替。
  • 已删除已弃用的 CastError 错误。使用 TypeError 代替。
  • 已删除已弃用的 FallThroughError 错误。以前导致抛出此错误的穿透类型在 Dart 2.0 中已成为编译时错误。
  • 已移除弃用的 NullThrownError 错误。此错误永远不会从空安全代码中抛出。
  • 已移除弃用的 AbstractClassInstantiationError 错误。在 Dart 2.0 中,调用抽象类的构造函数已成为编译时错误。
  • 已移除弃用的 CyclicInitializationError。空安全代码中不再在运行时检测循环依赖关系。此类代码将以其他方式失败,可能出现 StackOverflowError。
  • 已移除弃用的 NoSuchMethodError 默认构造函数。请改用 NoSuchMethodError.withInvocation 具名构造函数。
  • 已移除弃用的 BidirectionalIterator 类。现有的双向迭代器仍然可以工作,只是它们没有共享的超类型将它们锁定到用于向后移动的特定名称。

dart:async

#

dart:developer

#

dart:html

#
  • 如先前宣布,DocumentHtmlDocument 中的弃用 registerElementregisterElement2 方法已被移除。有关详细信息,请参见 #49536

dart:math

#
  • Random 接口只能实现,不能扩展。

dart:io

#
  • 更新 NetworkProfiling 以适应 vm_service:11.0.0 中引入的新 String id。

症状

#

Dart 分析(例如,在您的 IDE 中,或在 dart analyze/flutter analyze 中)将出现错误,例如

error line 2 • Undefined class 'CyclicInitializationError'.

迁移

#

手动迁移以不再使用这些 API。

Extends 和 implements

#

Dart 3 支持新的 类修饰符,这些修饰符可以限制类的功能。它们已应用于核心库中的多个类。

范围

#

这是一个 版本化更改,仅适用于语言版本 3.0 或更高版本。

dart:async

#
  • 以下声明只能实现,不能扩展

    • StreamConsumer
    • StreamIterator
    • StreamTransformer
    • MultiStreamController

    这些声明中没有任何实现可以继承。它们被标记为interface,表示它们仅作为接口。

dart:core

#
  • Function 类型不再可以实现、扩展或混合。从 Dart 2.0 开始,为了向后兼容,允许编写implements Function,但它没有任何效果。在 Dart 3.0 中,Function 类型是最终的,不能进行子类型化,防止代码错误地假设它有效。

  • 以下声明只能实现,不能扩展

    • Comparable
    • Exception
    • Iterator
    • Pattern
    • Match
    • RegExp
    • RegExpMatch
    • StackTrace
    • StringSink

    这些声明中没有任何实现可以继承。它们被标记为interface,表示它们仅作为接口。

  • 以下声明不再可以实现或扩展

    • MapEntry
    • OutOfMemoryError
    • StackOverflowError
    • Expando
    • WeakReference
    • Finalizer

    MapEntry 值类被限制以允许以后的优化。其余类与平台紧密耦合,不打算进行子类化或实现。

dart:collection

#
  • 以下接口不再可以扩展,只能实现

    • Queue
  • 以下实现类不再可以实现

    • LinkedList
    • LinkedListEntry
  • 以下实现类不再可以实现或扩展

    • HasNextIterator(也已弃用。)
    • HashMap
    • LinkedHashMap
    • HashSet
    • LinkedHashSet
    • DoubleLinkedQueue
    • ListQueue
    • SplayTreeMap
    • SplayTreeSet

Dart 3 工具更改

#

已删除的工具

#

历史上,Dart 团队为代码格式化(dartfmt)、代码分析(dartanalyzer)等提供了一些较小的开发人员工具。在 Dart 2.10(2020 年 10 月)中,我们引入了一个新的统一的 Dart 开发人员工具,即dart 工具

范围

#

这是一个 非版本化更改,适用于所有 Dart 3 代码。

症状

#

在 Dart 3 中,这些较小的工具不存在,已被新的组合dart 工具取代。

迁移

#

使用dart 工具中可用的新子命令

历史工具dart 替换弃用停止使用
stagehanddart create2.142.14*
dartfmtdart format2.142.15
dart2nativedart compile exe2.142.15
dart2jsdart compile js2.172.18
dartdevcwebdev2.172.18
dartanalyzerdart analyze2.162.18
dartdocdart doc2.162.17
pubdart pub2.152.17

空安全迁移工具

#

以下空安全迁移命令已被移除,因为 Dart 3 不支持没有空安全的代码

  • dart migrate
  • dart pub upgrade --null-safety
  • dart pub outdated --mode=null-safety

范围

#

这是一个 非版本化更改,适用于所有 Dart 3 代码。

症状

#

这些命令将失败。

迁移

#

使用 Dart 2.19 迁移到空安全

分析器配置

#

用于启用更严格检查的 分析器配置选项 已更改。

范围

#

这是一个 非版本化更改,适用于所有 Dart 3 代码。

症状

#

以前的配置选项将显示类似的警告并失败

The option 'implicit-casts' is no longer supported.
Try using the new 'strict-casts' option.

迁移

#

替换分析器配置的这部分

yaml
analyzer:
  strong-mode:
    implicit-casts: false
    implicit-dynamic: false

yaml
analyzer:
  language:
    strict-casts: true
    strict-raw-types: true

其他工具更改

#
  • 默认情况下,已隐藏过时的 Observatory。我们建议使用 DevTools
  • 命令 dart format fix 已被 dart fix 替换 #1153
  • SDK 中捆绑的用于 Dart Web 编译器的快照文件已清理 #50700
  • dart format 的输出对 某些代码 进行了细微更改。
  • 结束对 Windows 上旧的 pub-cache 位置的反向兼容性。在 Dart 3 之前,%APPDATA%\Pub\Cache 是 pub-cache 的备用位置。从 Dart 3 开始,默认的 pub-cache 位于 %LOCALAPPDATA%\Pub\Cache。如果您已将全局激活的包添加到 PATH,请考虑更新 PATH 以包含 %LOCALAPPDATA%\Pub\Cache\bin

范围

#

这是一个 非版本化更改,适用于所有 Dart 3 代码。