Stable Diffusion WebUI 无障碍改造：键盘导航与屏幕阅读器适配

运行这个脚本后，你会发现焦点顺序可能完全不符合操作逻辑。比如，焦点可能在各个输入框之间乱跳，或者直接跳过了一些重要的操作按钮。

重构 Tab 索引顺序

正确的焦点顺序应该遵循'从上到下、从左到右'的自然阅读顺序，并且优先处理主要操作区域。对于 SD WebUI，合理的焦点顺序应该是：Prompt 输入框（主要文本区域）、Negative Prompt 输入框、Steps 参数滑块、Guidance Scale 参数滑块、Width 和 Height 输入框、Seed 输入框、'生成图片'按钮、结果展示区域。

我们需要通过 tabindex 属性来明确指定这个顺序：

<!-- 为关键元素设置明确的 tabindex -->
<div>
  <label for="prompt">正向提示词</label>
  <textarea tabindex="1" aria-label="请输入描述图片内容的提示词，建议使用英文" placeholder="例如：a beautiful sunset over mountains, digital art"></textarea>
</div>
<div>
  <label for="negative-prompt">负向提示词</label>
  <textarea tabindex="2" aria-label="请输入不希望出现在图片中的内容" placeholder="例如：blurry, low quality, extra fingers"></textarea>
</div>
<!-- 参数滑块需要特殊的键盘支持 -->
<div>
  <label for="steps-slider">采样步数 (Steps)</label>
  <input type="range" tabindex="3" min="1" max="50" value="20" aria-valuemin="1" aria-valuemax="50" aria-valuenow="20" aria-valuetext="20 步">
  <span aria-live="polite">20</span>
</div>

为滑块控件添加键盘支持

HTML 原生的 <input type="range"> 虽然可以通过 Tab 聚焦，但默认的键盘交互不够友好。我们需要增强它的键盘控制：

// 增强滑块控件的键盘交互
function enhanceSliderAccessibility(sliderId) {
  const slider = document.getElementById(sliderId);
  const valueDisplay = slider.nextElementSibling;
  if (!slider || !valueDisplay) return;

  // 监听键盘事件
  slider.addEventListener('keydown', function(event) {
    const step = parseInt(slider.getAttribute('step')) || 1;
    const min = parseInt(slider.min);
    const max = parseInt(slider.max);
    let newValue = parseInt(slider.value);

    switch(event.key) {
      case 'ArrowRight':
      case 'ArrowUp':
        newValue = Math.min(max, newValue + step);
        break;
      case 'ArrowLeft':
      case 'ArrowDown':
        newValue = Math.max(min, newValue - step);
        break;
      case 'Home':
        newValue = min;
        break;
      case 'End':
        newValue = max;
        break;
      case 'PageUp':
        newValue = Math.min(max, newValue + (step * 5));
        break;
      case 'PageDown':
        newValue = Math.max(min, newValue - (step * 5));
        break;
      default:
        return; // 其他按键不处理
    }

    // 更新滑块值
    slider.value = newValue;
    // 更新显示值
    valueDisplay.textContent = newValue;
    // 更新 ARIA 属性
    slider.setAttribute('aria-valuenow', newValue);
    slider.setAttribute('aria-valuetext', `${newValue}步`);
    // 触发 change 事件，让其他代码能响应变化
    slider.dispatchEvent(new Event('input'));
    slider.dispatchEvent(new Event('change'));
    event.preventDefault();
  });

  // 实时更新显示值
  slider.addEventListener('input', function() {
    valueDisplay.textContent = this.value;
    this.setAttribute('aria-valuenow', this.value);
    this.setAttribute('aria-valuetext', `${this.value}步`);
  });
}

// 为所有滑块应用增强功能
document.addEventListener('DOMContentLoaded', function() {
  enhanceSliderAccessibility('steps-slider');
  enhanceSliderAccessibility('guidance-slider');
  // ... 其他滑块
});

添加快捷键支持

除了基本的导航，我们还可以为常用操作添加快捷键，进一步提升操作效率：

// 全局快捷键支持
document.addEventListener('keydown', function(event) {
  // 忽略在输入框中的按键
  if (event.target.tagName === 'INPUT' || event.target.tagName === 'TEXTAREA') {
    return;
  }

  // Ctrl+Enter 生成图片
  if (event.ctrlKey && event.key === 'Enter') {
    event.preventDefault();
    document.getElementById('generate-btn').click();
    announceToScreenReader('开始生成图片，请稍候');
  }

  // Ctrl+R 重置所有参数
  if (event.ctrlKey && event.key === 'r') {
    event.preventDefault();
    resetAllParameters();
    announceToScreenReader('所有参数已重置为默认值');
  }

  // Ctrl+S 保存当前设置
  if (event.ctrlKey && event.key === 's') {
    event.preventDefault();
    saveCurrentSettings();
    announceToScreenReader('当前设置已保存');
  }
});

// 屏幕阅读器播报函数
function announceToScreenReader(message, priority = 'polite') {
  // 创建隐藏的 aria-live 区域
  let liveRegion = document.getElementById('a11y-announcer');
  if (!liveRegion) {
    liveRegion = document.createElement('div');
    liveRegion.id = 'a11y-announcer';
    liveRegion.setAttribute('aria-live', priority);
    liveRegion.setAttribute('aria-atomic', 'true');
    liveRegion.style.cssText = `
      position: absolute;
      width: 1px;
      height: 1px;
      padding: 0;
      margin: -1px;
      overflow: hidden;
      clip: rect(0, 0, 0, 0);
      white-space: nowrap;
      border: 0;
    `;
    document.body.appendChild(liveRegion);
  }

  // 更新内容触发播报
  liveRegion.textContent = message;
  // 清空内容以便下次播报
  setTimeout(() => {
    liveRegion.textContent = '';
  }, 1000);
}

屏幕阅读器适配深度优化

屏幕阅读器用户'听'网页而不是'看'网页。我们需要确保界面上的每个元素都能被正确识别和描述。

完善 ARIA 属性

ARIA（Accessible Rich Internet Applications）是一组属性，用于增强 HTML 元素的可访问性。对于 SD WebUI，我们需要重点关注以下几个方面：

<!-- 主操作区域标记 -->
<div role="main" aria-label="Stable Diffusion 图像生成主界面">
  <!-- 提示词区域 -->
  <section aria-labelledby="prompt-section-heading">
    <h2>提示词设置</h2>
    <div>
      <label for="prompt-input">
        <span>正向提示词</span>
        <span>描述你想要的图片内容，建议使用英文</span>
      </label>
      <textarea aria-describedby="prompt-help" placeholder="例如：a cat sitting on a windowsill, sunlight, detailed fur"></textarea>
      <div aria-live="polite">已输入<span>0</span>个字符</div>
    </div>
  </section>

  <!-- 参数设置区域 -->
  <section aria-labelledby="params-section-heading">
    <h2>生成参数设置</h2>
    <!-- 滑块组 -->
    <div role="group" aria-labelledby="steps-label">
      <div>
        <span>采样步数</span>
        <span aria-live="polite">20</span>
      </div>
      <input type="range" aria-valuemin="1" aria-valuemax="50" aria-valuenow="20" aria-valuetext="20 步" aria-describedby="steps-desc">
      <div>控制生成过程的精细程度，值越高细节越多但速度越慢</div>
    </div>
  </section>

  <!-- 生成按钮 -->
  <button aria-label="生成图片，当前设置：采样步数 20，引导系数 7.5" aria-busy="false">
    <span>生成图片</span>
    <span aria-hidden="true"></span>
  </button>
</div>

<!-- 视觉隐藏但屏幕阅读器可读的样式 -->
<style>
.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}
</style>

动态内容实时播报

AI 图像生成是一个异步过程，我们需要让屏幕阅读器用户也能了解生成进度和结果：

// 增强生成过程的可访问性
class AccessibleImageGenerator {
  constructor() {
    this.generateButton = document.getElementById('generate-button');
    this.statusRegion = document.getElementById('generation-status');
    this.resultRegion = document.getElementById('result-display');
    this.init();
  }

  init() {
    // 监听生成按钮点击
    this.generateButton.addEventListener('click', () => {
      this.startGeneration();
    });

    // 创建状态播报区域
    if (!this.statusRegion) {
      this.statusRegion = document.createElement('div');
      this.statusRegion.id = 'generation-status';
      this.statusRegion.setAttribute('aria-live', 'assertive');
      this.statusRegion.setAttribute('aria-atomic', 'true');
      this.statusRegion.className = 'visually-hidden';
      document.body.appendChild(this.statusRegion);
    }
  }

  startGeneration() {
    // 更新按钮状态
    this.generateButton.setAttribute('aria-busy', 'true');
    this.generateButton.disabled = true;

    // 播报开始状态
    this.announceStatus('开始生成图片，请稍候...');

    // 模拟生成过程（实际应替换为真实的 API 调用）
    setTimeout(() => {
      this.announceStatus('正在处理提示词...');
    }, 1000);
    setTimeout(() => {
      this.announceStatus('正在生成图像，已完成 50%...');
    }, 3000);
    setTimeout(() => {
      this.completeGeneration();
    }, 6000);
  }

  announceStatus(message) {
    this.statusRegion.textContent = `状态更新：${message}`;
    // 同时更新按钮的 aria-label
    const currentLabel = this.generateButton.getAttribute('aria-label');
    const baseLabel = currentLabel.split('，')[0];
    this.generateButton.setAttribute('aria-label', `${baseLabel}，${message}`);
  }

  completeGeneration() {
    // 恢复按钮状态
    this.generateButton.setAttribute('aria-busy', 'false');
    this.generateButton.disabled = false;

    // 播报完成状态
    this.announceStatus('图片生成完成！');

    // 更新结果区域
    this.updateResultAccessibility();
  }

  updateResultAccessibility() {
    const resultImage = document.querySelector('#result-display img');
    if (!resultImage) return;

    // 为图片添加详细描述
    const prompt = document.getElementById('prompt-input').value;
    const steps = document.getElementById('steps-slider').value;
    resultImage.setAttribute('alt', `根据提示词"${prompt.substring(0, 100)}..."生成的图像，采样步数${steps}步`);

    // 创建详细描述区域
    const description = document.createElement('div');
    description.className = 'image-description visually-hidden';
    description.id = 'image-description';
    description.innerHTML = `
      <h3>生成结果详情</h3>
      <p>提示词：${prompt}</p>
      <p>采样步数：${steps}步</p>
      <p>图像尺寸：512×512 像素</p>
      <p>生成时间：约 6 秒</p>
    `;
    resultImage.parentNode.appendChild(description);
    resultImage.setAttribute('aria-describedby', 'image-description');

    // 播报结果可用
    this.announceStatus('新图片已生成，可使用 Tab 键查看详情');
  }
}

// 初始化
document.addEventListener('DOMContentLoaded', () => {
  new AccessibleImageGenerator();
});

为图标按钮添加文本替代

WebUI 中大量使用图标按钮，这对屏幕阅读器来说是看不见的。我们需要为每个图标提供文本描述：

<!-- 改造前的图标按钮 -->
<button>
  <svg>...</svg>
</button>

<!-- 改造后的可访问版本 -->
<button aria-label="下载图片">
  <svg aria-hidden="true" focusable="false">
    <!-- SVG 内容 -->
  </svg>
  <span>下载图片</span>
</button>

<!-- 或者使用 title 属性（部分屏幕阅读器支持） -->
<button title="下载图片">
  <svg aria-hidden="true">
    <!-- SVG 内容 -->
  </svg>
</button>

视觉设计与交互反馈优化

无障碍设计不仅仅是代码层面的改造，视觉和交互的优化同样重要。好的无障碍设计对所有用户都有好处。

高对比度与色彩安全

确保界面有足够的对比度，让色弱或视力不佳的用户也能清晰辨认：

/* 无障碍友好的颜色方案 */
:root {
  /* 高对比度颜色 */
  --text-primary: #000000;
  --text-secondary: #333333;
  --background-primary: #ffffff;
  --background-secondary: #f5f5f5;
  /* 焦点指示器 */
  --focus-outline: 3px solid #0056b3;
  --focus-outline-offset: 2px;
  /* 状态颜色 */
  --success-color: #2e7d32;
  --error-color: #c62828;
  --warning-color: #f57c00;
  --info-color: #0277bd;
}

/* 确保足够的对比度 */
.control-label {
  color: var(--text-primary);
  font-weight: 600;
}
.help-text {
  color: var(--text-secondary);
  font-size: 0.9em;
}

/* 焦点状态明显可见 */
button:focus,
input:focus,
textarea:focus,
select:focus,
[tabindex]:focus {
  outline: var(--focus-outline);
  outline-offset: var(--focus-outline-offset);
}

/* 禁用状态也要清晰 */
button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

/* 错误状态高亮 */
.input-error {
  border-color: var(--error-color);
  background-color: rgba(198, 40, 40, 0.05);
}
.input-error:focus {
  outline-color: var(--error-color);
}

清晰的焦点指示器

焦点指示器是键盘用户的'鼠标指针'，必须清晰可见：

/* 增强焦点指示器 */
*:focus {
  outline: 3px solid #0056b3;
  outline-offset: 2px;
  box-shadow: 0 0 0 3px rgba(0, 86, 179, 0.2);
}

/* 移除默认轮廓并添加自定义样式 */
button:focus,
input:focus,
textarea:focus,
select:focus {
  outline: none;
  border-color: #0056b3;
  box-shadow: 0 0 0 3px rgba(0, 86, 179, 0.3);
}

/* 为滑块添加特殊的焦点样式 */
input[type="range"]:focus {
  outline: none;
}
input[type="range"]:focus::-webkit-slider-thumb {
  box-shadow: 0 0 0 3px rgba(0, 86, 179, 0.5);
}
input[type="range"]:focus::-moz-range-thumb {
  box-shadow: 0 0 0 3px rgba(0, 86, 179, 0.5);
}

/* 链接焦点样式 */
a:focus {
  text-decoration: underline;
  background-color: rgba(0, 86, 179, 0.1);
}

操作状态反馈

为用户的操作提供即时反馈，特别是对于异步操作：

// 操作反馈系统
class OperationFeedback {
  constructor() {
    this.feedbackContainer = this.createFeedbackContainer();
  }

  createFeedbackContainer() {
    const container = document.createElement('div');
    container.id = 'operation-feedback';
    container.setAttribute('role', 'status');
    container.setAttribute('aria-live', 'polite');
    container.setAttribute('aria-atomic', 'true');
    container.style.cssText = `
      position: fixed;
      top: 20px;
      right: 20px;
      z-index: 10000;
      max-width: 300px;
    `;
    document.body.appendChild(container);
    return container;
  }

  showFeedback(message, type = 'info') {
    const feedback = document.createElement('div');
    feedback.className = `feedback feedback-${type}`;
    feedback.setAttribute('role', 'alert');

    // 添加图标
    const icon = document.createElement('span');
    icon.className = 'feedback-icon';
    icon.setAttribute('aria-hidden', 'true');
    icon.textContent = this.getIconForType(type);

    // 添加消息
    const text = document.createElement('span');
    text.className = 'feedback-text';
    text.textContent = message;

    feedback.appendChild(icon);
    feedback.appendChild(text);

    // 添加到容器
    this.feedbackContainer.appendChild(feedback);

    // 自动移除
    setTimeout(() => {
      feedback.style.opacity = '0';
      feedback.style.transform = 'translateX(100%)';
      setTimeout(() => {
        if (feedback.parentNode) {
          feedback.parentNode.removeChild(feedback);
        }
      }, 300);
    }, 5000);

    return feedback;
  }

  getIconForType(type) {
    const icons = {
      'success': '✓',
      'error': '✗',
      'warning': '⚠',
      'info': 'ℹ'
    };
    return icons[type] || icons.info;
  }
}

// 使用示例
const feedback = new OperationFeedback();

// 生成开始
document.getElementById('generate-btn').addEventListener('click', () => {
  feedback.showFeedback('开始生成图片，请稍候...', 'info');
});

// 生成完成
function onGenerationComplete() {
  feedback.showFeedback('图片生成成功！', 'success');
  // 同时为屏幕阅读器播报
  const statusRegion = document.getElementById('generation-status');
  if (statusRegion) {
    statusRegion.textContent = '图片生成完成，已显示在结果区域';
  }
}

// 错误处理
function onGenerationError(error) {
  feedback.showFeedback(`生成失败：${error.message}`, 'error');
  // 详细的错误信息（屏幕阅读器可访问）
  const errorDetails = document.createElement('div');
  errorDetails.className = 'visually-hidden';
  errorDetails.id = 'error-details';
  errorDetails.innerHTML = `
    <h3>错误详情</h3>
    <p>错误类型：${error.type || '未知错误'}</p>
    <p>错误信息：${error.message}</p>
    <p>建议操作：请检查网络连接后重试</p>
  `;
  document.body.appendChild(errorDetails);
}

测试与验证

改造完成后，必须进行全面的测试，确保无障碍功能真正可用。

键盘导航测试清单

手动测试键盘导航的完整性：

1. Tab 键导航：按 Tab 键，焦点是否按逻辑顺序移动？
2. Shift+Tab 反向导航：是否正常工作？
3. Enter/Space 激活：按钮和链接能否用 Enter 或 Space 激活？
4. 方向键控制：滑块、下拉菜单等能否用方向键控制？
5. Escape 关闭：弹窗、菜单能否用 Escape 关闭？
6. 快捷键冲突：自定义快捷键是否与浏览器快捷键冲突？

屏幕阅读器测试

使用主流屏幕阅读器进行测试：

// 屏幕阅读器兼容性测试辅助脚本
function runScreenReaderTests() {
  const tests = [
    {
      name: '所有图片都有 alt 文本',
      test: () => {
        const images = document.querySelectorAll('img');
        let failed = [];
        images.forEach((img, index) => {
          if (!img.hasAttribute('alt') || img.alt.trim() === '') {
            failed.push(`图片 #${index}: ${img.src || '无 src'}`);
          }
        });
        return failed.length === 0 ? '通过' : `失败：${failed.join(', ')}`;
      }
    },
    {
      name: '所有表单控件都有标签',
      test: () => {
        const inputs = document.querySelectorAll('input, textarea, select');
        let failed = [];
        inputs.forEach((input, index) => {
          const id = input.id;
          if (!id) {
            failed.push(`控件 #${index}: 无 id 属性`);
          } else {
            const label = document.querySelector(`label[for="${id}"]`);
            if (!label) {
              failed.push(`控件 ${id}: 无对应 label`);
            }
          }
        });
        return failed.length === 0 ? '通过' : `失败：${failed.join(', ')}`;
      }
    },
    {
      name: '所有按钮都有可访问名称',
      test: () => {
        const buttons = document.querySelectorAll('button');
        let failed = [];
        buttons.forEach((btn, index) => {
          const name = btn.textContent.trim() || btn.getAttribute('aria-label') || btn.getAttribute('title');
          if (!name) {
            failed.push(`按钮 #${index}: 无可访问名称`);
          }
        });
        return failed.length === 0 ? '通过' : `失败：${failed.join(', ')}`;
      }
    },
    {
      name: 'ARIA 属性使用正确',
      test: () => {
        const elements = document.querySelectorAll('[aria-*]');
        let warnings = [];
        elements.forEach((el, index) => {
          // 检查常见的 ARIA 误用
          if (el.hasAttribute('aria-hidden') && el.hasAttribute('aria-label')) {
            warnings.push(`元素 #${index}: 同时使用 aria-hidden 和 aria-label`);
          }
          if (el.hasAttribute('role') && el.tagName.toLowerCase() === el.getAttribute('role')) {
            warnings.push(`元素 #${index}: 冗余的 role 属性`);
          }
        });
        return warnings.length === 0 ? '通过' : `警告：${warnings.join(', ')}`;
      }
    }
  ];

  console.log('=== 屏幕阅读器兼容性测试 ===');
  tests.forEach(test => {
    const result = test.test();
    console.log(`${test.name}: ${result}`);
  });
  console.log('=== 测试结束 ===');
}

// 在控制台运行测试
// runScreenReaderTests();

自动化测试集成

将无障碍测试集成到开发流程中：

// package.json 中添加无障碍测试脚本
{
  "scripts": {
    "test:a11y": "pa11y http://localhost:7860 --reporter json",
    "test:a11y-ci": "pa11y-ci --sitemap http://localhost:7860/sitemap.xml"
  },
  "devDependencies": {
    "pa11y": "^6.0.0",
    "pa11y-ci": "^3.0.0"
  }
}

# .pa11yci 配置文件
# 持续集成中的无障碍测试配置
urls:
  - http://localhost:7860/
  - http://localhost:7860/#generate
standard: WCAG2AA
ignore:
  - WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail
  - WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.NoContent
timeout: 30000
wait: 5000
chromeLaunchConfig:
  args:
    - "--no-sandbox"
    - "--disable-setuid-sandbox"

真实用户测试

最重要的测试是让真实用户使用：

1. 招募测试用户：包括屏幕阅读器用户、键盘导航用户、运动障碍用户
2. 观察使用过程：记录遇到的问题和困惑
3. 收集反馈：了解哪些改进最有用，哪些还不够
4. 持续迭代：根据反馈不断优化

总结：让 AI 工具真正人人可用

通过这一系列的无障碍改造，我们让 Stable Diffusion v1.5 Archive 的 WebUI 从一个只能鼠标操作的界面，变成了一个真正人人可用的 AI 创作工具。这次改造的核心收获可以总结为以下几点：

关键改造要点回顾

1. 键盘导航是基础：确保所有功能都能通过键盘完成，这是运动障碍用户的生命线
2. 屏幕阅读器兼容性是关键：为每个界面元素提供清晰的语义描述，让视觉障碍用户也能'看见'
3. 反馈系统很重要：无论是视觉反馈还是听觉反馈，都要让用户知道发生了什么
4. 测试验证不可少：自动化测试和真实用户测试相结合，确保改造真正有效

实际效果对比

改造前后的对比非常明显：

• 改造前：视觉障碍用户完全无法使用，运动障碍用户操作困难
• 改造后：屏幕阅读器可以完整描述界面，键盘可以完成所有操作，操作状态有清晰反馈

可复用的经验

这次改造中积累的经验可以应用到其他 AI 工具中：

1. 渐进增强策略：先确保基本功能可用，再逐步添加高级特性
2. 语义化 HTML：使用正确的 HTML 元素和 ARIA 属性，这是无障碍的基础
3. 键盘交互设计：遵循 WCAG 标准，提供完整的键盘支持
4. 用户测试优先：真实用户的反馈比任何自动化测试都重要

下一步改进方向

虽然我们已经完成了主要改造，但仍有优化空间：

1. 多语言支持：让屏幕阅读器播报支持更多语言
2. 个性化设置：允许用户自定义快捷键和反馈方式
3. 离线支持：确保无障碍功能在离线状态下也能工作
4. 性能优化：减少无障碍功能对性能的影响

最后的建议

如果你也在开发 AI 工具，不妨从项目开始就考虑无障碍设计。这不仅仅是道德责任，也是扩大用户群体的明智选择。一个真正优秀的工具，应该让所有人都能使用，无论他们的能力如何。

记住：好的无障碍设计，对所有人都是更好的设计。当我们为特殊需求用户优化时，往往也能让普通用户获得更好的体验。这不仅是技术的进步，更是技术的温度。