a11y
@nuxt/a11y

开发期间在浏览器中提供实时无障碍反馈和自动化测试。
92.6K 下载量220 颗星v1.0.0-alpha.1
timdamentimdamen
danielroedanielroe

Nuxt 无障碍访问 (Accessibility)

npm versionnpm downloadsLicenseNuxt

一个 Nuxt 模块，可在开发过程中直接在浏览器中提供实时无障碍访问反馈和自动化测试。

Nuxt Accessibility 直接集成到 Nuxt DevTools 中，为您提供可操作的见解，以修复 WCAG 违规、改进无障碍合规性，并确保您的应用程序在无需离开开发环境的情况下对每个人都可用。

入门指南

要安装并添加该模块，您可以运行以下命令

npx nuxt module add a11y

该模块现已自动安装并添加到您的 nuxt.config.ts。现在您可以打开您的 Nuxt 应用，转到 DevTools，然后点击 Nuxt a11y 图标即可开始使用。

功能

  • 🔍 丰富的 DevTools UI：Nuxt DevTools 中的一个选项卡，用于可视化无障碍违规情况、检查元素并获取建议。
  • ⚡️ 由 axe-core 提供支持：行业领先的无障碍测试引擎，被 Google、Microsoft 和全球成千上万的开发者使用。
  • 🎨 元素高亮：点击任何违规项，即可在页面上用带编号的徽章标记并固定受影响的元素。
  • 🎯 基于影响力的组织：按严重程度（严重、重要、中等、轻微）对违规项进行分类，帮助您确定修复优先级。
  • 🔄 基于路由的结果：当您浏览应用程序时，会自动跟踪所有路由上的违规情况。
  • ⚙️ 自动扫描 - 持续扫描模式：每次与应用程序交互时，自动扫描无障碍问题。
  • 🎛️ 可配置选项：自动高亮所有违规项、自定义 axe-core 设置并控制控制台日志记录。

DevTools 内的视觉界面

Nuxt Accessibility 在 Nuxt DevTools 面板内提供了一个丰富且交互式的 UI。

仪表板概览

a11y devtools initial screen after scan

一个中央中心，显示：

  • 整个应用程序中的违规总数和受影响的元素
  • 按影响级别（严重、重要、中等、轻微）分组的违规项
  • 每个页面的违规快速统计
  • 用于手动扫描、自动扫描和清除结果的控制面板

违规卡片

a11y devtools violation cards with expanded affected items section

每个违规项显示：

  • 影响徽章：带有颜色编码的严重程度
  • 规则 ID 和描述：来自 WCAG/axe-core
  • 了解更多链接：指向详细文档
  • 受影响元素计数：带有可展开的详细信息
  • 交互式元素徽章：用于固定/取消固定特定元素
  • CSS 选择器：针对每个受影响的元素
  • 滚动到元素按钮：用于快速导航

高亮显示

a11y devtools running in the playground app showing issue highlights

  • 点击违规卡片：以高亮显示页面上所有受影响的元素
  • 带编号的徽章：出现在高亮元素上，便于识别
  • 点击单个元素：切换特定节点的高亮显示
  • 滚动到元素按钮：跳转到页面上元素的位置
  • 感知路由的高亮显示：显示当前页面所属的违规项

工作原理

自动化无障碍测试

Nuxt a11y 使用 axe-core 进行全面的无障碍审计。该模块会自动：

  1. 当您导航到新页面时运行无障碍扫描
  2. 检测针对 WCAG 2.0、WCAG 2.1、WCAG 2.2 和最佳实践的违规情况
  3. 按影响级别对违规项进行分组，并跟踪跨路由的违规情况
  4. 提供有关每个违规项的详细信息，包括 CSS 选择器、失败摘要和修复建议

元素高亮显示

该模块挂载到您的应用程序中以提供交互式调试：

  • 点击即固定：点击任何违规项即可固定并用编号徽章高亮显示受影响的元素
  • 悬停定位：当您滚动时，徽章会动态跟随元素
  • 路由跟踪：违规项与特定路由关联，以便更好地组织
  • 智能根元素处理：通过有用的通知，防止高亮显示 <html> 和 <body> 标签

自动扫描 - 持续扫描模式

启用可选的实时扫描，监听用户交互

  • 监控鼠标、键盘和触摸事件
  • 防抖动扫描以防止性能问题
  • 当 DOM 发生变化时，自动检测新的违规项
  • 可从 DevTools 控制面板开关

配置

模块选项

export default defineNuxtConfig({
  modules: ['@nuxt/a11y'],
  
  a11y: {
    // Enable/disable the module (default: true in dev mode)
    enabled: true,
    
    // Auto-highlight all violations when detected
    defaultHighlight: false,
    
    // Log violations to browser console
    logIssues: true,
    
    // Configure axe-core
    axe: {
      // axe-core configuration options
      options: {},
      
      // axe-core run options
      runOptions: {},
    },
  },
})

配置选项

enabled

  • 类型：boolean
  • 默认：true（仅在开发模式下）

启用或禁用无障碍模块。默认情况下，该模块仅在开发模式下运行。

defaultHighlight

  • 类型：boolean
  • 默认值：false

检测到无障碍违规时自动高亮显示。启用后，当前页面上的所有违规项都将被固定并以带编号的徽章高亮显示。

a11y: {
  defaultHighlight: true, // Auto-highlight all violations
}

logIssues

  • 类型：boolean
  • 默认值： true

控制是否将无障碍违规记录到浏览器控制台。启用后，违规项将以适当的样式和严重程度级别进行记录。

a11y: {
  logIssues: false, // Disable console logging
}

axe.options & axe.runOptions

  • 类型：object
  • 默认：{}

配置底层的 axe-core 运行器。有关可用选项，请参阅 axe-core 文档。

a11y: {
  axe: {
    options: {
      // Customize which rules to run
      rules: {
        'color-contrast': { enabled: true },
      },
    },
    runOptions: {
      // Customize how axe-core runs
      runOnly: ['wcag2a', 'wcag2aa'],
    },
  },
}

开发

# Install dependencies
pnpm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch

# Release new version
pnpm release