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 documentation 阅读更多内容。