Webhint项目：如何开发自定义检查规则（Hint）

前言

Webhint是一个强大的网站检查工具，它通过一系列内置规则（称为Hint）来帮助开发者发现网站中的各种问题。本文将深入讲解如何在Webhint中开发自定义检查规则，让开发者能够根据项目需求扩展检查能力。

什么是Hint

Hint是Webhint中的核心检查单元，每个Hint负责检查特定类型的网站问题。它可以实现多种功能，包括但不限于：

• 验证所有链接是否使用HTTPS协议
• 与第三方服务集成进行深度检查
• 向页面上下文中注入JavaScript代码进行动态检测
• 检查各种Web标准和最佳实践

创建新Hint的快捷方式

Webhint提供了便捷的命令行工具来初始化新Hint：

npm init hint

执行此命令后，会进入交互式向导流程，需要回答以下问题：

1. Hint名称：为你的新Hint起一个描述性名称
2. 分类：选择Hint所属的类别，包括：
   • 无障碍访问(accessibility)
   • 开发规范(development)
   • 浏览器兼容性(compatibility)
   • 性能优化(performance)
   • 渐进式Web应用(PWA)
   • 常见陷阱(pitfalls)
   • 安全性(security)
3. 描述：简要说明Hint的功能
4. 使用场景类型：选择Hint的工作方式：
   • DOM操作：需要访问特定DOM元素
   • 资源请求分析
   • 第三方服务集成
   • JavaScript注入

回答完这些问题后，工具会自动生成Hint的模板文件，并根据选择的使用场景预先订阅相关事件。

Hint的工作原理

基本结构

一个Hint本质上是一个TypeScript类，基本模板如下：

import { Category } from '@hint/utils-types';
import { FetchEnd, IHint, HintMetadata } from 'hint/dist/src/lib/types';
import { HintContext } from 'hint/dist/src/lib/hint-context';

export default class MyNewHint implements IHint {
    public static readonly meta: HintMetadata = {}

    public constructor(context: HintContext) {
        // 初始化代码
        
        // 事件处理函数
        const validateFetchEnd = (fetchEnd: FetchEnd) => {
            // 处理fetch::end事件
        };

        const validateElement = (element: ElementFound) => {
            // 处理element::element-type事件
        };

        // 订阅事件
        context.on('element', validateElement);
        context.on('fetch::end::*', validateFetchEnd);
    }
}

事件驱动机制

Webhint采用事件驱动架构，Hint通过订阅特定事件来执行检查。常见的事件包括：

• fetch::end：资源加载完成时触发
• element::<type>：发现特定类型DOM元素时触发
• traverse::end：DOM遍历完成时触发

Hint可以订阅多个事件，但应保持最小化原则，只订阅真正需要的事件。

问题报告机制

当Hint发现问题时，需要通过context对象报告：

context.report(resource, message, { 
    element: elementToReport,
    // 其他可选参数
});

参数说明：

• resource：被分析资源的URL
• message：展示给用户的错误信息
• options：可选配置对象，可包含：
  • element：发现问题的DOM元素
  • codeSnippet：显示的问题代码片段
  • content：元素内的文本内容
  • location：问题的具体位置（行列号）
  • severity：问题严重级别（错误、警告等）

Hint元数据配置

每个Hint都需要定义meta属性，包含重要配置信息：

public static readonly meta: HintMetadata = {
    docs: {
        category: Category.performance, // 分类
        description: '检查图片是否优化'  // 描述
    },
    id: 'optimized-images',           // 唯一标识
    recommended: true,                // 是否推荐启用
    schema: [],                       // 配置项JSON Schema
    worksWithLocalFiles: true         // 是否支持本地文件
}

其中schema属性特别重要，它定义了Hint的可配置选项。当用户需要在.hintrc文件中配置该Hint时，schema将用于验证配置的有效性。Hint可以通过context.hintOptions访问这些配置。

开发建议

1. 单一职责：每个Hint应专注于检查一个特定问题
2. 明确分类：正确选择Hint的分类，方便用户理解
3. 详细文档：在meta中提供清晰的描述信息
4. 合理配置：通过schema提供灵活的配置选项
5. 精准报告：提供足够的问题上下文信息

通过遵循这些原则，你可以开发出高质量的Hint，为Webhint生态做出贡献，同时满足自己项目的特定需求。