Textlint 迁移指南：从 TextLintEngine 到 linter.lintText 的正确使用方式

在将项目从 textlint v13 升级到 v14 版本时，许多开发者会遇到如何正确使用新 API 的问题。本文将以技术专家的视角，详细解析如何正确使用 linter.lintText 方法替代旧版的 TextLintEngine。

新旧 API 对比

在 textlint v13 中，开发者通常使用 TextLintEngine 的 executeOnText 方法来检查文本内容。而在 v14 版本中，这个 API 已被弃用，取而代之的是 linter.lintText 方法。

旧版代码示例：

engine.executeOnText(ruleText).then(function(results) {
  // 处理结果
});

新版 API 的正确使用方式

linter.lintText 方法需要两个参数：

1. 要检查的文本内容
2. 文件路径（用于确定文件类型）

正确的新版代码示例：

// 检查 Markdown 格式文本
await linter.lintText(ruleText, "dummy.md").then(function(results) {
  // 处理结果
});

// 检查纯文本
await linter.lintText(ruleText, "dummy.txt").then(function(results) {
  // 处理结果
});

关键点解析

1. 文件路径参数的重要性：

   • 文件路径不仅用于日志输出，更重要的是用于 textlint 确定文件类型
   • 即使文本内容不来自实际文件，也需要提供虚拟路径
   • 文件扩展名（如 .md 或 .txt）决定了 textlint 如何处理内容

2. 常见文件类型处理：

   • Markdown 文件：使用 .md 扩展名
   • 纯文本文件：使用 .txt 扩展名
   • 技术文档：根据实际格式选择 .rst、.adoc 等

3. 异步处理：

   • lintText 返回一个 Promise，可以使用 then 或 await 处理结果
   • 建议在异步函数中使用 await 语法以获得更清晰的代码结构

迁移建议

1. 逐步替换：

   • 先在测试环境中验证新 API 的行为
   • 确保所有文件类型都被正确处理

2. 错误处理：

   • 添加适当的错误捕获逻辑
   • 处理不同文件类型可能产生的不同错误

3. 性能考虑：

   • 新版 API 在性能上有所优化
   • 对于大量文件处理，可以考虑批量处理

总结

textlint v14 的 linter.lintText API 提供了更清晰、更强大的文本检查能力。通过正确使用文件路径参数，开发者可以确保文本内容被按照预期的格式处理。在迁移过程中，重点关注文件类型的正确指定和异步处理逻辑的调整，可以顺利完成从旧版 API 的过渡。

对于更复杂的用例，建议查阅 textlint 的官方文档或参与社区讨论，以获取更多高级用法和最佳实践。