目录

Breaking changes and deprecations

This page lists all language and library breaking changes and deprecations in Dart, organized by release and area, to help Dart users understand and manage their impact. Complete release notes are available in the Dart SDK changelog. The breaking change policy document describes the policy and process around breaking changes and deprecations in Dart.

This page includes the following types of breaking changes:

  • Unversioned: The Dart SDK does not maintain backward compatibility, and code may break as soon as you upgrade your sdk version if it relies on the previous behavior.

    These are the majority of changes and are not specially marked in this list.

  • Language versioned: The Dart SDK maintains backward compatibility for existing code, and the behavior change only takes effect (potentially breaking code that relies on the previous behavior) when you upgrade the language version of your code.

    These are marked “Language versioned.

  • Deprecations: The Dart SDK maintains compatibility for deprecated code, with a warning. Deprecations are then completely removed in a subsequent release, breaking any code that relies on the previous behavior.

    These are marked “Deprecated” and “Removed”, respectively.

  • Experimental: Part of the release but not yet treated as stable in the SDK, and can break from one version to another. Experimental changes do not always have a corresponding breaking change issue, but may have more detail in the SDK changelog.

    These are marked “Experimental”, possibly in conjunction with another change type.

If you have questions or concerns about any of these breaking changes, please comment on the breaking change issue linked from the relevant entry. To be notified about future breaking changes, join the Dart announce group.

Not yet released to stable

Libraries

dart:nativewrappers

dart:typed_data

Released in 3.2.0

Language

Libraries

dart:cli

dart:convert

dart:developer

  • Deprecated: The Service.getIsolateID method.

dart:ffi

dart:io

dart:js_interop

  • Experimental Removed: JSNumber.toDart in favor of toDartDouble and toDartInt.
  • Experimental Removed: Object.toJS in favor of Object.toJSBox.
  • Experimental: Restricted external JS interop APIs using dart:js_interop to a set of allowed types.
  • Experimental: Prohibited use of isNull and isUndefined on dart2wasm.
  • Experimental: Changed typeofEquals and instanceof APIs to both return bool instead of JSBoolean. Also, typeofEquals now takes String instead of JSString.
  • Experimental: Changed JSAny and JSObject types to only implementable, not extendable, by user @staticInterop types.
  • Experimental: Changed JSArray.withLength to take int instead of JSNumber.

Tools

Development JavaScript compiler (DDC)

Production JavaScript compiler (dart2js)

Analyzer

Released in 3.1.0

Libraries

dart:async

dart:io

dart:js_interop

  • Experimental Removed: ObjectLiteral; create an object literal with no named members using {}.jsify().

package:js

  • external @staticInterop members and external extension members can no longer be used as tear-offs. Declare a closure or a non-external method that calls these members, and use that instead.
  • external @staticInterop members and external extension members will generate slightly different JS code for methods that have optional parameters.

Released in 3.0.0

Language

Libraries

  • The following existing classes have been made mixin classes: Iterable, IterableMixin, IterableBase, ListMixin, SetMixin, MapMixin, LinkedListEntry, StringConversionSink.

dart:core

dart:async

dart:collection

dart:developer

dart:html

dart:math

  • Language versioned: The Random interface can only be implemented, not extended.

dart:io

Released in 2.19.0

Language

Libraries

dart:convert

dart:developer

dart:ffi

dart:io

dart:isolate

  • Reverted SendPort.send back to strict checks on contents of messages when sending messages between isolates that are not known to share the same code.

dart:mirrors

package:js

dart2js

Released in 2.18.0

Language

Libraries

dart:io

Tools

Dart command line

Released in 2.17.0

Libraries

dart:io

Tools

Dart command line

Released in 2.16.0

Libraries

dart:io

dart:isolate

Tools

Dart command line

Released in 2.15.0

Libraries

dart:io

dart:web_sql

dart:html

Tools

Dart command line

Dart VM

Released in 2.14.0

Libraries

dart:io

  • The setter callbacks .authenticate and .authenticateProxy in HttpClient must now accept a nullable realm argument (for pre-migrated null safe code).

dart:typed_data

Tools

Dart VM

Dart command line

dart2js

Dart Dev Compiler (DDC)

Released in 2.13.0

Libraries

package:js

  • No longer valid to use a String that matches an @Native annotation in an @JS() annotation for a non-anonymous JS interop class.

Released in 2.12.0

Language

Libraries

dart:ffi

Tools

Dart VM

Pub

Released in 2.10.0

Tools

Dart VM

Released in 2.9.0

Libraries

dart:convert

dart:html

  • CssClassSet.add() and CssClassSet.toggle now return false instead of null if the CssClassSet corresponds to multiple elements.

dart:mirrors

Tools

Dart VM

Released in 2.8.1

Language

  • Fixed an implementation bug where local variable inference would incorrectly use the promoted type of a type variable.
  • Fixed an implementation bug surrounding the clauses implements Function, extends Function, or with Function no longer having an effect since Dart 2.0.0.

Libraries

dart:async

dart:core

dart:ffi

  • Changed Pointer.asFunction() and DynamicLibrary.lookupFunction() to extension methods.

dart:io

Tools

Dart Dev Compiler (DDC)

We fixed several inconsistencies between DDC and Dart2JS so that users less frequently encounter code that is accepted by one compiler but then fails in the other.

  • Deleted the legacy (analyzer based) version of DDC.
  • Functions passed to JavaScript using the recommended package:js interop specification must now be wrapped with a call to allowInterop.
  • Constructors in @JS() classes must be marked with external.

dart2js

  • Corresponding type parameter bounds now only need to be mutual subtypes rather than structurally equal up to renaming of bound type variables and equating all top types.
  • Types are now normalized.
  • Constructors in @JS() classes must be marked with external.
  • Completely removed the --package-root flag, which was hidden and disabled in Dart 2.0.0.

Released in 2.7.1

Released in 2.7.0

Language

Libraries

dart:io

  • Added IOOverrides.serverSocketBind to aid in writing tests that wish to mock ServerSocket.bind.

Released in 2.6.0

Language

Libraries

dart:ffi

  • The API now makes use of static extension members.
  • Removed memory management Pointer.allocate and Pointer.free.
  • Pointer.offsetBy was removed, use cast and elementAt instead.

Released in 2.5.0

Libraries

dart:io

Tools

Pub

Released in 2.4.0

Language

Libraries

dart:isolate

  • Isolate.resolvePackageUri will always throw an UnsupportedError when compiled with dart2js or DDC.

dart:async

Released in 2.2.0

Libraries

package:kernel

  • The klass getter on the InstanceConstant class in the Kernel AST API has been renamed to classNode for consistency.
  • Updated Link implementation to utilize true symbolic links instead of junctions on Windows.

Released in 2.1.1

Libraries

dart:io

Tools

Dart VM

Released in 2.1.0

Language

Tools

dart2js

  • Duplicate keys in a const map are not allowed and produce a compile-time error.

Released in 2.0.0

Language

Libraries

  • Renamed constants in the core libraries from SCREAMING_CAPS to lowerCamelCase.
  • Added many new methods to core library classes that will need to be implemented if you implement the interfaces of these classes.
  • dart:isolate and dart:mirrors are no longer supported when using Dart for the web.

Tools

Pub