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

Question

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

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

这是什么@macro意思？

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

Answer 1

A@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 文档中阅读更多内容。