目录

Contents

Dart 2 迁移指南

目录

Contents

Dart 2 有一些与早期版本 Dart 不同的关键点。本文将会简单地介绍这些差异并提供了一些将代码迁移到 Dart 2 的建议。

Dart 2 has a few key differences from earlier versions of Dart. This page briefly covers those differences and gives general advice on migrating your code to Dart 2.

至于 为什么 Dart 2 要做这些改变，你可以查阅 Dart 2 公告

For information on why Dart 2 has changed, see the Dart 2 announcement.

差异点

Differences

Dart 语言、库、编译系统以及 Web 开发工具都已经有所变化。

The Dart language, libraries, build system, and web development tools have changed.

语言和库

Language and libraries

工具

Tools

迁移你的代码

Migrating your code

如何迁移你的代码取决于你的代码有多古老以及运行在什么平台。有关如何迁移 Web 应用的帮助请查阅 Web 应用迁移指南。如果你迁移一个 Flutter 应用，请查阅 变革公告 如果你发布了 package，则除了适配平台不同的特性之外，还需要遵循 下述的 package 迁移说明。

How to migrate your code depends on how old your code is and what platforms it runs on. For help with migrating web apps, see the web app migration guide. If you’re migrating a Flutter app, consult the breaking change notification. If you publish packages, then in addition to making platform-specific changes, follow the package migration instructions below.

通用流程

General process

下面是迁移到 Dart 2 的一个流程概述。

Here’s an overview of the process of migrating to Dart 2, from either Dart 1.x or an earlier version of Dart 2.

  1. 获取一个最新的 Flutter 或 Dart SDK 版本以及你所使用的 IDE 的最新插件。

    Get an up-to-date version of the Flutter or Dart SDK and the plugins for any IDEs you use.

  2. 升级你应用依赖的 package。

    Upgrade the packages your app depends on.

  3. 运行 dart2_fix 工具 它可以帮助迁移一些过时的 Dart 1.x API 到 Dart 2。

    Run the dart2_fix tool. It helps migrate some usages of deprecated Dart 1.x APIs to Dart 2.

  4. 运行分析器以找出 编译时错误 以及弃用提示。

    Run the analyzer to find compile-time errors and deprecation hints.

  5. 修复代码问题并再次运行分析器，重复该操作直到你的代码通过静态分析。

    Fix issues in your code and run the analyzer again, repeating until your code passes static analysis.

  6. 运行测试以找出 运行时错误

    Run tests to find runtime errors.

    • 运行你软件所有的 [自动化测试]。

      Run all automated tests for your software.

    • 执行手动测试以查找控制台错误。

      Do manual testing, and look for console errors.

    考虑添加自动化测试来捕获你发现的问题。

    Consider adding automated tests to catch issues that you find.

  7. 修复问题知道你的代码可以正常运行。

    Fix issues until your code works.

  8. 可选的： 移除 new 以及不必要的 const 关键字。

    Optional: Remove new and unnecessary const.

    • 你可以手动地移除它们或者使用类似 dart format --fix 这样的工具。

      You can remove these by hand or use a tool such as dart format --fix.

    • 为了找到 new 和不必要的 const 出现的地方，可以将 unnecessary_new 和 unnecessary_const 规则添加至 分析选项文件 的 linter 部分。

      To find occurrences of new and unnecessary const, add the rules unnecessary_new and unnecessary_const to the linter section of your analysis options file.

迁移 package

Migrating packages

作为一个 package 的拥有者，你需要遵循下列几项：

As a package owner, you need to do the following:

  • 遵循你的 package 所支持的平台的迁移技巧（详见 上述）。

    Follow the migration tips for the platforms that your package supports (see above).

  • 确保你的 package 通过了 Dart 2 分析（查阅上面的运行分析器）。

    Make sure your package passes Dart 2 analysis (see Run the analyzer above)

  • 确保你 package 的使用者知道如何上报问题。

    Make sure your package’s users know how to report issues.

  • 能够对上报的问题快速地作出响应。

    Respond quickly to issue reports.

  • 如果代码的变更导致无法向后兼容，请升级最低的 SDK 版本限制。

    If code changes aren’t backward compatible, update the lower SDK constraint.

变化以及向后兼容性

Changes and backward compatibility

如果你必须更改 package 的代码，请 尝试令其可以在 1.x 中使用，就像其在 Dart 2 中使用那样。例如，你可能需要添加类型注解（或者如果一个已被移除的 API）去使用一个替代的 1.x API。

If you have to change your package’s code, try to make it work in 1.x, as well as Dart 2. For example, you might be able to add type annotations or (if an API has been removed) to use an alternative 1.x API.

如果代码的变更导致无法向后兼容，请升级最低的 SDK 限制

If a backward-compatible change isn’t possible, update the lower SDK constraint.

测试你代码的变更 以确保你的 package 在使用时可以如你所愿地运行。

Test your changes to make sure that your package works as expected.

SDK 版本上限

Upper constraints on the SDK version

一旦你的 package 通过了 Dart 2 分析，请更新版本上限以表明其支持兼容到 Dart 2：

Once your package passes Dart 2 analysis, update the upper constraint to declare that the package is compatible with Dart 2:

environment:
  # 只能在 Dart 2 中使用
  sdk: '>=2.0.0 <3.0.0'

如果你计划保持与旧版 Dart 的兼容性，请相应地调整 SDK 为较低的版本限制：

If you plan to maintain compatibility with older versions of Dart, adjust the lower SDK constraint accordingly:

environment:
  # 可以在 Dart 1（1.20.1 开始）以及 Dart 2 中使用。
  sdk: '>=1.20.1 <3.0.0'

如果你使用 2.0 后引入的功能 请确保你指定了正确的 SDK 下限：

If you use features introduced after 2.0, be sure to specify the correct lower SDK constraint:

environment:
  # 可以在 2.1 中使用但不能在 2.0 中使用
  sdk: '>=2.1.0 <3.0.0'

更多资源

More resources