Flutter 和 Dart 文档中的@macro 注释是什么

Question

当我阅读源代码时，我经常看到这样的东西（来自TextField ）：

/// {@macro flutter.widgets.editableText.keyboardType}
final TextInputType keyboardType;

@macro是什么意思？

我找到了答案，所以我将其作为自我回答问答发布在下面。

Answer 1

@macro是一种插入一些在其他地方编写的dartdoc文档的方法。 这样您就没有必须维护的重复文档。

@macro的字符串是模板的名称，其中包括您将插入的文档。 所以在TextField示例中：

/// {@macro flutter.widgets.editableText.keyboardType}
final TextInputType keyboardType;

模板名称是flutter.widgets.editableText.keyboardType 。 如果您转到EditableText的源代码，您将找到带有文档文本的模板：

/// {@template flutter.widgets.editableText.keyboardType}
/// The type of keyboard to use for editing the text.
///
/// Defaults to [TextInputType.text] if [maxLines] is one and
/// [TextInputType.multiline] otherwise.
/// {@endtemplate}
final TextInputType keyboardType;

注释@template启动模板，后跟其名称。 @endtemplate完成它。

当您查看EditableText.keyboardType和TextField.keyboardType的文档时，您会发现它们完全相同：

• https://api.flutter.dev/flutter/widgets/EditableText/keyboardType.html
• https://api.flutter.dev/flutter/material/TextField/keyboardType.html

在dartdoc 文档中阅读更多内容。