用途:在 Dart 文档注释中引用多行代码示例时,官方建议把示例抽成独立的 .dart 文件,再用 {@example} 指令注入,而不是直接写在 /// 注释里,这样示例可被分析、lint 和执行。
主要能力:{@example} 会解析外部文件并生成带围栏的 Markdown 代码块。语法为 {@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}。path 以 / 开头时从包根目录解析,否则相对当前文件;lang 默认按扩展名自动识别,也可显式指定;indent 默认 strip,会去掉公共前导缩进。
区域与隐藏:在目标文件中用 // #region 名称 与 // #endregion 名称 包裹片段,指令路径后加 #region 名称 即可只注入该块。某行若仅供编译通过但不想展示,可在行尾加 #hide,该行会被完全丢弃。
标记规则:只有指定了 region 后缀时,标记才会被处理并剥离;若注入整个文件,文件会原样嵌入,包括 // #hide 等标记文本。标记系统与格式无关,dartdoc 用正则剥离含标记的行,因此在 YAML 的 # #region 或 HTML 的 <!-- #region --> 中同样有效。
放置与路径:该指令是块级指令,必须独占一行并以 /// 开头。路径遵循 URI 引用规则:以 / 开头映射到包根;相对路径基于当前文件所在目录;允许用 .. 向上遍历,但不会越过包根;不支持 https:// 等网络 URL,示例文件必须在本地文件系统中;分隔符必须用正斜杠 /,即使在 Windows 上也是如此,也支持 URI 编码字符如 %20。
验证:注入后对示例文件运行 dart analyze 确认隐藏的 setup 代码可编译;可选运行 dart doc,检查 dartdoc 是否成功解析指令、未出现读取文件失败或缺少 region 的警告。
限制:不支持网络 URL;未指定 region 时标记不会被剥离;路径解析受包根边界约束。