dart-long-lines

Dart 长行

1. 何时使用此技能

在以下情况下使用此技能：

• 编写可能超过 80 列限制的 Dart 代码。
• 重构代码，使其符合 lines_longer_than_80_chars lint 规则。 参考：https://dart.dev/tools/linter-rules/lines_longer_than_80_chars

何时不使用（规避护栏）

在以下情况下，请勿换行或修改代码：

• 无法拆分的 URL 和 URI：行中包含较长的 HTTP/HTTPS URL、导入 URI 或文件路径，拆分后会导致链接失效。
• 复杂的正则表达式字面量：较长的 RegExp 模式 （RegExp(r'...')），插入空格或换行会改变匹配语义。
• ASCII 艺术字、表格或预格式化图表：注释或字符串中的预格式化文本块、 表格行或 ASCII 图表，换行会破坏视觉对齐。
• 自动格式化之前：运行 dart format 之前，请勿手动拆分代码行。让 dart format 自动处理代码换行；仅手动换行格式化工具不会重新换行的注释、 文档和多行字符串。

查找

查找超出限制的行：

自动分析

查找长行最可靠的方法是使用 Dart 分析器：

• 命令：dart analyze
• Lint：lines_longer_than_80_chars

手动搜索

使用正则表达式搜索长行：

• 正则表达式：^.{81,}$（匹配包含 81 个或更多字符的任意行）。

2. 指南

先格式化

手动拆分长行之前，始终先运行 dart format。格式化工具通常会自动修复长行， 尤其是在生成的代码中，并应用标准 Dart 样式规则。

代码注释

在词语边界处合理拆分较长的代码注释（//），确保行长不超过 80 个字符。 保持紧凑的格式，避免不必要的垂直空白。

文档注释（///）

• 采用与代码注释相同的换行规则。
• 避免将 Markdown 链接块（如 [name] 或 [text](http://example.com)）拆分到多行。如果超出限制，请将其单独放在一行。
• 文档注释以一句简短的摘要句开头，其后空一行，再写注释的其余部分。可以将 这句开头的摘要拆分为多行，以满足 80 列限制。
• 避免未解析的引用或悬空句子。

长字符串

• 使用相邻的字符串字面量（例如，'part 1 ' 'part 2'）拆分长字符串。在词语 边界处拆分。
• 如果单行字符串包含换行符（\n），或者存在连续的 print 语句，可以考虑迁移为 多行字符串字面量（'''）。

修改后进行格式化和分析

• 修改后运行 dart format 和 dart analyze。
• 注意，拆分字符串可能会触发新的 lint（例如，如果拆分后的双引号字符串不再包含 单引号，则可能触发 prefer_single_quotes）。

3. 示例

文档注释链接

避免：

/// This is a long doc comment that contains a link to [a very long
/// URL](http://example.com/very/long/url/that/exceeds/eighty/chars).

推荐：

/// This is a long doc comment that contains a link to [a very long URL][ref].
///
/// [ref]: http://example.com/very/long/url/that/exceeds/eighty/chars

相邻字符串字面量

推荐：

final longString = 'This is a very long string that needs to be broken '
    'across multiple lines to stay under the limit.';

迁移为多行字符串

避免：

print('This is line 1\nThis is line 2 that is also quite long\nThis is line 3 which makes the whole thing exceed eighty characters');

推荐：

print('''This is line 1
This is line 2 that is also quite long
This is line 3 which makes the whole thing exceed eighty characters''');