Textlint模块化使用指南：从基础到高级API详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00751/article/details/148756343

Textlint模块化使用指南：从基础到高级API详解

textlint The pluggable natural language linter for text and markdown. 项目地址: https://gitcode.com/gh_mirrors/te/textlint

前言

Textlint作为一款强大的文本校验工具，除了提供命令行接口外，还提供了丰富的模块化API，允许开发者将其集成到各种JavaScript项目中。本文将全面介绍Textlint的模块化使用方法，帮助开发者更好地理解和使用这套工具。

核心概念

Textlint提供了两种主要的使用方式：

高级API：通过.textlintrc配置文件加载规则和插件
内核API：直接使用@textlint/kernel进行更底层的控制

对于大多数用户来说，使用高级API是更便捷的选择，因为它可以自动处理配置文件的加载和解析。

现代API详解

Textlint在v12.3.0版本中引入了全新的API设计，这些API更好地支持了现代JavaScript模块系统。

核心方法

`createLinter`

创建lint实例的主要方法，接收一个配置描述符对象，返回具有多种方法的linter实例。

import { createLinter, loadTextlintrc } from "textlint";

const descriptor = await loadTextlintrc();
const linter = createLinter({ descriptor });

linter实例方法

lintFiles(files)：校验多个文件
lintText(text, filePath)：校验文本内容（需提供虚拟文件路径）
fixFiles(files)：自动修复多个文件
fixText(text, filePath)：自动修复文本内容
scanFilePath(filePath)：检查文件路径是否可被校验

配置加载

loadTextlintrc方法用于加载配置文件：

const descriptor = await loadTextlintrc({
  configFilePath: "/path/to/.textlintrc"
});

实际应用示例

基础文件校验

import { createLinter, loadTextlintrc, loadLinterFormatter } from "textlint";

async function runLint() {
  const descriptor = await loadTextlintrc();
  const linter = createLinter({ descriptor });
  const results = await linter.lintFiles(["*.md"]);
  
  const formatter = await loadLinterFormatter({ formatterName: "stylish" });
  console.log(formatter.format(results));
}

runLint();

文本自动修复

import { createLinter, loadTextlintrc } from "textlint";

async function fixText() {
  const descriptor = await loadTextlintrc();
  const linter = createLinter({ descriptor });
  
  const result = await linter.fixText("TODO: fix me", "DUMMY.md");
  console.log(result.output); // 输出修复后的文本
}

fixText();

高级用法

自定义规则和插件

import { createLinter, loadTextlintrc } from "textlint";
import { TextlintKernelDescriptor } from "@textlint/kernel";
import { moduleInterop } from "@textlint/module-interop";

async function useCustomRules() {
  const customDescriptor = new TextlintKernelDescriptor({
    rules: [{
      ruleId: "my-rule",
      rule: moduleInterop((await import("./my-rule")).default)
    }]
  });

  const rcDescriptor = await loadTextlintrc();
  const linter = createLinter({
    descriptor: customDescriptor.concat(rcDescriptor)
  });

  const result = await linter.lintText("Some text", "README.md");
  console.log(result);
}

文件扩展名检测

const descriptor = await loadTextlintrc();
console.log(descriptor.availableExtensions); // [".md", ".txt"]

迁移指南

从旧版API迁移到新版API需要注意以下几点：

配置加载方式变化：
- 旧版：自动查找配置文件
- 新版：需要显式调用loadTextlintrc

文本校验方法变化：

// 旧版
engine.executeOnText("text");

// 新版
linter.lintText("text", "dummy.md");

结果处理方式变化：
- 新版API返回的结果结构更加清晰
- 格式化输出需要单独调用formatter

测试自定义规则

开发自定义规则时，可以使用textlint-tester工具进行测试：

import { TextlintTester } from "textlint-tester";

const tester = new TextlintTester();
tester.run("my-rule", rule, {
  valid: ["valid text"],
  invalid: [{
    text: "invalid text",
    errors: [{ message: "Expected error" }]
  }]
});