跳到主要內容
目錄

記錄

目錄

記錄是一種匿名、不可變、聚合類型。如同其他集合類型，它們可讓您將多個物件捆綁到單一物件中。與其他集合類型不同，記錄是固定大小、異質且具類型的。

記錄是真實的值；您可以將它們儲存在變數中、巢狀化它們、將它們傳遞給函式和從函式傳遞，並將它們儲存在資料結構中，例如清單、Map 和 Set。

記錄語法

#

記錄表達式是以逗號分隔的具名或位置欄位清單，並以括號括起來

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

記錄類型註解是以逗號分隔的類型清單，並以括號括起來。您可以使用記錄類型註解來定義回傳類型和參數類型。例如，以下 (int, int) 陳述式是記錄類型註解

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

記錄表達式和類型註解中的欄位會鏡射參數和引數在函式中的運作方式。位置欄位直接放在括號內

dart
// Record type annotation in a variable declaration:
(String, int) record;

// Initialize it with a record expression:
record = ('A string', 123);

在記錄類型註解中，具名欄位放在類型和名稱配對的花括號分隔區段中，在所有位置欄位之後。在記錄表達式中，名稱放在每個欄位值之前，並在後面加上冒號

dart
// Record type annotation in a variable declaration:
({int a, bool b}) record;

// Initialize it with a record expression:
record = (a: 123, b: true);

記錄類型中具名欄位的名稱是記錄類型定義或其形狀的一部分。具名欄位名稱不同的兩個記錄具有不同的類型

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

// Compile error! These records don't have the same type.
// recordAB = recordXY;

在記錄類型註解中，您也可以命名位置欄位，但這些名稱僅用於文件目的，不會影響記錄的類型

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

recordAB = recordXY; // OK.

這類似於函式宣告或函式類型定義中的位置參數可以有名稱，但這些名稱不會影響函式的簽章。

如需更多資訊和範例，請查看記錄類型和記錄相等性。

記錄欄位

#

記錄欄位可透過內建的 getter 存取。記錄是不可變的，因此欄位沒有 setter。

具名欄位會公開相同名稱的 getter。位置欄位會公開名稱為 $<位置> 的 getter，並跳過具名欄位

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

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

為了更簡化記錄欄位存取，請查看關於模式的頁面。

記錄類型

#

沒有個別記錄類型的類型宣告。記錄是根據其欄位類型進行結構類型化的。記錄的形狀 (其欄位集合、欄位類型及其名稱，如果有的話) 唯一決定了記錄的類型。

記錄中的每個欄位都有自己的類型。欄位類型在同一記錄中可以不同。類型系統知道從記錄存取每個欄位的類型

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

var first = pair.$1; // Static type `num`, runtime type `int`.
var second = pair.$2; // Static type `Object`, runtime type `String`.

考慮兩個不相關的函式庫，它們建立具有相同欄位集合的記錄。類型系統了解這些記錄是相同的類型，即使這些函式庫彼此沒有耦合。

記錄相等性

#

如果兩個記錄具有相同的形狀 (欄位集合)，且其對應欄位具有相同的值，則這兩個記錄相等。由於具名欄位順序不是記錄形狀的一部分，因此具名欄位的順序不會影響相等性。

例如

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

print(point == color); // Prints 'true'.
dart
({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); // Prints 'false'. Lint: Equals on unrelated types.

記錄會根據其欄位的結構自動定義 hashCode 和 == 方法。

多重回傳

#

記錄允許函式傳回捆綁在一起的多個值。若要從回傳中擷取記錄值，請使用模式比對將值解構為區域變數。

dart
// Returns multiple values in a record:
(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'};

// Destructures using a record pattern with positional fields:
var (name, age) = userInfo(json);

/* Equivalent to:
  var info = userInfo(json);
  var name = info.$1;
  var age  = info.$2;
*/

您也可以使用記錄的具名欄位，使用冒號 : 語法來解構記錄，您可以在模式類型頁面上閱讀更多相關資訊

dart
({String name, int age}) userInfo(Map<String, dynamic> json)
// ···
// Destructures using a record pattern with named fields:
final (:name, :age) = userInfo(json);

您可以從函式傳回多個值而無需記錄，但其他方法會帶來缺點。例如，建立類別會更冗長，而使用其他集合類型 (如 List 或 Map) 會失去類型安全。

記錄作為簡單資料結構

#

記錄僅保存資料。當這就是您所需要的全部時，它們可以立即使用且易於使用，而無需宣告任何新類別。對於形狀都相同的簡單資料元組清單，記錄清單是最直接的表示法。

以這個「按鈕定義」清單為例

dart
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"),
  )
];

此程式碼可以直接撰寫，而無需任何額外的宣告。

記錄與類型定義

#

您可以選擇使用類型定義為記錄類型本身命名，並使用該名稱而不是寫出完整的記錄類型。此方法可讓您聲明某些欄位可以為空值 (?)，即使清單中目前的項目都沒有空值。

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

由於記錄類型是結構類型，因此給定像 ButtonItem 這樣的名稱只會引入一個別名，使其更容易參考結構類型：({String label, Icon icon, void Function()? onPressed})。

讓您的所有程式碼都透過其別名參考記錄類型，可以更輕鬆地在以後變更記錄的實作，而無需更新每個參考。

程式碼可以使用給定的按鈕定義，就像使用簡單的類別實例一樣

dart
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),
      ),
    ),
];

您甚至可以決定稍後將記錄類型變更為類別類型以新增方法

dart
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;
}

或變更為擴充類型

dart
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;
}

然後使用該類型的建構子建立按鈕定義清單

dart
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"),
  )
];

同樣地，所有這些都不需要變更使用該清單的程式碼。

變更任何類型確實需要使用它的程式碼非常小心，不要做出假設。對於使用類型別名作為參考的程式碼，類型別名不提供任何保護或保證，保證被別名的值是記錄。擴充類型也幾乎沒有提供保護。只有類別才能提供完整的抽象化和封裝。

除非另有說明，否則本網站上的文件反映 Dart 3.7.1。頁面最後更新於 2025-03-10。 檢視原始碼 或回報問題。