模式类型

目录 keyboard_arrow_down keyboard_arrow_up

逻辑或
逻辑与
关系
强制类型转换
空检查
空断言
常量
变量
标识符
带括号的
列表
- 剩余元素
映射
记录
对象
通配符

more_horiz

本页面是对各种模式的参考。有关模式的工作原理、在 Dart 中可以使用模式的位置以及常见用例的概述，请访问主模式页面。

类似于运算符优先级，模式评估遵循优先级规则。您可以使用带括号的模式来优先评估低优先级模式。

本文档按优先级升序列出模式类型：

逻辑或模式的优先级低于逻辑与模式，逻辑与模式的优先级低于关系模式，依此类推。
后缀一元模式（强制类型转换、空检查和空断言）具有相同的优先级。
其余主模式共享最高的优先级。集合类型（记录、列表和映射）和对象模式包含其他数据，因此首先作为外部模式进行评估。

subpattern1 || subpattern2

逻辑或模式用 || 分隔子模式，如果任何分支匹配，则匹配成功。分支从左到右进行评估。一旦一个分支匹配，其余分支将不会被评估。

dartvar isPrimary = switch (color) {
  Color.red || Color.yellow || Color.blue => true,
  _ => false
};

逻辑或模式中的子模式可以绑定变量，但分支必须定义相同的变量集，因为当模式匹配时，只有一个分支会被评估。

subpattern1 && subpattern2

只有当两个子模式都匹配时，用 && 分隔的一对模式才匹配。如果左分支不匹配，则右分支不会被评估。

逻辑与模式中的子模式可以绑定变量，但每个子模式中的变量不得重叠，因为如果模式匹配，它们都会被绑定：

dartswitch ((1, 2)) {
  // 错误，两个子模式都尝试绑定 'b'。
  case (var a, var b) && (var b, var c): // ...
}

== expression

< expression

关系模式使用任何相等或关系运算符（ == 、 != 、 < 、 > 、 <= 和 >= ）将匹配的值与给定常量进行比较。

当使用常量作为参数对匹配的值调用相应的运算符返回 true 时，模式匹配成功。

关系模式对于匹配数值范围非常有用，尤其是在与逻辑与模式结合使用时：

dartString asciiCharType(int char) {
  const space = 32;
  const zero = 48;
  const nine = 57;

  return switch (char) {
    < space => 'control',
    == space => 'space',
    > space && < zero => 'punctuation',
    >= zero && <= nine => 'digit',
    _ => ''
  };
}

foo as String

强制类型转换模式允许您在解构中间插入类型转换，然后再将值传递给另一个子模式：

dart(num, Object) record = (1, 's');
var (i as int, s as String) = record;

如果值没有声明的类型，强制类型转换模式将抛出异常。与空断言模式一样，这允许您强制断言某些解构值的预期类型。

subpattern?

如果值不为 null，空检查模式首先匹配，然后将内部模式与相同的值进行匹配。它们允许您绑定一个变量，该变量的类型是正在匹配的可空值的非空基类型。

要将 null 值视为匹配失败而不会抛出异常，请使用空检查模式。

dartString? maybeString = 'nullable with base type String';
switch (maybeString) {
  case var s?:
  // 's' 在此处具有非空 String 类型。
}

要匹配值为 null 的情况，请使用常量模式null 。

subpattern!

如果对象不为 null，空断言模式首先匹配，然后匹配该值。它们允许非空值流过，但如果匹配的值为 null，则抛出异常。

为了确保 null 值不会被默默地视为匹配失败，在匹配时使用空断言模式：

dartList<String?> row = ['user', null];
switch (row) {
  case ['user', var name!]: // ...
  // 'name' 在此处是非空字符串。
}

要从变量声明模式中消除 null 值，请使用空断言模式：

dart(int?, int?) position = (2, 3);

var (x!, y!) = position;

要匹配值为 null 的情况，请使用常量模式null 。

123, null, 'string', math.pi, SomeClass.constant, const Thing(1, 2), const (1 + 2)

当值等于常量时，常量模式匹配成功：

dartswitch (number) {
  // 如果 1 == number，则匹配。
  case 1: // ...
}

您可以直接使用简单的字面量和命名常量的引用作为常量模式：

数字字面量（ 123 、 45.56 ）
布尔字面量（ true ）
字符串字面量（ 'string' ）
命名常量（ someConstant 、 math.pi 、 double.infinity ）
常量构造函数（ const Point(0, 0) ）
常量集合字面量（ const [] 、 const {1, 2} ）

更复杂的常量表达式必须用括号括起来并以 const 为前缀（ const (1 + 2) ）：

dart// 列表或映射模式：
case [a, b]: // ...

// 列表或映射字面量：
case const [a, b]: // ...

var bar, String str, final int _

变量模式将新变量绑定到已匹配或解构的值。它们通常作为解构模式的一部分出现，以捕获解构的值。

这些变量在代码区域内有效，该区域只有在模式匹配时才能访问。

dartswitch ((1, 2)) {
  // 'var a' 和 'var b' 是将分别绑定到 1 和 2 的变量模式。
  case (var a, var b): // ...
  // 'a' 和 'b' 在 case 主体中有效。
}

类型化 变量模式只有在匹配的值具有声明的类型时才匹配，否则失败：

dartswitch ((1, 2)) {
  // 不匹配。
  case (int a, String b): // ...
}

您可以使用通配符模式作为变量模式。

foo, _

标识符模式的行为可能像常量模式或变量模式，这取决于它们出现的上下文：

声明上下文：声明一个具有标识符名称的新变量： var (a, b) = (1, 2);
赋值上下文：赋值给具有标识符名称的现有变量： (a, b) = (3, 4);

匹配上下文：被视为命名常量模式（除非其名称为 _ ）：

dartconst c = 1;
switch (2) {
  case c:
    print('match $c');
  default:
    print('no match'); // 打印“no match”。
}

任何上下文中的通配符标识符：匹配任何值并丢弃它： case [_, var y, _]: print('The middle element is $y');

(subpattern)

与带括号的表达式一样，模式中的括号允许您控制模式优先级并在预期高优先级模式的位置插入低优先级模式。

例如，假设布尔常量 x 、 y 和 z 分别等于 true 、 true 和 false 。尽管以下示例类似于布尔表达式求值，但该示例匹配模式。

dart// ...
x || y => 'matches true',
x || y && z => 'matches true',
x || (y && z) => 'matches true',
// `x || y && z` 与 `x || (y && z)` 相同。
(x || y) && z => 'matches nothing',
// ...

Dart 从左到右开始匹配模式。

第一个模式匹配 true ，因为 x 匹配 true 。
第二个模式匹配 true ，因为 x 匹配 true 。
第三个模式匹配 true ，因为 x 匹配 true 。
第四个模式 (x || y) && z 没有匹配。
- x 匹配 true ，因此 Dart 不会尝试匹配 y 。
- 尽管 (x || y) 匹配 true ，但 z 不匹配 true
- 因此，模式 (x || y) && z 不匹配 true 。
- 子模式 (x || y) 不匹配 false ，因此 Dart 不会尝试匹配 z 。
- 因此，模式 (x || y) && z 不匹配 false 。
- 综上所述， (x || y) && z 没有匹配。

[subpattern1, subpattern2]

列表模式匹配实现 List 的值，然后递归地将它的子模式与列表的元素进行匹配，以按位置对其进行解构：

dartconst a = 'a';
const b = 'b';
switch (obj) {
  // 列表模式 [a, b] 首先匹配 obj，如果 obj 是一个具有两个字段的列表，
  // 然后如果它的字段匹配常量子模式 'a' 和 'b'。
  case [a, b]:
    print('$a, $b');
}

列表模式要求模式中的元素数量与整个列表匹配。但是，您可以使用剩余元素作为占位符来解释列表中任意数量的元素。

列表模式可以包含一个剩余元素（ ... ），它允许匹配任意长度的列表。

dartvar [a, b, ..., c, d] = [1, 2, 3, 4, 5, 6, 7];
// 打印“1 2 6 7”。
print('$a $b $c $d');

剩余元素也可以有一个子模式，该子模式将不匹配列表中其他子模式的元素收集到一个新的列表中：

dartvar [a, b, ...rest, c, d] = [1, 2, 3, 4, 5, 6, 7];
// 打印“1 2 [3, 4, 5] 6 7”。
print('$a $b $rest $c $d');

{"key": subpattern1, someConst: subpattern2}

映射模式匹配实现 Map 的值，然后递归地将它的子模式与映射的键进行匹配以对其进行解构。

映射模式不要求模式匹配整个映射。映射模式会忽略映射包含的任何未被模式匹配的键。

(subpattern1, subpattern2)

(x: subpattern1, y: subpattern2)

记录模式匹配记录对象并解构其字段。如果值不是与模式具有相同形状的记录，则匹配失败。否则，字段子模式将与记录中相应的字段进行匹配。

记录模式要求模式匹配整个记录。要使用模式解构具有命名字段的记录，请在模式中包含字段名称：

dart

var (myString: foo, myNumber: bar) = (myString: 'string', myNumber: 1);

getter名称可以省略，并从变量模式推断。

或者字段子模式中的标识符模式。这些模式对是等价的：

dart// 使用变量子模式的记录模式：
var (untyped: untyped, typed: int typed) = record;
var (:untyped, :int typed) = record;

switch (record) {
  case (untyped: var untyped, typed: int typed): // ...
  case (:var untyped, :int typed): // ...
}

// 使用空检查和空断言子模式的记录模式：
switch (record) {
  case (checked: var checked?, asserted: var asserted!): // ...
  case (:var checked?, :var asserted!): // ...
}

// 使用强制类型转换子模式的记录模式：
var (untyped: untyped as int, typed: typed as String) = record;
var (:untyped as int, :typed as String) = record;

SomeClass(x: subpattern1, y: subpattern2)

对象模式使用对象属性上的 getter 来检查匹配的值与给定的命名类型是否匹配以解构数据。如果值没有相同的类型，则会被驳斥。

dartswitch (shape) {
  // 如果 shape 的类型为 Rect，则匹配，然后与 Rect 的属性进行匹配。
  case Rect(width: var w, height: var h): // ...
}

getter名称可以省略，并从字段子模式中的变量模式或标识符模式推断：

dart// 将新的变量 x 和 y 绑定到 Point 的 x 和 y 属性的值。
var Point(:x, :y) = Point(1, 2);

对象模式不要求模式匹配整个对象。如果对象具有模式未解构的额外字段，它仍然可以匹配。

_

名为 _ 的模式是一个通配符，它是一个变量模式或标识符模式，它不绑定或分配给任何变量。

它在需要子模式才能解构后面的位置值的地方很有用：

dartvar list = [1, 2, 3];
var [_, two, _] = list;

当您想要测试值的类型但不将值绑定到名称时，带有类型注解的通配符名称很有用：

dartswitch (record) {
  case (int _, String _):
    print('First field is int and second is String.');
}

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。查看源代码或报告问题.