跳到主要内容

重大变更与弃用

此页面列出了 Dart SDK 更新中的所有重大变更和弃用,按发布版本和领域组织,以帮助 Dart 开发者了解和管理其影响。完整的发布说明可在Dart SDK 变更日志中查看。重大变更政策文档描述了 Dart 中重大变更和弃用的政策和流程。

此页面包含以下类型的重大变更:

无版本限制

Dart SDK 不维护向后兼容性,如果您的代码依赖于旧行为,则一旦升级 SDK 版本,代码可能会立即中断。

这些是大多数变更,在此列表中没有特殊标记。

语言版本限定

Dart SDK 维护现有代码的向后兼容性,行为变更仅在您升级代码的语言版本时生效(可能破坏依赖旧行为的代码)。

这些标记为: 语言版本限定

弃用

Dart SDK 维护已弃用代码的兼容性,并发出警告。弃用项随后会在后续版本中完全移除,从而破坏依赖旧行为的任何代码。

这些标记为: 已弃用 / 已移除

实验性

作为发布版本的一部分,但尚未在 SDK 中被视为稳定,并且可能在一个版本到另一个版本之间发生中断。实验性变更不一定总有相应的重大变更问题,但可能在SDK 变更日志中有更多详细信息。

这些标记为: 实验性

如果您对这些重大变更中的任何一个有疑问或疑虑,请在相关条目链接的重大变更问题上发表评论。要接收未来重大变更的通知,请加入 Dart announce 小组。

3.9.0

#

语言

#
  • 语言版本限定 在计算类型提升、可达性和确定性赋值时,现在默认启用空安全。因此,改进的死代码分析可能会导致对以前通过分析的现有代码触发新的分析器诊断。

3.8.0

#

#

dart:html

#
  • 已移除 Element.created 构造函数已移除。
  • dart:html 中的原生类,例如 HtmlElement不再可以被扩展

工具

#

分析器

#

开发 JavaScript 编译器 (DDC)

#
  • 现在,当一个重定向工厂构造函数被“拆分”并且其可选的非空参数之一未提供值时,会抛出运行时错误。未来这很可能会成为编译时错误。

生产 JavaScript 编译器 (dart2js)

#
  • 实验性 已移除 --experiment-new-rti--use-old-rti 标志不再受支持。

格式化工具 (dart format)

#
  • 语言版本限定 格式化工具进行了一些更改和修复,使得当代码的语言版本为 3.8 或更高时,会产生新的格式化输出。

3.7.0

#

语言

#

#

dart:html, dart:indexed:db, dart:svg, dart:web_audo, dart:web_gl, dart:js

#
  • 已弃用 这些旧版 Web 库已正式弃用。预计它们将在未来版本中移除。项目应迁移到使用 package:webdart:js_interop。了解更多信息,请查看迁移到 package:web

dart:js, dart:js_util, package:js

#
  • 已弃用 这些旧版 JS 互操作库已正式弃用。预计它们将在未来版本中移除。项目应迁移到使用 dart:js_interop。了解更多信息,请查看JS 互操作用法

工具

#

分析器

#

格式化工具 (dart format)

#
  • 语言版本限定 格式化工具实现了一种新样式,当使用 3.7 或更高语言版本格式化代码时,会产生新的输出。
  • 已移除 dart format--fix 标志不再受支持。要应用类似的修复及更多功能,请配置您的分析选项并运行 dart fix
  • 已弃用 dart format--line-length 选项已弃用并设置为移除。所有用法都应迁移到新的 --page-width 选项。

3.6.0

#

语言

#

#

dart:io

#

工具

#

分析器

#

编译器前端 (cfe)

#
  • Dart 编译器现在会在类型模式传入子类型测试过程之前计算其上闭包和下闭包。在 Dart 3.6 之前,编译器在上下限计算的最开始就计算它们。分析器已经遵循此行为,因此已经通过分析的应用程序不太可能受到此更改的影响。

Wasm 编译器 (dart2wasm)

#
  • 当编译为 WebAssembly 时,条件导入上的 dart.library.js 条件现在为 false。应改用 dart.library.js_interop 条件。

格式化工具 (dart format)

#

当使用 Dart 3.6 SDK 或更高版本运行 dart format 时,以下更改可能会导致细微的格式化变更:

  • 保留旧式函数类型形式参数的类型参数,这些形式参数也使用 this.super.
  • 正确格式化同时包含 asif 子句的导入。

Pub

#
  • 如果 git 中跟踪的文件有未提交的更改,dart pub publish 现在会发出警告。

3.5.0

#

语言

#

#

dart:core

#

dart:io

#

dart:js_interop

#

dart:typed_data

#

运行时

#
  • 已移除 Dart VM 不再支持不健全的空安全。
    • --no-sound-null-safety CLI 选项已移除。
    • Dart_NewListOfDart_IsLegacyType 函数已从 C API 中移除。
  • 已移除 Dart_DefaultCanonicalizeUrl 函数已从 C API 中移除。

3.4.0

#

语言

#

#

dart:cli

#

dart:html, dart:indexed:db, dart:svg, dart:web_audo, dart:web_gl

#
  • 已弃用 这些库现在被标记为旧版,未来将获得较少支持。新项目应优先使用 package:webdart:js_interop。了解更多信息,请查看迁移到 package:web

dart:js

#
  • 已弃用 此库现在被标记为旧版,未来将获得较少支持。用法应迁移到 dart:js_interopdart:js_interop_unsafe。了解更多信息,请查看/go/next-gen-js-interop

dart:js_util

#
  • 已弃用 此库现在被标记为旧版,未来将获得较少支持。用法应迁移到 dart:js_interopdart:js_interop_unsafe。了解更多信息,请查看/go/next-gen-js-interop

dart:io

#

dart:typed_data

#

工具

#

生产 JavaScript 编译器 (dart2js)

#
  • 实验性 已弃用 您现在应该为 --dump-info CLI 选项指定 binaryjson 格式。json 格式已弃用,并可能在未来的 Dart 版本中移除。

Wasm 编译器 (dart2wasm)

#
  • 实验性 各种 dart compile wasm CLI 参数已更新、移除或替换。了解更多信息,请运行 dart compile wasm --verbose --help

运行时

#
  • 已移除 Dart VM 不再支持外部字符串。因此,Dart_IsExternalStringDart_NewExternalLatin1StringDart_NewExternalUTF16String 函数已从 Dart C API 中移除。

3.3.0

#

SDK

#
  • 实验性 已移除 以下实验性功能现已停用,因为它们已在 Dart 3 中发布,并且在语言版本为 3.0 或更高时不再需要。应从分析选项、CLI 命令和 IDE 配置中移除它们的配置。

    • 模式
    • 记录
    • 类修饰符
    • 密封类

语言

#

#

dart:cli

#
  • 实验性 已弃用 waitFor 函数在下一个版本中仍将弃用,并计划在 Dart 3.4 中移除。

dart:ffi

#

dart:html

#
  • 现在建议使用 package:http,而不是直接使用 HttpRequest

dart:io

#
  • 现在建议使用 package:http,而不是直接使用 HttpClient

dart:js_interop

#
  • 实验性JSAny 这样的 JS 类型有新的编译器特定表示类型
  • 实验性 用户定义的 @staticInterop不再能实现 JSAnyJSObject。用法应迁移到 JSObject.fromInteropObject 或定义为扩展类型。
  • 实验性 JSArrayJSPromise 现在具有泛型参数。
  • 实验性 各种扩展成员已被移动或重命名。要了解更新后的扩展,请参考 JSAnyUtilityExtensionJSAnyOperatorExtension

dart:typed_data

#

dart:nativewrappers

#

工具

#

生产 JavaScript 编译器 (dart2js)

#

Wasm 编译器 (dart2wasm)

#

分析器

#
  • 实验性 无效的 dart doc 注释指令现在由分析器报告。

  • 由于类型提升的改进,以下分析器诊断可能会对以前通过分析的现有代码触发:

    • 不必要的非空断言
    • 不必要的类型转换
    • 无效的空感知运算符

Linter

#
  • iterable_contains_unrelated_typelist_remove_unrelated_type lint 已移除。考虑迁移到扩展的 collection_methods_unrelated_type lint。

  • 由于健全的空安全不再需要,以下 lint 已移除。您应该从 analysis_options.yaml 文件和任何忽略注释中移除它们的配置。

    • always_require_non_null_named_parameters
    • avoid_returning_null
    • avoid_returning_null_for_future

3.2.0

#

语言

#

#

dart:cli

#

dart:convert

#

dart:developer

#
  • 已弃用 Service.getIsolateID 方法。

dart:ffi

#

dart:io

#

dart:js_interop

#
  • 实验性 已移除 JSNumber.toDart 已移除,请改用 toDartDoubletoDartInt
  • 实验性 已移除 Object.toJS 已移除,请改用 Object.toJSBox.
  • 实验性 使用 dart:js_interop 的外部 JS 互操作 API 已限制为一组允许的类型。
  • 实验性 禁止在 dart2wasm 上使用 isNullisUndefined
  • 实验性 typeofEqualsinstanceof API 已更改为均返回 bool 而不是 JSBoolean。此外,typeofEquals 现在接受 String 而不是 JSString
  • 实验性 JSAnyJSObject 类型已更改为只能由用户 @staticInterop 类型实现,不能扩展。
  • 实验性 JSArray.withLength 已更改为接受 int 而不是 JSNumber

工具

#

开发 JavaScript 编译器 (DDC)

#

生产 JavaScript 编译器 (dart2js)

#

分析器

#

3.1.0

#

#

dart:async

#

dart:io

#

dart:js_interop

#
  • 实验性 已移除 ObjectLiteral;请使用 {}.jsify() 创建不带命名成员的对象字面量。

package:js

#
  • external @staticInterop 成员和 external 扩展成员不再能用作 tear-offs。请声明一个调用这些成员的闭包或非 external 方法,并改用它。
  • external @staticInterop 成员和 external 扩展成员对于具有可选参数的方法将生成略有不同的 JS 代码。

3.0.0

#

语言

#

#
  • 以下现有类已成为 mixin 类:Iterable, IterableMixin, IterableBase, ListMixin, SetMixin, MapMixin, LinkedListEntry, StringConversionSink

dart:core

#

dart:async

#

dart:collection

#

dart:developer

#

dart:ffi

#
  • 实验性 已弃用 @FfiNative 注解现在已弃用。用法应更新为使用 @Native 注解。

dart:html

#

dart:math

#
  • 语言版本限定 Random 接口只能被实现,不能被扩展。

dart:io

#

2.19.0

#

语言

#

#

dart:convert

#

dart:developer

#

dart:ffi

#

dart:io

#

dart:isolate

#
  • SendPort.send 恢复为在不确定共享相同代码的隔离区之间发送消息时,对消息内容进行严格检查。

dart:mirrors

#

package:js

#

dart2js

#

2.18.0

#

语言

#

#

dart:io

#

工具

#

Dart 命令行

#

2.17.0

#

#

dart:io

#

工具

#

Dart 命令行

#

2.16.0

#

#

dart:io

#

dart:isolate

#

工具

#

Dart 命令行

#

2.15.0

#

#

dart:io

#

dart:web_sql

#

dart:html

#

工具

#

Dart 命令行

#

Dart VM

#

2.14.0

#

#

dart:io

#
  • HttpClient 中的 setter 回调 .authenticate.authenticateProxy 现在必须接受可空的 realm 参数(对于未迁移的空安全代码)。

dart:typed_data

#

工具

#

Dart VM

#

Dart 命令行

#

dart2js

#

Dart 开发编译器 (DDC)

#

2.13.0

#

#

package:js

#
  • 对于非匿名 JS 互操作类,在 @JS() 注解中使用与 @Native 注解匹配的 String 不再有效

2.12.0

#

语言

#

#

dart:ffi

#

工具

#

Dart VM

#

Pub

#

2.10.0

#

工具

#

Dart VM

#

2.9.0

#

#

dart:convert

#

dart:html

#
  • 如果 CssClassSet 对应于多个元素,CssClassSet.add()CssClassSet.toggle 现在返回 false 而不是 null

dart:mirrors

#

工具

#

Dart VM

#

2.8.1

#

语言

#

#

dart:async

#

dart:core

#

dart:ffi

#
  • Pointer.asFunction()DynamicLibrary.lookupFunction() 更改为扩展方法。

dart:io

#

工具

#

Dart 开发编译器 (DDC)

#

我们修复了 DDC 和 Dart2JS 之间的多处不一致,以便用户更少遇到一个编译器接受但另一个编译器失败的代码。

  • 删除了DDC的旧版(基于分析器)版本。
  • 现在,使用推荐的 package:js 互操作规范传递给 JavaScript 的函数必须用 allowInterop 调用包裹起来。
  • @JS() 类中的构造函数必须用 external 标记。

dart2js

#
  • 相应的类型参数边界现在只需是相互子类型,而不是在绑定类型变量重命名和所有顶层类型相等的情况下结构上相等。
  • 类型现在已标准化
  • @JS() 类中的构造函数必须用 external 标记。
  • 完全移除了 --package-root 标志,该标志在 Dart 2.0.0 中已隐藏和禁用。

2.7.1

#

2.7.0

#

语言

#

#

dart:io

#
  • 添加了 IOOverrides.serverSocketBind,以帮助编写希望模拟 ServerSocket.bind 的测试。

2.6.0

#

语言

#

#

dart:ffi

#
  • API 现在使用静态扩展成员。
  • 移除了内存管理 Pointer.allocatePointer.free
  • Pointer.offsetBy 已移除,请改用 castelementAt

2.5.0

#

#

dart:io

#

工具

#

Pub

#

2.4.0

#

语言

#

#

dart:isolate

#
  • 当使用 dart2js 或 DDC 编译时,Isolate.resolvePackageUri 将始终抛出 UnsupportedError

dart:async

#

2.2.0

#

#

package:kernel

#
  • Kernel AST API 中 InstanceConstant 类上的 klass getter 已重命名为 classNode 以保持一致性。
  • 更新了 Link 实现,以便在 Windows 上使用真正的符号链接而不是连接点。

2.1.1

#

#

dart:io

#

工具

#

Dart VM

#

2.1.0

#

语言

#

工具

#

dart2js

#
  • 常量映射中不允许重复键,并且会产生编译时错误。

2.0.0

#

语言

#

#
  • 将核心库中的常量从 SCREAMING_CAPS 重命名为 lowerCamelCase
  • 为核心库类添加了许多新方法,如果您实现这些类的接口,则需要实现这些方法。
  • 在 Web 上使用 Dart 时,不再支持 dart:isolatedart:mirrors

工具

#

Pub

#