当前位置：首页 > news >正文

nuxt常用组件库html-validator应用解析

news 来源：原创 2025/9/12 21:45:45

html-validator

主要用于自动验证nuxt服务器呈现的HTML(SSR和SSG)，以检测可能导致水合错误的HTML常见问题，有助于减少水合错误，检测常见的可访问性错误。

安装

npx nuxi@latest module add html-validator

配置

若自动更新nuxt.config.ts配置文件失败，可手动添加下面代码:

nuxt3

defineNuxtConfig({modules: ['@nuxtjs/html-validator',//其他配置项]})

nuxt2.9+

 export default {buildModules: ['@nuxtjs/html-validator']}

nuxt2

 export default {// Install @nuxtjs/html-validator as dependency instead of devDependencymodules: ['@nuxtjs/html-validator']}

使用

html-validator有四个选项

1.usePrettier允许更美观地打印源代码，以便在上下文中显示错误。

如果使用的是TailwindCSS，请考虑不要启用此功能，因为在开发模式下，prettier将难以处理解析HTML的大小。

2.logLevel设置详细信息为verbose、warning或error。在dev中默认为verbose，在生成时为warning。

您可以使用此配置选项来关闭控制台日志记录的No HTML validation errors found for…消息。

3.如果生成的页面有任何验证错误，failOnError将在运行nuxt generate后抛出一个错误。

在持续集成中很有用。

4.Options允许您传入html-validate选项，这些选项将与默认配置合并

更多关于配置 html- validate 的信息，可以参考官方文档。

默认配置

{htmlValidator: {usePrettier: false,logLevel: 'verbose',failOnError: false,/** A list of routes to ignore (that is, not check validity for). */ignore: [/\.(xml|rss|json)$/],options: {extends: ['html-validate:document','html-validate:recommended','html-validate:standard'],rules: {'svg-focusable': 'off','no-unknown-elements': 'error',// Conflicts or not needed as we use prettier formatting'void-style': 'off','no-trailing-whitespace': 'off',// Conflict with Nuxt defaults'require-sri': 'off','attribute-boolean-style': 'off','doctype-style': 'off',// Unreasonable rule'no-inline-style': 'off'}}}
}

规则参考

html语法和概念

与HTML语法和概念相关的规则。

	attr-delimiter	禁止属性键和值之间有空格
	attr-spacing	要求属性之间用空格分隔
	close-attr	禁止结束标记具有属性
	close-order	要求元素按正确顺序关闭
	element-name	禁止使用无效的元素名称
	form-dup-name	要求表单控件具有唯一的名称
	map-dup-name	要求‘ <map name> ’是唯一的
	map-id-name	要求name和id在<map>元素上匹配
	no-dup-attr	禁止重复属性
	no-dup-class	禁止重复的类
	no-raw-characters	禁止使用未转义的特殊字符
	no-redundant-for	禁止对属性使用冗余标签
	script-type	要求‘ <script> ’元素的有效类型
	unrecognized-char-ref	禁止无法识别的字符引用
	valid-autocomplete	要求自动完成属性有效
	valid-id	要求‘ id ’是一个有效的标识符

内容模型

	attribute-allowed-values	验证允许的属性值
	attribute-misuse	要求属性在正确的上下文中使用
	element-permitted-content	验证允许的内容
	element-permitted-occurrences	验证允许的元素出现次数
	element-permitted-order	验证所需的元素顺序
	element-permitted-parent	验证允许的元素父元素
	element-required-ancestor	验证所需的元素祖级
	element-required-attributes	确保设置了所需的属性
	element-required-content	确保必需的元素存在
	input-attributes	验证输入属性的使用
	no-multiple-main	禁用多个“<main>”
	script-element	为‘ <script> ’要求结束标签
	void-content	禁止包含内容的void元素

弃用规则

与已弃用或过时功能的使用相关的规则。

	deprecated	禁止使用废弃的元素
	deprecated-rule	禁止使用不推荐的规则
	no-conditional-comment	禁止使用条件注释
	no-deprecated-attr	禁止使用弃用的属性

可行性

	area-alt	要求‘ <area> ’元素上的替代文本
	aria-hidden-body	禁止在“<body>”上设置“aria-hidden”
	aria-label-misuse	禁止误用“aria-label”
	empty-heading	要求标题头有文字内容
	empty-title	要求标题有文字内容
	hidden-focusable	在可聚焦的元素上禁用“aria-hidden”
	input-missing-label	要求输入有标签
	meta-refresh	要求元刷新具有0秒延迟
	multiple-labeled-controls	禁止与多个控件关联的标签
	no-abstract-role	禁止使用抽象的WAI-ARIA角色
	no-autoplay	禁止自动播放媒体元素
	no-implicit-button-type	禁止隐式按钮类型
	no-redundant-aria-label	禁止arial -label和label具有相同的文本内容
	no-redundant-role	禁止使用冗余角色
	prefer-native-element	更倾向使用原生HTML元素而不是角色
	svg-focusable	要求<svg>具有可聚焦属性
	tel-non-breaking	要求在电话号码中使用不间断字符
	text-content	要求元素具有有效的文本内容
	unique-landmark	要求地标有唯一的名称
	wcag/h30	WCAG H30：提供链接文本
	wcag/h32	WCAG H32：提供提交按钮
	wcag/h36	WCAG H36：要求在图片上使用所有文本作为提交按钮
	wcag/h37	WCAG H37：在img元素上使用alt属性
	wcag/h63	WCAG H63：使用scope属性来关联标题单元格和数据单元格
	wcag/h67	WCAG H67：在img元素上使用空alt文本和没有标题属性
	wcag/h71	WCAG H71：为表单控件组提供描述

验证

	require-csp-nonce	需要CSP的资源
	require-sri	要求资源的SRI

SEO

long-title

要求标题不要有太长的文字

模式

	attr-case	要求属性名使用特定的大小写
	attr-pattern	要求属性匹配已配置的模式
	attr-quotes	Require attribute quoting
	attribute-boolean-style	要求属性引用
	attribute-empty-style	为空属性要求特定的样式
	class-pattern	要求类匹配特定的模式
	doctype-style	需要DOCTYPE的特定案例
	element-case	要求元素名称使用特定的大小写
	id-pattern	要求id匹配特定的模式
	name-pattern	要求表单控件名称匹配特定的模式
	no-implicit-close	要求带有可选结束标签的元素显式关闭
	no-implicit-input-type	禁止隐式输入类型
	no-inline-style	禁止内联样式
	no-self-closing	禁止自闭元素
	no-style-tag	禁止使用<style>标记
	no-trailing-whitespace	禁止尾随空格
	prefer-button	对于按钮，更喜欢使用<button>而不是<input>
	prefer-tbody	更喜欢把<tr>包装在<tbody>里面
	void-style	需要一个特定的样式来关闭void元素

文档

这些规则适用于完整的单据。

	allowed-links	禁用链接类型
	doctype-html	要求使用“html”文档类型
	heading-level	要求标题从h1开始并递增1
	missing-doctype	要求文档具有doctype
	no-dup-id	不允许重复的id
	no-missing-references	要求所有元素引用都存在
	no-utf8-bom	禁止文档具有UTF-8 BOM

未知元素

	no-unknown-elements	禁止使用未知元素
	no-unused-disable	禁用未使用的禁用指令

预设配置

HTML-validate带有一些预定义的预设。

示例 .htmlvalidate.json

{"extends": ["html-validate:PRESET"]
}

示例 .htmlvalidate.cjs

const { defineConfig } = require("html-validate");module.exports = defineConfig({extends: ["html-validate:PRESET"],
});

示例 .htmlvalidate.mjs

import { defineConfig } from "html-validate";export default defineConfig({extends: ["html-validate:PRESET"],
});

可以设置多个预设，并将按照它们出现在“extends”中的顺序启用。

预设类型

html-validate:recommended

这是默认的预设，支持大多数规则，包括标准验证、WCAG和最佳实践。它是其他预设的超集。

html-validate:standard

启用与根据WHATWG HTML标准（生活标准）进行验证相关的规则。

如果您想要类似于Nu Html检查器和类似工具的验证，请使用此预设。

html-validate:prettier

自:v7.18.0
如果您正在使用Prettier来格式化HTML标记，则可以使用此预设来禁用诸如void-style之类的矛盾规则。

这个预设应该与另一个预设（如html-validate:）结合使用，因为它只禁用规则。

html-validate:a11y

启用与可访问性相关的规则。大多数规则（但不是所有已启用的规则）都与WCAG遵从性有关。它本身不会验证文档/模板本身是否有效，而只会在发现可访问性问题时进行验证。

这个预设应该与html-validate:standard一起使用，以确保文档结构是有效的（WCAG的要求），如果可能的话，还应该与html-validate:document（确保引用是有效的，等等）一起使用。

html-validate:browser

自:8.24.0
如果要从浏览器中获取源代码，请使用此预设来禁用受浏览器规范化影响的规则，例如属性布尔样式。这些规则大多只是表面上的。

这个预设应该与另一个预设（如html-validate:）结合使用，因为它只禁用规则。

html-validate:document

启用需要验证完整文档的规则，即不需要验证部分模板。示例包括缺少文档类型和无效引用。

将此预设与其他预设一起使用以实现全覆盖。这个预设是由cypress-html-validate和protractor-html-validate等插件启用的。