Dart 扩展方法：extension 关键字

Dart 扩展方法：extension 关键字

Dart 中的 extension 关键字允许开发者在不修改源代码的情况下，向现有的类或类型添加新功能。这种机制解决了无法直接继承或修改第三方库类型的痛点。

基础语法构建

创建扩展方法需要遵循特定的结构。基本框架包含关键字、扩展名、目标类型以及具体的成员定义。

1. 输入 extension 关键字 开始 定义。
2. 输入 扩展名称（建议使用描述性名称，如 StringExtension）。
3. 输入 on 关键字 指定 目标类型（即要扩展的类，如 String）。
4. 输入 大括号 {} 包裹 方法体。
5. 在大括号内编写 具体的方法、属性或运算符。

以下代码展示了为 String 类型添加一个判断是否为空白的属性：

extension StringExtension on String {
  // 定义一个 getter 属性，判断字符串去除空格后是否为空
  bool get isReallyEmpty {
    return this.trim().isEmpty;
  }
}

void main() {
  String text = "   ";
  // 直接调用扩展属性
  print(text.isReallyEmpty); // 输出: true
}

实战：为 String 添加验证逻辑

实际开发中，经常需要验证用户输入。通过扩展方法，可以将繁琐的验证逻辑直接附加到 String 类型上，提升代码的可读性。

1. 创建 一个名为 StringValidators 的扩展。
2. 指定 目标类型为 String。
3. 定义 一个名为 isValidEmail 的方法，返回 bool 值。
4. 使用 this 关键字 访问 字符串实例本身。
5. 在 main 函数中 调用 该方法。

extension StringValidators on String {
  bool isValidEmail() {
    // 简单的邮箱正则验证
    return this.contains('@') && this.contains('.');
  }

  // 添加一个判断是否为手机号的简单逻辑
  bool get isPhoneNumber {
    return this.length == 11 && this.startsWith('1');
  }
}

void main() {
  String email = "test@example.com";
  String phone = "13800138000";

  // 使用扩展方法
  if (email.isValidEmail()) {
    print('邮箱格式正确');
  }

  if (phone.isPhoneNumber) {
    print('手机号格式正确');
  }
}

解决命名冲突

当多个扩展库中存在同名方法，或者扩展方法与类原有的方法重名时，Dart 有一套明确的优先级规则。

1. 确认 调用优先级：类成员方法 > 扩展方法。
2. 处理 扩展之间的冲突：显式调用 指定的扩展。

如果定义了两个扩展，均包含 log() 方法，直接调用会报错。此时需要通过以下格式显式指定：

extension LogA on String {
  void log() => print('LogA: $this');
}

extension LogB on String {
  void log() => print('LogB: $this');
}

void main() {
  String s = "Hello";

  // 错误写法：s.log(); (歧义)

  // 正确写法：显式指定使用哪一个扩展
  LogA(s).log(); // 输出: LogA: Hello
  LogB(s).log(); // 输出: LogB: Hello
}

下图展示了方法调用的解析流程：

泛型扩展

扩展方法不仅限于特定类型，还可以配合泛型使用，适用于所有类型的集合或类。

1. 声明 泛型参数（如 ``） 紧随 扩展名之后。
2. 在 on 关键字后 使用 泛型类型（如 List）。
3. 在 方法体中 利用 泛型 T 进行逻辑处理。

以下示例为所有 List 添加一个安全的取值方法：

extension ListSafeGet on List {
  // 定义安全获取元素的方法，避免越界异常
  T? safeGet(int index) {
    if (index < 0 || index >= this.length) {
      return null;
    }
    return this[index];
  }
}

void main() {
  List<int> numbers = [1, 2, 3];

  // 正常获取
  print(numbers.safeGet(0)); // 输出: 1

  // 越界获取，返回 null 而非报错
  print(numbers.safeGet(5)); // 输出: null
}

限制与注意事项

虽然扩展方法功能强大，但其行为受限于静态类型解析，不具备运行时多态性。

以下是关键限制的对比说明：

理解这些限制能避免误用。例如，即使 List 的运行时对象是具体的 MyCustomList，如果扩展定义在 List 上，它也无法访问 MyCustomList 特有的私有字段。

快速上手清单

为了在项目中规范地使用扩展方法，请遵循以下步骤：

1. 创建 专门的 .dart 文件（如 extensions.dart） 集中管理 扩展代码，避免文件碎片化。
2. 使用 描述性的命名 防止 冲突，例如 DateFormatter 而非简单的 Format。
3. 优先使用 getter 属性 替代 无参数方法，以保持调用的简洁性（如 str.isEmpty 而非 str.isEmpty()）。
4. 在 使用扩展的文件顶部 导入 定义扩展的文件。
5. 利用 IDE 的代码提示功能，确认 扩展方法是否生效。