修复类型提升失败

内容 keyboard_arrow_down keyboard_arrow_up

不支持字段提升的语言版本
只有局部变量可以提升（Dart 3.2 之前）
其他原因和解决方法

more_horiz

类型提升发生在流分析能够可靠地确认一个具有可空类型的变量 _不是_ 空，并且它不会从该点开始改变。许多情况可能会削弱类型的可靠性，导致类型提升失败。

此页面列出了类型提升失败的原因，以及如何修复它们的技巧。要了解更多关于流分析和类型提升的信息，请查看了解空安全页面。

原因：您正在尝试提升字段，但字段提升是语言版本化的，您的代码设置为 3.2 之前的语言版本。

如果您已经使用 SDK 版本 >= Dart 3.2，您的代码可能仍然明确地针对更早的语言版本。这可能发生在以下情况之一中：

您的 pubspec.yaml 声明了一个 SDK 约束，其下限低于 3.2，或者
您在文件顶部有一个 // @dart=version 注释，其中 version 低于 3.2。

示例

baddart// @dart=3.1

class C {
  final int? _i;
  C(this._i);

  void f() {
    if (_i != null) {
      int i = _i;  // ERROR
    }
  }
}

消息

'_i' refers to a field. It couldn't be promoted because field promotion is only available in Dart 3.2 and above.

解决方案

确保您的库没有使用早于 3.2 的语言版本。检查文件顶部是否有过时的 // @dart=version 注释，或您的 pubspec.yaml 是否有低于 3.2 的过时的 SDK 约束下限。

原因：您正在尝试提升属性，但只有局部变量可以在 Dart 3.2 之前的版本中提升，而您正在使用 3.2 之前的版本。

示例

baddartclass C {
  int? i;
  void f() {
    if (i == null) return;
    print(i.isEven);       // ERROR
  }
}

消息

'i' refers to a property so it couldn't be promoted.

解决方案

如果您正在使用 Dart 3.1 或更早的版本，请升级到 3.2 或更高版本。

如果您需要继续使用旧版本，请阅读其他原因和解决方法

此页面上的剩余示例记录了与版本不一致无关的提升失败原因，包括字段和局部变量失败，以及示例和解决方法。

一般来说，提升失败的常见修复方法是以下一项或多项：

将属性的值分配给一个具有所需非空类型的局部变量。
添加显式的空检查（例如，i == null）。
如果您确定表达式不可能为空，请使用 ! 或 as 作为冗余检查。

以下是如何创建局部变量（可以命名为 i）来保存 i 值的示例：

gooddartclass C {
  int? i;
  void f() {
    final i = this.i;
    if (i == null) return;
    print(i.isEven);
  }
}

此示例包含实例字段，但它也可以使用实例 Getter、静态字段或 Getter、顶层变量或 Getter，或 this。

以下是使用 i! 的示例：

gooddart

print(i!.isEven);

原因：您正在尝试提升 this，但目前不支持 this 的类型提升。

一种常见的 this 提升场景是在编写扩展方法时。如果扩展方法的 on 类型是可空类型，则需要进行空检查以查看 this 是否为空。

示例

baddartextension on int? {
  int get valueOrZero {
    return this == null ? 0 : this; // ERROR
  }
}

消息

`this` can't be promoted.

解决方案

创建一个局部变量来保存 this 的值，然后执行空检查。

gooddartextension on int? {
  int get valueOrZero {
    final self = this;
    return self == null ? 0 : self;
  }
}

原因：您正在尝试提升字段，但该字段不是私有的。

程序中的其他库可能使用 Getter 覆盖公共字段。因为 Getter 可能不会返回稳定的值，并且编译器无法知道其他库在做什么，所以非私有字段无法提升。

示例

baddartclass Example {
  final int? value;
  Example(this.value);
}

void test(Example x) {
  if (x.value != null) {
    print(x.value + 1); // ERROR
  }
}

消息

'value' refers to a public property so it couldn't be promoted.

解决方案

将字段设为私有，可以让编译器确定没有任何外部库可以覆盖其值，因此可以安全地提升。

gooddartclass Example {
  final int? _value;
  Example(this._value);
}

void test(Example x) {
  if (x._value != null) {
    print(x._value + 1);
  }
}

原因：您正在尝试提升字段，但该字段不是 final 的。

对于编译器来说，非 final 字段原则上可以在测试和使用它们之间随时修改。因此，对于编译器来说，将非 final 可空类型提升为非空类型是不安全的。

示例

baddartclass Example {
  int? _mutablePrivateField;
  Example(this._mutablePrivateField);

  void f() {
    if (_mutablePrivateField != null) {
      int i = _mutablePrivateField; // ERROR
    }
  }
}

消息

'_mutablePrivateField' refers to a non-final field so it couldn't be promoted.

解决方案

将字段设为 final

gooddartclass Example {
  final int? _immutablePrivateField;
  Example(this._immutablePrivateField);

  void f() {
    if (_immutablePrivateField != null) {
      int i = _immutablePrivateField; // OK
    }
  }
}

原因：您正在尝试提升 Getter，但只能提升实例 _字段_，不能提升实例 Getter。

编译器无法保证 getter 每次返回相同的结果。由于无法确认其稳定性，getter 不适合进行类型提升。

示例

baddartimport 'dart:math';

abstract class Example {
  int? get _value => Random().nextBool() ? 123 : null;
}

void f(Example x) {
  if (x._value != null) {
    print(x._value.isEven); // ERROR
  }
}

消息

'_value' refers to a getter so it couldn't be promoted.

解决方案

将 getter 赋值给局部变量

gooddartimport 'dart:math';

abstract class Example {
  int? get _value => Random().nextBool() ? 123 : null;
}

void f(Example x) {
  final value = x._value;
  if (value != null) {
    print(value.isEven); // OK
  }
}

原因：你试图提升一个字段，但该字段被标记为 external。

外部字段不会提升，因为它们本质上是外部 getter；它们的实现来自 Dart 之外的代码，因此编译器无法保证外部字段在每次调用时都会返回相同的值。

示例

baddartclass Example {
  external final int? _externalField;

  void f() {
    if (_externalField != null) {
      print(_externalField.isEven); // ERROR
    }
  }
}

消息

'_externalField' refers to an external field so it couldn't be promoted.

解决方案

将外部字段的值赋值给局部变量

gooddartclass Example {
  external final int? _externalField;

  void f() {
    final i = _externalField;
    if (i != null) {
      print(i.isEven); // OK
    }
  }
}

原因：你试图提升一个字段，但同一库中的另一个类包含一个具有相同名称的具体 getter。

示例

baddartimport 'dart:math';

class Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? get _overridden => Random().nextBool() ? 1 : null;
}

void testParity(Example x) {
  if (x._overridden != null) {
    print(x._overridden.isEven); // ERROR
  }
}

消息

'_overriden' couldn't be promoted because there is a conflicting getter in class 'Override'.

解决方案:

如果 getter 和字段相关联且需要共享其名称（例如，当其中一个覆盖另一个时，如上面的示例所示），那么你可以通过将值赋值给局部变量来启用类型提升

gooddartimport 'dart:math';

class Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? get _overridden => Random().nextBool() ? 1 : null;
}

void testParity(Example x) {
  final i = x._overridden;
  if (i != null) {
    print(i.isEven); // OK
  }
}

请注意，在上面的示例中，很明显为什么提升字段 _overridden 不安全：因为字段和 getter 之间存在覆盖关系。但是，即使类不相关，冲突的 getter 也会阻止字段提升。例如

baddartimport 'dart:math';

class Example {
  final int? _i;
  Example(this._i);
}

class Unrelated {
  int? get _i => Random().nextBool() ? 1 : null;
}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // ERROR
  }
}

另一个库可能包含一个类，该类将两个不相关的类组合到同一个类层次结构中，这会导致函数 f 中对 x._i 的引用被分派到 Unrelated._i。例如

baddartclass Surprise extends Unrelated implements Example {}

void main() {
  f(Surprise());
}

解决方案

如果字段和冲突的实体确实不相关，你可以通过为它们指定不同的名称来解决问题

gooddartclass Example {
  final int? _i;
  Example(this._i);
}

class Unrelated {
  int? get _j => Random().nextBool() ? 1 : null;
}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // OK
  }
}

原因：你试图提升一个字段，但同一库中的另一个类包含一个具有相同名称的不可提升字段（由于本页面列出的任何其他原因）。

示例

baddartclass Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? _overridden;
}

void f(Example x) {
  if (x._overridden != null) {
    print(x._overridden.isEven); // ERROR
  }
}

此示例失败，因为在运行时，x 实际上可能是 Override 的实例，因此提升将不安全。

消息

'overridden' couldn't be promoted because there is a conflicting non-promotable field in class 'Override'.

解决方案

如果字段实际上相关联且需要共享名称，那么你可以通过将值赋值给最终的局部变量来启用类型提升

gooddartclass Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? _overridden;
}

void f(Example x) {
  final i = x._overridden;
  if (i != null) {
    print(i.isEven); // OK
  }
}

如果字段不相关，则重命名其中一个字段，以便它们不冲突。请阅读关于无关类的说明。

原因：你试图提升一个私有且最终的字段，但同一库中的另一个类包含一个隐式 noSuchMethod 转发器，其名称与该字段相同。

这是不安全的，因为无法保证 noSuchMethod 会从一次调用到下一次调用返回稳定的值。

示例

baddartimport 'package:mockito/mockito.dart';

class Example {
  final int? _i;
  Example(this._i);
}

class MockExample extends Mock implements Example {}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // ERROR
  }
}

在此示例中，_i 无法提升，因为它可能解析为不安全的隐式 noSuchMethod 转发器（也称为 _i），编译器在 MockExample 中生成该转发器。

编译器创建了 _i 的此隐式实现，因为 MockExample 在其声明中承诺支持 _i 的 getter，但未履行该承诺。因此，未定义的 getter 实现由Mock 的 noSuchMethod 定义处理，该定义创建了相同名称的隐式 noSuchMethod 转发器。

该错误也可能发生在无关类中的字段之间。

消息

'_i' couldn't be promoted because there is a conflicting noSuchMethod forwarder in class 'MockExample'.

解决方案

定义有问题的 getter，以便 noSuchMethod 不必隐式处理其实现

gooddartimport 'package:mockito/mockito.dart';

class Example {
  final int? _i;
  Example(this._i);
}

class MockExample extends Mock implements Example {
  @override
  late final int? _i;
}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // OK
  }
}

getter 被声明为 late 以与模拟的常规使用方式一致；在不涉及模拟的情况下，无需将 getter 声明为 late 来解决此类型提升错误。

原因：你试图提升一个自上次提升后可能已被写入的变量。

示例

baddartvoid f(bool b, int? i, int? j) {
  if (i == null) return;
  if (b) {
    i = j;           // (1)
  }
  if (!b) {
    print(i.isEven); // (2) ERROR
  }
}

解决方案:

在此示例中，当流程分析到达 (1) 时，它会将 i 从不可为空的 int 降级回可为空的 int?。人类可以判断 (2) 处的访问是安全的，因为没有代码路径同时包含 (1) 和 (2)，但流程分析不够智能，无法识别这一点，因为它不会跟踪不同 if 语句中条件之间的相关性。

你可以通过组合两个 if 语句来解决问题

gooddartvoid f(bool b, int? i, int? j) {
  if (i == null) return;
  if (b) {
    i = j;
  } else {
    print(i.isEven);
  }
}

在像这样的直线控制流情况（没有循环）中，流程分析在决定是否降级时会考虑赋值的右侧。因此，解决此代码的另一种方法是将 j 的类型更改为 int。

gooddartvoid f(bool b, int? i, int j) {
  if (i == null) return;
  if (b) {
    i = j;
  }
  if (!b) {
    print(i.isEven);
  }
}

原因：你试图提升可能在循环的先前迭代中已被写入的内容，因此提升无效。

示例

baddartvoid f(Link? p) {
  if (p != null) return;
  while (true) {    // (1)
    print(p.value); // (2) ERROR
    var next = p.next;
    if (next == null) break;
    p = next;       // (3)
  }
}

当流程分析到达 (1) 时，它会向前看，并看到 (3) 处对 p 的写入。但因为它正在向前看，所以它还没有确定赋值右侧的类型，因此它不知道是否可以安全地保留提升。为了安全起见，它会使提升无效。

解决方案:

你可以通过将空检查移至循环的顶部来解决此问题

gooddartvoid f(Link? p) {
  while (p != null) {
    print(p.value);
    p = p.next;
  }
}

如果 case 块有标签，这种情況也可能出现在 switch 语句中，因为你可以使用带标签的 switch 语句来构造循环

baddartvoid f(int i, int? j, int? k) {
  if (j == null) return;
  switch (i) {
    label:
    case 0:
      print(j.isEven); // ERROR
      j = k;
      continue label;
  }
}

同样，你可以通过将空检查移至循环的顶部来解决此问题

gooddartvoid f(int i, int? j, int? k) {
  switch (i) {
    label:
    case 0:
      if (j == null) return;
      print(j.isEven);
      j = k;
      continue label;
  }
}

原因：该变量可能在 try 块中已被写入，并且现在正在 catch 块中执行。

示例

baddartvoid f(int? i, int? j) {
  if (i == null) return;
  try {
    i = j;                 // (1)
    // ... Additional code ...
    if (i == null) return; // (2)
    // ... Additional code ...
  } catch (e) {
    print(i.isEven);       // (3) ERROR
  }
}

在这种情况下，流程分析认为 i.isEven (3) 不安全，因为它无法知道异常可能在 try 块中的何处发生，因此它保守地假设它可能发生在 (1) 和 (2) 之间，此时 i 可能为 null。

类似的情况可能发生在 try 和 finally 块之间，以及 catch 和 finally 块之间。由于实现方式的历史原因，这些 try/catch/finally 情况不会考虑赋值的右侧，类似于循环中发生的情况。

解决方案:

要解决此问题，请确保 catch 块不依赖于关于在 try 块中更改的变量状态的假设。请记住，异常可能在 try 块中的任何时候发生，可能是在 i 为 null 时。

最安全的解决方案是在 catch 块中添加一个空检查

gooddarttry {
  // ···
} catch (e) {
  if (i != null) {
    print(i.isEven); // (3) OK due to the null check in the line above.
  } else {
    // Handle the case where i is null.
  }
}

或者，如果你确定异常不可能在 i 为 null 时发生，只需使用 ! 运算符

darttry {
  // ···
} catch (e) {
  print(i!.isEven); // (3) OK because of the `!`.
}

原因：你试图提升的类型不是变量当前提升类型的子类型（或在尝试提升时不是子类型）。

示例

baddartvoid f(Object o) {
  if (o is Comparable /* (1) */) {
    if (o is Pattern /* (2) */) {
      print(o.matchAsPrefix('foo')); // (3) ERROR
    }
  }
}

在此示例中，o 在 (1) 处提升为 Comparable，但在 (2) 处未提升为 Pattern，因为 Pattern 不是 Comparable 的子类型。（原因是如果它确实提升了，那么你将无法使用 Comparable 上的方法。）请注意，仅仅因为 Pattern 不是 Comparable 的子类型并不意味着 (3) 处的代码是死的；o 可能具有一个类型（例如 String），该类型同时实现了 Comparable 和 Pattern。

解决方案:

一种可能的解决方案是创建一个新的局部变量，以便将原始变量提升为 Comparable，并将新变量提升为 Pattern

dartvoid f(Object o) {
  if (o is Comparable /* (1) */) {
    Object o2 = o;
    if (o2 is Pattern /* (2) */) {
      print(
          o2.matchAsPrefix('foo')); // (3) OK; o2 was promoted to `Pattern`.
    }
  }
}

但是，稍后编辑代码的人可能会倾向于将 Object o2 更改为 var o2。此更改会使 o2 的类型为 Comparable，这又会带来对象无法提升为 Pattern 的问题。

冗余类型检查可能是一个更好的解决方案

gooddartvoid f(Object o) {
  if (o is Comparable /* (1) */) {
    if (o is Pattern /* (2) */) {
      print((o as Pattern).matchAsPrefix('foo')); // (3) OK
    }
  }
}

另一种有时有效的解决方案是在可以使用更精确的类型时。如果第 3 行只关心字符串，那么你可以在类型检查中使用 String。由于 String 是 Comparable 的子类型，因此提升有效

gooddartvoid f(Object o) {
  if (o is Comparable /* (1) */) {
    if (o is String /* (2) */) {
      print(o.matchAsPrefix('foo')); // (3) OK
    }
  }
}

原因：该变量已被局部函数或函数表达式写入捕获。

示例

baddartvoid f(int? i, int? j) {
  var foo = () {
    i = j;
  };
  // ... Use foo ... 
  if (i == null) return; // (1)
  // ... Additional code ...
  print(i.isEven);       // (2) ERROR
}

流程分析认为，一旦到达 foo 的定义，它就可能在任何时候被调用，因此不再安全地提升 i。与循环一样，这种降级会发生，无论赋值右侧的类型是什么。

解决方案:

有时可以重新组织逻辑，以便在写入捕获之前进行提升

gooddartvoid f(int? i, int? j) {
  if (i == null) return; // (1)
  // ... Additional code ...
  print(i.isEven); // (2) OK
  var foo = () {
    i = j;
  };
  // ... Use foo ...
}

另一个选择是创建一个局部变量，以便它不会被写入捕获

gooddartvoid f(int? i, int? j) {
  var foo = () {
    i = j;
  };
  // ... Use foo ...
  var i2 = i;
  if (i2 == null) return; // (1)
  // ... Additional code ...
  print(i2.isEven); // (2) OK because `i2` isn't write captured.
}

或者你可以进行冗余检查

dartvoid f(int? i, int? j) {
  var foo = () {
    i = j;
  };
  // ... Use foo ...
  if (i == null) return; // (1)
  // ... Additional code ...
  print(i!.isEven); // (2) OK due to `!` check.
}

原因：该变量在闭包或函数表达式之外被写入，并且类型提升位置在闭包或函数表达式内部。

示例

baddartvoid f(int? i, int? j) {
  if (i == null) return;
  var foo = () {
    print(i.isEven); // (1) ERROR
  };
  i = j;             // (2)
}

流程分析认为，无法确定 foo 可能在何时被调用，因此它可能在 (2) 处的赋值之后被调用，因此提升可能不再有效。与循环一样，这种降级会发生，无论赋值右侧的类型是什么。

解决方案:

一个解决方案是创建一个局部变量

gooddartvoid f(int? i, int? j) {
  if (i == null) return;
  var i2 = i;
  var foo = () {
    print(i2.isEven); // (1) OK because `i2` isn't changed later.
  };
  i = j; // (2)
}

示例

一个特别糟糕的情况如下所示

baddartvoid f(int? i) {
  i ??= 0;
  var foo = () {
    print(i.isEven); // ERROR
  };
}

在这种情况下，人类可以看出促销是安全的，因为唯一写入i的操作使用了一个非空值，并且发生在创建foo之前。但流程分析并不那么智能。

解决方案:

同样，一个解决方案是创建一个局部变量

gooddartvoid f(int? i) {
  var j = i ?? 0;
  var foo = () {
    print(j.isEven); // OK
  };
}

此解决方案有效，因为j推断为具有非空类型（int），因为其初始值为（i ?? 0）。由于j具有非空类型，无论它是否在以后被赋值，j永远不会具有非空值。

原因：您试图提升的变量是在闭包或函数表达式之外捕获的写入，但此变量的使用位于尝试提升它的闭包或函数表达式内部。

示例

baddartvoid f(int? i, int? j) {
  var foo = () {
    if (i == null) return;
    print(i.isEven); // ERROR
  };
  var bar = () {
    i = j;
  };
}

流程分析认为无法确定foo和bar可能以何种顺序执行；事实上，bar甚至可能在执行foo的过程中执行（因为foo调用了调用bar的东西）。因此，在foo内部提升i并不安全。

解决方案:

最佳解决方案可能是创建一个局部变量

gooddartvoid f(int? i, int? j) {
  var foo = () {
    var i2 = i;
    if (i2 == null) return;
    print(i2.isEven); // OK because i2 is local to this closure.
  };
  var bar = () {
    i = j;
  };
}

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

修复类型提升失败

不支持字段提升的语言版本

只有局部变量可以提升（Dart 3.2 之前）

其他原因和解决方法

无法提升 `this`

只能提升私有字段

只能提升 final 字段

无法提升 Getter

无法提升外部字段

与库中其他地方的 Getter 冲突

关于无关类的说明

与库中其他地方的不可提升字段冲突

与隐式 `noSuchMethod` 转发器冲突

可能在提升之后写入

可能在之前的循环迭代中写入

在 try 中可能写入后的 catch 中

子类型不匹配

由局部函数捕获的写入

在当前闭包或函数表达式之外写入

在当前闭包或函数表达式之外捕获的写入

修复类型提升失败

不支持字段提升的语言版本

只有局部变量可以提升（Dart 3.2 之前）

其他原因和解决方法

无法提升 this

只能提升私有字段

只能提升 final 字段

无法提升 Getter

无法提升外部字段

与库中其他地方的 Getter 冲突

关于无关类的说明

与库中其他地方的不可提升字段冲突

与隐式 noSuchMethod 转发器冲突

可能在提升之后写入

可能在之前的循环迭代中写入

在 try 中可能写入后的 catch 中

子类型不匹配

由局部函数捕获的写入

在当前闭包或函数表达式之外写入

在当前闭包或函数表达式之外捕获的写入

无法提升 `this`

与隐式 `noSuchMethod` 转发器冲突