2025-09-03发表2025-09-11更新ai / dart16 分钟读完 (大约2359个字)0次访问

Records

版本说明
记录（Record）需要语言版本至少为 3.0。

记录是一种匿名的、不可变的、聚合的类型。像其他集合类型一样，它们允许你将多个对象捆绑到一个对象中。与其他集合类型不同，记录是固定大小、异构且类型化的。

记录是真实的值；你可以将它们存储在变量中、嵌套它们、作为函数的参数传递或从函数返回，以及将它们存储在诸如列表、映射和集合等数据结构中。

记录语法

记录表达式是由逗号分隔的命名或位置字段列表，并用圆括号括起来：

1	var record = ('first', a: 2, b: true, 'last');

记录类型注解是由逗号分隔的类型列表，并用圆括号括起来。你可以使用记录类型注解来定义返回类型和参数类型。例如，下面 (int, int) 语句就是记录类型注解：

(int, int) swap((int, int) record) {
  var (a, b) = record;
  return (b, a);
}

记录表达式和类型注解中的字段反映了函数中参数和实参的工作方式。位置字段直接放在圆括号内：

// 变量声明中的记录类型注解：
(String, int) record;

// 使用记录表达式初始化它：
record = ('A string', 123);

在记录类型注解中，命名字段位于所有位置字段之后，放在一个由花括号分隔的类型和名称对的区域内。在记录表达式中，名称位于每个字段值之前，并后跟一个冒号：

// 变量声明中的记录类型注解：
({int a, bool b}) record;

// 使用记录表达式初始化它：
record = (a: 123, b: true);

记录类型中命名字段的名称是记录类型定义（或其形状）的一部分。两个具有不同名称的命名字段的记录属于不同的类型：

({int a, int b}) recordAB = (a: 1, b: 2);
({int x, int y}) recordXY = (x: 3, y: 4);

// 编译错误！这些记录的类型不同。
// recordAB = recordXY;

在记录类型注解中，你也可以为位置字段命名，但这些名称纯粹用于文档说明，不影响记录的类型：

(int a, int b) recordAB = (1, 2);
(int x, int y) recordXY = (3, 4);

recordAB = recordXY; // OK.

这与函数声明或函数类型定义（typedef）中的位置参数可以有名称，但这些名称不影响函数签名（signature）的方式类似。

更多信息和示例，请查阅记录类型和记录相等性。

记录字段

记录字段可以通过内置的 getter 访问。记录是不可变的，因此字段没有 setter。

命名字段公开了同名的 getter。位置字段公开了名为 $<position> 的 getter，并跳过命名字段：

var record = ('first', a: 2, b: true, 'last');

print(record.$1); // 输出 'first'
print(record.a); // 输出 2
print(record.b); // 输出 true
print(record.$2); // 输出 'last'

要进一步简化记录字段的访问，请查看关于模式（Patterns）的页面。

记录类型

单个记录类型没有类型声明。记录是根据其字段的类型进行结构化类型定义的。一个记录的形状（其字段集合、字段的类型以及它们的名称（如果有的话））唯一地决定了记录的类型。

记录中的每个字段都有自己的类型。同一记录内的字段类型可以不同。类型系统在任何地方访问记录字段时都知道每个字段的类型：

(num, Object) pair = (42, 'a');

var first = pair.$1; // 静态类型是 `num`，运行时类型是 `int`。
var second = pair.$2; // 静态类型是 `Object`，运行时类型是 `String`。

假设两个不相关的库创建了具有相同字段集的记录。类型系统会认为这些记录是相同的类型，即使这两个库彼此之间没有耦合。

提示
虽然你不能为记录的形状声明一个唯一的类型，但你可以创建类型别名以提高可读性和复用性。要了解如何以及何时这样做，请查阅记录与类型定义（typedef）。

记录相等性

如果两个记录具有相同的形状（字段集），并且它们对应的字段具有相同的值，那么这两个记录就是相等的。由于命名字段的顺序不属于记录形状的一部分，因此命名字段的顺序不影响相等性。

例如：

(int x, int y, int z) point = (1, 2, 3);
(int r, int g, int b) color = (1, 2, 3);

print(point == color); // 输出 'true'。

({int x, int y, int z}) point = (x: 1, y: 2, z: 3);
({int r, int g, int b}) color = (r: 1, g: 2, b: 3);

print(point == color); // 输出 'false'。Linter 提示：对不相关的类型进行相等比较。

记录会根据其字段的结构自动定义 hashCode 和 == 方法。

多返回值

记录允许函数返回捆绑在一起的多个值。要从返回值中检索记录值，可以使用模式匹配将这些值解构到局部变量中。

// 在记录中返回多个值：
(String name, int age) userInfo(Map<String, dynamic> json) {
  return (json['name'] as String, json['age'] as int);
}

final json = <String, dynamic>{'name': 'Dash', 'age': 10, 'color': 'blue'};

// 使用带有位置字段的记录模式进行解构：
var (name, age) = userInfo(json);

/* 等价于：
  var info = userInfo(json);
  var name = info.$1;
  var age  = info.$2;
*/

你也可以使用命名字段来解构一个记录，这需要使用冒号 : 语法，你可以在模式类型页面上阅读更多相关内容：

({String name, int age}) userInfo(Map<String, dynamic> json)
// ···
// 使用带有命名字段的记录模式进行解构：
final (:name, :age) = userInfo(json);

你也可以在不使用记录的情况下从函数返回多个值，但其他方法有其缺点。例如，创建一个类会更冗长，而使用像 List 或 Map 这样的其他集合类型会失去类型安全。

注意
记录的多返回值和异构类型特性使得不同类型的 future 可以并行化，你可以在 dart:async 文档中阅读相关内容。

记录作为简单数据结构

记录只持有数据。当这就是你所需要的全部功能时，它们立即可用且易于使用，无需声明任何新类。对于一个所有元素都具有相同形状的简单数据元组列表，使用记录列表是最直接的表示方法。

以这个“按钮定义”列表为例：

final buttons = [
  (
    label: "Button I",
    icon: const Icon(Icons.upload_file),
    onPressed: () => print("Action -> Button I"),
  ),
  (
    label: "Button II",
    icon: const Icon(Icons.info),
    onPressed: () => print("Action -> Button II"),
  )
];

这段代码可以直接编写，无需任何额外的声明。

记录与类型定义（typedef）

你可以选择使用类型定义（typedef）为记录类型本身命名，然后使用该名称而不是写出完整的记录类型。这种方法允许你声明某些字段可以为 null (?)，即使列表中当前没有任何条目具有 null 值。

typedef ButtonItem = ({String label, Icon icon, void Function()? onPressed});
final List<ButtonItem> buttons = [
  // ...
];

因为记录类型是结构化类型，所以像 ButtonItem 这样的命名只是引入了一个别名，使其更容易引用结构化类型 ({String label, Icon icon, void Function()? onPressed})。

让所有代码都通过别名引用记录类型，可以让你在以后更容易地更改记录的实现，而无需更新每个引用。

代码可以像处理简单的类实例一样处理给定的按钮定义：

List<Container> widget = [
  for (var button in buttons)
    Container(
      margin: const EdgeInsets.all(4.0),
      child: OutlinedButton.icon(
        onPressed: button.onPressed,
        icon: button.icon,
        label: Text(button.label),
      ),
    ),
];

你甚至可以决定稍后将记录类型更改为类类型以添加方法：

class ButtonItem {
  final String label;
  final Icon icon;
  final void Function()? onPressed;
  ButtonItem({required this.label, required this.icon, this.onPressed});
  bool get hasOnpressed => onPressed != null;
}

或者更改为扩展类型：

extension type ButtonItem._(({String label, Icon icon, void Function()? onPressed}) _) {
  String get label => _.label;
  Icon get icon => _.icon;
  void Function()? get onPressed => _.onPressed;
  ButtonItem({required String label, required Icon icon, void Function()? onPressed})
      : this._((label: label, icon: icon, onPressed: onPressed));
  bool get hasOnpressed => _.onPressed != null;
}

然后使用该类型的构造函数创建按钮定义列表：

final List<ButtonItem> buttons =  [
  ButtonItem(
    label: "Button I",
    icon: const Icon(Icons.upload_file),
    onPressed: () => print("Action -> Button I"),
  ),
  ButtonItem(
    label: "Button II",
    icon: const Icon(Icons.info),
    onPressed: () => print("Action -> Button II"),
  )
];