Dart 注释

Dart 支持单行注释、多行注释和文档注释。

单行注释

单行注释以 // 开头。 // 和行尾之间的所有内容都被 Dart 编译器忽略。

void main() {
   
  // TODO: 重构为 AbstractLlamaGreetingFactory？
  print('欢迎来到我的羊驼农场！');
}

多行注释

多行注释以 /* 开头，以 */ 结尾。 /* 和 */ 之间的所有内容都被 Dart 编译器忽略（除非注释是文档注释；请参见下一节）。多行注释可以嵌套。

void main() {
   
  /*
   * 这是很多工作。考虑养鸡。

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}

文档注释

文档注释是开头为 /// 或 /** 的多行或单行注释。在连续行上使用 /// 与多行文档注释的效果相同。

在文档注释中，分析器会忽略所有文本，除非它包含在方括号中。使用方括号，您可以引用类、方法、字段、顶级变量、函数和参数。方括号中的名称在已记录程序元素的词法作用域中解析。

这是一个带有对其他类和参数引用的文档注释示例：

/// 一种驯养的南美骆驼科动物（羊驼）。
///
/// 安第斯文化自前西班牙时代以来就一直将羊驼用作肉类和驮畜。
///
/// 与任何其他动物一样，羊驼也需要吃东西，
/// 所以不要忘记用一些 [Food] [feed] 它们。
class Llama {
   
  String? name;

  /// 用 [food] 喂你的羊驼。
  ///
  /// 一只典型的羊驼每周吃一捆干草。
  void feed(Food food) {
   
    // ...
  }

  /// 用 [activity] 活动让你的羊驼锻炼 [timeLimit] 分钟。
  void exercise(Activity activity, int timeLimit) {
   
    // ...
  }
}

在类的生成的文档中， [feed] 成为指向 feed 方法文档的链接，

而 [Food] 成为指向 Food 类文档的链接。

要解析 Dart 代码并生成 HTML 文档，您可以使用 Dart 的文档生成工具， dart doc 。

有关生成的文档示例，请参见

Dart API 文档。

有关如何组织注释的建议，请参见

Effective Dart：文档。

Dart 元数据

使用元数据为代码提供附加信息。元数据注释以字符 @ 开头，后跟编译时常量的引用（例如 deprecated ）或对常量构造函数的调用。

所有 Dart 代码都可以使用四种注释： @Deprecated 、 @deprecated 、 @override 和 @pragma 。有关使用 @override 的示例，请参阅 扩展类 。以下是如何使用 @Deprecated 注释的示例：

class Television {
   
  /// 使用 [turnOn] 代替打开电源。
  [!@Deprecated('Use turnOn instead')!]
  void activate() {
   
    turnOn();
  }

  /// 打开电视电源。
  void turnOn() {
   ...}
  // ···
}

如果您不想指定消息，可以使用 @deprecated 。但是，我们 建议 始终使用 @Deprecated 指定消息。

您可以定义自己的元数据注释。以下是如何定义一个带有两个参数的 @Todo 注释的示例：

class Todo {
   
  final String who;
  final String what;

  const Todo(this.who, this.what);
}

以下是如何使用该 @Todo 注释的示例：

@Todo('Dash', 'Implement this function')
void doSomething() {
   
  print('Do something');
}

元数据可以出现在库、类、typedef、类型参数、构造函数、工厂、函数、字段、参数或变量声明之前，以及 import 或 export 指令之前。

Dart 库与导入

import 和 library 指令可以帮助您创建模块化且可共享的代码库。库不仅提供 API，而且还是隐私单元：以下划线 (_) 开头的标识符仅在库内可见。每个 Dart 文件（及其部分）都是一个 库，即使它不使用 library 指令。

库可以使用 包 进行分发。

注意
要了解为什么 Dart 使用下划线而不是 public 或 private 等访问修饰符关键字，请参阅
SDK issue 33383 。

使用库

使用 import 指定一个库的命名空间如何在另一个库的范围内使用。

例如，Dart Web 应用通常使用 dart:html 库，它们可以这样导入：

import 'dart:html';

import 唯一必需的参数是指定库的 URI。

对于内置库，URI 具有特殊的 dart: 模式。

对于其他库，您可以使用文件系统路径或 package: 模式。 package: 模式指定由包管理器（例如 pub 工具）提供的库。例如：

import 'package:test/test.dart';

注意
URI 代表统一资源标识符。
URL（统一资源定位符）是一种常见的 URI。

指定库前缀

如果您导入了两个具有冲突标识符的库，则可以为一个或两个库指定前缀。例如，如果库1和库2都具有 Element 类，则您的代码可能如下所示：

import 'package:lib1/lib1.dart';
import 'package:lib2/lib2.dart' as lib2;

// 使用 lib1 中的 Element。
Element element1 = Element();

// 使用 lib2 中的 Element。
lib2.Element element2 = lib2.Element();

只导入库的一部分

如果您只想使用库的一部分，可以选择性地导入库。例如：

// 只导入 foo。
import 'package:lib1/lib1.dart' show foo;

// 导入除 foo 之外的所有名称。
import 'package:lib2/lib2.dart' hide foo;

延迟加载库

延迟加载 （也称为 懒加载 ）

允许 Web 应用根据需要按需加载库。

当您需要满足以下一项或多项需求时，请使用延迟加载。

• 减少 Web 应用的初始启动时间。
• 执行 A/B 测试——例如，尝试算法的替代实现。
• 加载很少使用的功能，例如可选屏幕和对话框。

这并不意味着 Dart 会在启动时加载所有延迟组件。

Web 应用可以在需要时通过 Web 下载延迟组件。

dart 工具不支持针对 Web 以外的目标的延迟加载。

如果您正在构建 Flutter 应用，

请参阅 Flutter 指南中关于

延迟组件 的延迟加载实现。

undefined

要延迟加载库，首先使用 deferred as 导入它。

import 'package:greetings/hello.dart' deferred as hello;

当您需要该库时，使用库的标识符调用 loadLibrary() 。

Future<void> greet() async {
   
  await hello.loadLibrary();
  hello.printGreeting();
}

在前面的代码中，

await 关键字会暂停执行，直到库加载完毕。

有关 async 和 await 的更多信息，

请参见 异步支持 。

您可以多次在库上调用 loadLibrary() 而不出现问题。

库只加载一次。

使用延迟加载时，请记住以下几点：

• 延迟库的常量在导入文件中不是常量。
  请记住，这些常量在延迟库加载之前不存在。
• 您不能在导入文件中使用延迟库中的类型。
  相反，请考虑将接口类型移动到由延迟库和导入文件同时导入的库。
• Dart 会隐式地将 loadLibrary() 插入到您使用 deferred as 命名空间 定义的命名空间中。
  loadLibrary() 函数返回一个 Future 。

library 指令 {:#library-directive}

要指定库级 文档注释 或 元数据注释 ，

请将它们附加到文件开头的 library 声明。

/// 一个非常棒的测试库。
@TestOn('browser')
library;

实现库

有关如何实现包的建议，请参阅

创建包 ，其中包括：

• 如何组织库源代码。
• 如何使用 export 指令。
• 何时使用 part 指令。
• 如何使用条件导入和导出来实现支持多个平台的库。

来源：Dart 中文开发文档