重大变更和弃用

此页面列出了 Dart 中所有语言和库重大变更和弃用，按版本和领域进行组织，以帮助 Dart 用户理解和管理其影响。完整的版本说明可以在 Dart SDK 变更日志 中找到。 重大变更策略 文档描述了 Dart 中重大变更和弃用的策略和流程。

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

• 未版本化：Dart SDK 不维护向后兼容性，只要你 升级 SDK 版本，代码就可能出现问题，如果代码依赖于之前的行为。

  这些是大多数变更，在本列表中未做特殊标记。

• 语言版本化：Dart SDK 保持对现有代码的向后兼容性，行为变更只会在你升级代码的 语言版本 时生效（可能会破坏依赖于之前行为的代码）。

  这些标记为： 语言版本化

• 弃用：Dart SDK 保持对弃用代码的兼容性，并发出警告。弃用将在后续版本中完全删除，破坏任何依赖于之前行为的代码。

  这些标记为： 已弃用 / 已删除

• 实验性：是版本的一部分，但尚未在 SDK 中视为稳定，可能会从一个版本到另一个版本发生变化。实验性变更并不总是具有相应的重大变更问题，但在 SDK 变更日志 中可能会有更多详细信息。

  这些标记为： 实验性

如果你对任何重大变更有任何疑问或疑虑，请在相关条目中链接的重大变更问题中发表评论。若要接收有关未来重大变更的通知，请加入 Dart 公告 组。

暂定
以下变更预计将包含在 3.6 稳定版本中，但最终列表可能会在发布之前发生变化。为了减少这些变更带来的潜在影响，请考虑在 3.6 版本发布之前做好准备。

• Dart 用于对 throw 表达式操作数进行类型推断的上下文已从“未知类型”更改为 Object。这使得类型系统更加自洽，因为它反映了无法抛出 null 的事实。此变更预计不会在实践中产生任何影响。

• 编译器用于对 await 表达式操作数进行类型推断的上下文已更改为匹配分析器的行为。
• 编译器用于对“if-null”表达式（e1 ?? e2）的右侧进行类型推断的上下文已更改为匹配分析器的行为。 可以通过提供显式类型来恢复旧的行为。

• DateTime 现在在 Web 平台上存储微秒，更接近本地平台上的行为。

• SecurityContext 现在是 final 的，不能再被子类化.

• importModule 现在接受 JSAny 而不是 String，以支持其他 JS 值，例如 TrustedScriptURL 对象。
• isTruthy 和 not 现在返回 JSBoolean 而不是 bool，以与其他 JS 运算符方法保持一致。
• ExternalDartReference 不再实现 Object。相反，它现在接受一个类型参数 (T)，其边界为 Object?，以捕获外部化的 Dart 对象的类型。

• 已删除 已删除类型化数据的不可修改视图类。不要使用这些类的构造函数，而是使用类型化数据列表上的新 asUnmodifiableView 方法。

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

• 用于强制类型转换模式的模式上下文类型模式现在是 _（未知类型），而不是 Object?.
• Dart 编译器用于对映射和集合字面量中空感知扩展运算符（...?）的操作数进行类型推断的类型模式已改为可空，以匹配列表字面量中当前发生的情况。

• 实验性 已删除 waitFor 函数 已删除。

• 已弃用 这些库现在标记为遗留库，未来将获得较少的支持。新项目应优先使用 package:web 和 dart:js_interop。若要了解更多信息，请查看 迁移到 package:web。

• 已弃用 此库现在标记为遗留库，未来将获得较少的支持。应将用法迁移到 dart:js_interop 和 dart:js_interop_unsafe。若要了解更多信息，请查看 /go/next-gen-js-interop。

• 已弃用 此库现在标记为遗留库，未来将获得较少的支持。应将用法迁移到 dart:js_interop 和 dart:js_interop_unsafe。若要了解更多信息，请查看 /go/next-gen-js-interop。

• Stdout 具有一个新的字段 lineTerminator，允许开发人员控制 stdout 和 stderr 使用的行结束符。 实现 Stdout 的类必须定义 lineTerminator 字段。stdout 和 stderr 的默认语义没有改变。
• 已弃用 FileSystemDeleteEvent.isDirectory 属性。它始终返回 false。

• 已弃用 类型化数据的不可修改视图类已弃用。不要使用这些类的构造函数，而是使用类型化数据列表上的新 asUnmodifiableView 方法。

• 实验性 已弃用 现在应为 --dump-info CLI 选项指定 binary 或 json 格式。json 格式已弃用，可能会在未来的 Dart 版本中删除。

• 实验性 dart compile wasm CLI 参数已更新、删除或替换。若要了解更多信息，请运行 dart compile wasm --verbose --help。

• 已删除 Dart VM 不再支持外部字符串。因此，Dart_IsExternalString、Dart_NewExternalLatin1String 和 Dart_NewExternalUTF16String 函数已从 Dart C API 中删除。

• 实验性 已删除 以下实验现已退出，因为它们已在 Dart 3 中发布，并且在语言版本 3.0 或更高版本中不再需要。应从分析选项、CLI 命令和 IDE 配置中删除对它们的配置。

  • patterns
  • records
  • class-modifers
  • sealed-class

• 如果没有任何冲突的声明，抽象 getter 现在被认为是可提升的.

• 实验性 已弃用 waitFor 函数 将在下一个版本中继续被弃用，并将在 Dart 3.4 中被移除。

• 已弃用 Pointer 类型上的 elementAt 指针运算方法已弃用。迁移到 - 和 + 运算符。
• 实验性 已移除 之前已弃用的 @FfiNative 注解已被移除。使用情况应更新为使用 @Native 注解。

• 建议使用 package:http 而不是直接使用 HttpRequest。

• 建议使用 package:http 而不是直接使用 HttpClient。

• 实验性 像 JSAny 这样的 JS 类型具有 新的编译器特定表示类型。
• 实验性 用户定义的 @staticInterop 类 不再能实现 JSAny 或 JSObject。使用情况应迁移到 JSObject.fromInteropObject 或定义为扩展类型。
• 实验性 JSArray 和 JSPromise 现在具有泛型参数。
• 实验性 各种扩展成员已被移动或重命名。要了解更新的扩展，请参考 JSAnyUtilityExtension 和 JSAnyOperatorExtension。

• 类型化数据的不可修改视图类将在 Dart 3.4 中被弃用。不要使用这些类的构造函数，而是在类型化数据列表上使用新的 asUnmodifiableView 方法。

• 实验性 所有本地包装器类现在都被标记为 base，因此它们的任何子类型都不能被实现。

• 传递给 noSuchMethod 的 Invocation 不再具有缩小的 memberName，即使在使用 --minify 编译时也是如此。

• 实验性 不允许导入旧的 JS 交互库。建议使用 dart:js_interop 和 dart:js_interop_unsafe 代替。

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

• 由于 类型提升方面的改进，以下分析器诊断可能在以前通过分析的现有代码上触发

  • unnecessary_non_null_assertion
  • unnecessary_cast
  • invalid_null_aware_operator

• iterable_contains_unrelated_type 和 list_remove_unrelated_type lints 已被移除。考虑迁移到扩展的 collection_methods_unrelated_type lint。

• 以下 lints 已被移除，因为它们在健全的空安全下不再是必需的。您应该从您的 analysis_options.yaml 文件和任何忽略注释中移除它们的配置。

  • always_require_non_null_named_parameters
  • avoid_returning_null
  • avoid_returning_null_for_future

• 语言版本化 更改了可推翻模式的拆分点 为顶层模式，因此，无论受检对象是否可能引发异常，if-case 语句中的类型提升都保持一致。

• 实验性 已弃用 waitFor 函数。

• 更改了 utf8.encode() 和 Utf8Codec.encode() 的返回值类型 从 List<int> 到 Uint8List。

• 已弃用 Service.getIsolateID 方法。

• 更改了 NativeCallable.nativeFunction，因此，调用现在在接收器已关闭时引发错误，而不是返回 nullptr。

• 消除了 HTTP 标头中的尾随空格.
• 在 HttpClientResponse.headers 和 HttpRequest.headers 返回的折叠标头值的折叠点处插入空格。

• 实验性 已移除 JSNumber.toDart，取而代之的是 toDartDouble 和 toDartInt。
• 实验性 已移除 Object.toJS，取而代之的是 Object.toJSBox.。
• 实验性 使用 dart:js_interop 的外部 JS 交互 API 被限制为一组允许的类型。
• 实验性 禁止在 dart2wasm 上使用 isNull 和 isUndefined。
• 实验性 更改了 typeofEquals 和 instanceof API，使其都返回 bool 而不是 JSBoolean。此外，typeofEquals 现在接受 String 而不是 JSString。
• 实验性 更改了 JSAny 和 JSObject 类型，使其仅可由用户 @staticInterop 类型实现，而不是扩展。
• 实验性 更改了 JSArray.withLength，使其接受 int 而不是 JSNumber。

• 为 JavaScript Symbol 和 BigInt 类型添加了拦截器；它们不应再与 package:js 类一起使用。

• 为 JavaScript Symbol 和 BigInt 类型添加了拦截器；它们不应再与 package:js 类一起使用。

• 语言版本化 私有 final 字段提升 可能导致以下分析器警告在以前通过分析的现有代码上触发

  • unnecessary_non_null_assertion
  • invalid_null_aware_operator
  • unnecessary_cast
  dart

  class C {
    final num? _x = null;
  
    void test() {
      if (_x != null) {
        print(_x! * 2); // unnecessary_non_null_assertion
        print(_x?.abs()); // invalid_null_aware_operator
      }
      if (_x is int) {
        print((_x as int).bitLength); // unnecessary_cast
      }
    }
  }

• 为纯抽象类添加了 interface 修饰符： MultiStreamController、StreamConsumer、StreamIterator 和 StreamTransformer。

• 将 sameSite 添加到 Cookie 类，并添加了 SameSite 类.
• FileSystemEvent 是 sealed。这意味着 FileSystemEvent 不能被扩展或实现。

• 实验性 已移除 ObjectLiteral；使用 {}.jsify() 创建没有命名成员的对象文字。

• external @staticInterop 成员和 external 扩展成员不再能用作撕裂。声明一个闭包或一个非 external 方法来调用这些成员，并改用它。
• external @staticInterop 成员和 external 扩展成员将为具有可选参数的方法生成略微不同的 JS 代码。

• 语言版本化 更改了 switch case 的解释，从常量表达式到模式。

• 语言版本化 已升级到 Dart 3.0 的库的类声明 默认情况下不再能用作 mixin。

• Dart 报告编译时错误 如果 continue 语句的目标是 标签，而该标签不是循环（for、do 和 while 语句）或 switch 成员。

• 以下现有类已变为 mixin 类：Iterable、IterableMixin、IterableBase、ListMixin、SetMixin、MapMixin、LinkedListEntry、StringConversionSink。

• 已弃用 已弃用的 API。

• 已移除 已移除已弃用的 DeferredLibrary 类。

• 语言版本化 平台库的更改。

• 已移除 已移除已弃用的 MAX_USER_TAGS 常量。使用 maxUserTags 代替。
• 已移除 已移除已弃用的 Metrics、Metric、Counter 和 Gauge 类，因为它们在 Dart 2.0 之后就一直无法使用。

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

• 已移除 已移除已弃用的 registerElement 和 registerElement2 方法在 Document 和 HtmlDocument 中。

• 语言版本化 Random 接口只能被实现，不能被扩展。

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

• 将更多代码标记为不可达，因为类型 Null 和 Never。
• 不要将不可访问的私有名称委托给 noSuchMethod.
• 报告编译时错误 针对顶层类型推断期间的所有循环依赖关系。

• 已移除 之前已弃用的 API [DEFAULT_BUFFER_SIZE] 在 JsonUtf8Encoder 中已被移除。

• 已移除 已移除之前已弃用的 API kInvalidParams、kExtensionError、kExtensionErrorMax 和 kExtensionErrorMin 在 ServiceExtensionResponse 中。

• 更改了 Pointer 的运行时类型参数为 Never，为完全移除运行时类型参数做准备。更改了 Pointer.toString，使其不再报告任何类型参数。

• 不允许使用负数或十六进制内容长度标头.
• File.create 现在接受新的可选 exclusive bool 参数，当它是 true 时，如果目标文件已存在，则操作将失败。
• 多次调用 ResourceHandle.toFile()、ResourceHandle.toSocket()、ResourceHandle.toRawSocket() 或 ResourceHandle.toRawDatagramSocket() 现在会引发 StateError。

• 恢复了 SendPort.send，使其在发送消息到已知不共享相同代码的隔离区之间时，恢复对消息内容的严格检查。

• 已移除 已移除 API MirrorsUsed 和 Comment。

• 预览功能 @staticInterop 的重大更改
  • 不允许使用此注释的类使用 external 生成式构造函数。有关更多详细信息，请参阅 48730 和 49941。
  • 不允许使用此注释的类的外部扩展成员使用类型参数.
  • 使用此注释的类还应具有 @JS 注释。
  • 使用此注释的类不能被没有此注释的类实现。

• dart2js 不再支持 HTTP URI 作为输入。.

• 删除了对不扩展 Object 的类的 mixin 支持。.

• 将 dart:io 中 RedirectException 的 uri 属性更改为可空。.
• 根据 SCREAMING_CAPS 约定，删除了 dart:io 网络 API 中的常量。.
• Dart VM 退出后不再自动恢复初始终端设置。

• 完全停止使用 .packages 文件。.

• 删除了独立的 dart2js 和 dartdevc 工具。.
• 删除了独立的 dartanalyzer 工具。.

• 在 HttpClient 中添加了新的 connectionFactory 属性。.
• 在 HttpClient 中添加了新的 keyLog 属性，它允许将 TLS 密钥记录到日志中以进行调试。
• 删除了 dart:io 中遵循 SCREAMING_CAPS 约定的常量。
• 在 SecurityContext 中添加了一个新的 allowLegacyUnsafeRenegotiation 属性，它允许为客户端安全套接字进行 TLS 重新协商。

• 已弃用 弃用了独立的 dart2js 工具。
• 已弃用 弃用了独立的 dartdevc 工具。
• 已移除 删除了独立的 dartdoc 工具。

• 在 Windows 上，Directory.rename 将不再删除目录，如果 newPath 指定了一个目录。相反，将抛出 FileSystemException。
• 已移除 删除了 Platform.packageRoot API。

• 已移除 删除了 Isolate.packageRoot API。

• 已弃用 弃用了独立的 dartanalyzer 工具。
• 已弃用 弃用了独立的 dartdoc 工具。
• 已移除 删除了已弃用的独立的 pub 工具。

• 更新了 SecurityContext 类，将最低 TLS 协议版本设置为 TLS1_2_VERSION (1.2) 而不是 TLS1_VERSION。

• 完全删除了 dart:web_sql 库。.

• 删除了 window.openDatabase（与上面删除的 dart:web_sql 相关）。

• 删除了独立的 dart2native 工具。.
• 删除了独立的 dartfmt 工具。

• 删除了对 dart-ext: 样式的原生扩展的支持。
• 将通过 Isolate.spawn() API 生成的隔离区分组，以在相同的托管堆上运行，因此共享各种 VM 内部数据结构。

• HttpClient 中的 setter 回调 .authenticate 和 .authenticateProxy 现在必须接受一个可空 realm 参数（针对迁移前的空安全代码）。

• 此库公开的大多数类型不再可以扩展、实现或混合。

• Expandos 和 Dart_NewWeakPersistentHandle 和 Dart_NewFinalizableHandle 的 object 参数不再接受 Pointer 和 Struct 的子类型。

• 弃用了独立的 dart2native 工具。
• 弃用了独立的 dartfmt 工具。

• dart2js 不再支持旧版浏览器，因为它默认情况下会生成 ES6+ JavaScript。

• 更改了 package:js 类的子类型关系，使其更准确并与 Dart2JS 保持一致。

• 不再有效 在非匿名 JS 互操作类中，将与 @Native 注释匹配的 String 用在 @JS() 注释中。

• 空安全 现在默认情况下在所有未选择退出代码中启用。
• 修复了实现错误，其中 this 有时会在扩展中进行类型提升。

• 弃用了使用泛型 T 的调用，例如 sizeOf<T>、Pointer<T>.elementAt()、Pointer<T extends Struct>.ref 和 Pointer<T extends Struct>[]。
• 弃用了 package:ffi 中的 allocate，因为它将不再能够泛型地调用 sizeOf<T>。
• 弃用了没有本地成员的 Struct 的子类型。.

• Dart_WeakPersistentHandle 不再在引用对象被垃圾回收时自动删除自身，以避免竞争条件。
• 将 Dart_WeakPersistentHandleFinalizer 重命名为 Dart_HandleFinalizer 并删除了它的 handle 参数。

• Dart SDK 约束现在在 pubspec.yaml 中是 **必需的**。.

• 将 dart_api_dl.cc 重命名为 dart_api_dl.c 并更改为纯 C 文件。

• 在将包含未配对代理的字符串编码为 UTF-8 时，未配对代理将被编码为替换字符 (U+FFFD)。
• 在解码 UTF-8 时，编码的代理将被视为格式错误的输入。
• 更改了为格式错误的输入序列发出的替换字符数量，使其与 WHATWG 编码标准 相匹配，当使用 allowMalformed: true 解码 UTF-8 时。

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

• Web 编译器 (dart2js 和 DDC) 现在会在导入 dart:mirrors 时产生编译时错误。

• 在使用 print 函数打印字符串时，默认实现将打印字符串中的任何未配对代理为替换字符 (U+FFFD)。
• Dart API 中的 Dart_StringToUTF8 函数将未配对代理转换为替换字符。

• 修复了实现错误，其中局部变量推断会错误地使用类型变量的提升类型。
• 修复了实现错误，围绕 implements Function、extends Function 或 with Function 子句不再生效，因为 Dart 2.0.0。

• 更改了 StreamSubscription.cancel() 的返回类型为 Future<void>。.
• 将 runZoned() 函数拆分为两个函数：runZoned() 和 runZonedGuarded()，其中后者有一个必需的 onError 参数，而前者没有。
• 传递给 Completer.completeError()、Stream.addError()、Future.error() 等的错误不再可以为空。
• 使堆栈跟踪不为空。.

• RuneIterator 上的三个成员在第一次调用 moveNext() 之前访问时不再返回 null。
• String.fromEnvironment() 的 defaultValue 默认值为现在是空字符串而不是 null。
• int.fromEnvironment() 的 defaultValue 参数的默认值为现在为零。

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

• 更改了 HttpHeaders 方法 add() 和 set 的签名。
• Socket 类现在在设置或获取套接字选项时抛出 SocketException，如果套接字已被显式销毁或升级为安全套接字。
• Process 类现在在访问 exitCode getter 时抛出 StateError，如果进程已分离（ProcessStartMode.detached 和 ProcessStartMode.detachedWithStdio）。
• Process 类现在也抛出，当未连接到子进程的 stdio（ProcessStartMode.detached 和 ProcessStartMode.inheritStdio）时，访问 stdin、stdout 和 stderr getter。
• 如果 FileStat.stat() 或 FileStat.statSync() 失败，则返回的虚拟对象现在包含 Unix 纪元时间戳，而不是 null，用于 accessed、changed 和 modified getter。
• HeaderValue 类现在在两个无效的边缘情况下解析得更严格。

我们修复了 DDC 和 Dart2JS 之间的一些不一致，这样用户就不太可能遇到一种编译器接受但另一种编译器失败的代码。

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

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

• macOS 的 Dart SDK 现在仅适用于 x64。.

• 使用前缀导入时，静态扩展成员可访问。.

• 添加了 IOOverrides.serverSocketBind，以帮助编写想要模拟 ServerSocket.bind 的测试。

• 更改了在 FutureOr 上下文中使用 Null 值时的推断。即，类似于 Null <: FutureOr<T> 的约束现在会产生 Null 作为 T 的解决方案。

• API 现在使用静态扩展成员。
• 删除了内存管理 Pointer.allocate 和 Pointer.free。
• Pointer.offsetBy 已删除，请改用 cast 和 elementAt。

• 各种核心库中的各种方法和属性，以前声明的返回类型为 List<int>，已更新为声明返回类型为 Uint8List。

• Cookie 类的构造函数的 name 和 value 可选位置参数现在是必须的。
• Cookie 类的 name 和 value setter 现在验证 字符串是否由允许的字符集组成，并且不为空。

• 发布到 pub.dev 的软件包不再可以包含 git 依赖项。

• 现在强制执行超级接口中使用的类型变量的协变。.

• 使用 dart2js 或 DDC 编译时，Isolate.resolvePackageUri 将始终抛出 UnsupportedError。

• 修复了 StreamIterator 类中的一个错误，其中 await for 允许 null 作为流。

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

• 现在对已关闭的 IOSink 添加内容会抛出 StateError。.

• 修复了使用 dart:mirrors 时的一个健全性漏洞，该漏洞以违反其静态类型的方式以不正确的方式反射地调用方法。

• 在 2.0.0 中，许多本应检测并报告的静态错误并未得到支持。现在报告了这些错误，这意味着现有的不正确代码可能会显示新的错误。
  • Mixin 必须正确地覆盖其超类。.
  • extends 子句中的隐式类型参数必须满足类边界。.
  • 实例成员应遮蔽前缀。.
  • 构造函数调用必须使用有效的语法，即使是可选的 new.
  • 泛型类型定义的类型参数必须满足其边界.
  • 类不能实现 FutureOr.
  • 抽象方法不能不合理地覆盖具体方法.
  • 常量构造函数不能重定向到非常量构造函数.
  • 不允许设置器与封闭类的名称相同.

• 常量映射中不允许重复键，会导致编译时错误。

• 用使用类型推断和运行时检查的健全静态类型系统替换了不健全的可选静态类型系统，以前称为 强模式。
• 标记为 async 的函数现在同步运行，直到第一个 await 语句。

• 将核心库中的常量从 SCREAMING_CAPS 重命名为 lowerCamelCase。
• 为核心库类添加了许多新方法，如果您实现这些类的接口，则需要实现这些方法。
• 使用 Dart 为网页开发时，不再支持 dart:isolate 和 dart:mirrors。

• 用 新的构建系统 替换了 pub 的基于转换器的构建系统。

除非另有说明，否则此网站上的文档反映了 Dart 3.5.3。 页面最后更新时间为 2024-08-06。 查看源代码 或 报告问题.