如何制作支持鼠标与键盘差异化交互的自定义spinbutton控件

整体结构与核心语义 #

基于WAI ARIA spinbutton 角色构建核心容器，结合嵌套按钮实现鼠标/键盘双交互，结构示例：

<div class="custom-spinbutton" role="spinbutton" tabindex="0"
     aria-valuenow="16" aria-valuemin="12" aria-valuemax="24"
     aria-label="字号调整" aria-live="polite">
  <button class="spin-btn spin-btn--decrease" tabindex="-1" aria-label="减小字号">
    <svg class="custom-icon" aria-hidden="true">
      <!-- 自定义减小图标SVG代码 -->
    </svg>
  </button>
  <span class="spin-value">16</span>
  <button class="spin-btn spin-btn--increase" tabindex="-1" aria-label="增大字号">
    <svg class="custom-icon" aria-hidden="true">
      <!-- 自定义增大图标SVG代码 -->
    </svg>
  </button>
</div>

焦点管理规范 #

1. 嵌套结构的标准行为

   • 容器设置 tabindex="0" 作为唯一焦点入口，内部按钮设置 tabindex="-1" 禁止通过Tab键聚焦，仅允许鼠标点击触发交互
   • 按钮点击后需主动将焦点归还容器（container.focus()），确保键盘交互始终以容器为核心
   • WAI ARIA示例中按钮作为同级的实现，是早期兼容旧版阅读器的方案；嵌套结构更符合语义（按钮是spinbutton的组成部分），当前主流阅读器均支持嵌套模式

2. 键盘事件处理

   • 监听容器的 keydown 事件，处理上下/左右方向键：
     • 上/右键触发数值增加，下/左键触发数值减少
     • 禁止事件冒泡，避免干扰页面其他交互

屏幕阅读器兼容最优方案 #

使用 role="spinbutton" 是解决NVDA等阅读器拦截键盘事件的最优解，原因如下：

• spinbutton 是WAI ARIA定义的标准数值输入角色，阅读器会自动识别并赋予其方向键交互逻辑
• 无需额外处理浏览模式下的事件拦截，阅读器会将焦点容器识别为可交互控件，直接响应键盘操作
• 补充完整ARIA属性（aria-valuenow/aria-valuemin/aria-valuemax/aria-label），确保阅读器能准确播报数值范围与当前值

可访问性适配细节 #

1. 标签与播报逻辑

   • 容器必须设置 aria-label 或 aria-labelledby，明确控件用途（如aria-label="移调量调整"）
   • 添加 aria-live="polite" 到容器，数值变化时阅读器会自动播报新值，无需手动触发播报
   • 按钮需设置 aria-label 明确功能（如aria-label="降低滚动速度"），SVG图标添加 aria-hidden="true" 避免无意义播报

2. 按钮显示策略

   • 无需隐藏按钮，鼠标用户依赖按钮进行精准点击；屏幕阅读器用户通过容器的键盘交互与ARIA播报即可完成操作，按钮的aria-label仅作为辅助补充
   • 若需优化移动端空间，可通过CSS隐藏按钮文本（仅保留图标），但aria-label必须保留

硬性要求实现（自定义SVG图标） #

通过原生HTML插槽（<slot>）实现自定义图标插入，不依赖Element Internals API：

<div class="custom-spinbutton" role="spinbutton" tabindex="0" ...>
  <button class="spin-btn spin-btn--decrease" tabindex="-1" aria-label="减小字号">
    <slot name="decrease-icon">
      <!-- 默认减小图标SVG -->
    </slot>
  </button>
  ...
  <button class="spin-btn spin-btn--increase" tabindex="-1" aria-label="增大字号">
    <slot name="increase-icon">
      <!-- 默认增大图标SVG -->
    </slot>
  </button>
</div>

使用时直接传入自定义元素或SVG：

<custom-spinbutton>
  <custom-decrease-icon slot="decrease-icon"></custom-decrease-icon>
  <custom-increase-icon slot="increase-icon"></custom-increase-icon>
</custom-spinbutton>

移动端歌谱场景适配建议 #

针对字号、滚动速度、移调量三类步进规则，通过自定义属性配置参数：

<!-- 字号控制 -->
<div class="custom-spinbutton" role="spinbutton" tabindex="0"
     data-step="1" data-min="12" data-max="24"
     aria-valuenow="16" aria-label="字号调整">
  ...
</div>

<!-- 滚动速度控制 -->
<div class="custom-spinbutton" role="spinbutton" tabindex="0"
     data-step="0.1" data-min="0.5" data-max="2"
     aria-valuenow="1" aria-label="滚动速度调整">
  ...
</div>

数值变化时触发自定义事件通知控制器：

// 数值变更逻辑
function updateValue(container, delta) {
  const current = parseInt(container.getAttribute('aria-valuenow'));
  const step = parseFloat(container.dataset.step);
  const min = parseFloat(container.dataset.min);
  const max = parseFloat(container.dataset.max);
  const newValue = Math.min(Math.max(current + delta * step, min), max);
  
  container.setAttribute('aria-valuenow', newValue);
  container.querySelector('.spin-value').textContent = newValue;
  
  // 通知控制器
  container.dispatchEvent(new CustomEvent('spinValueChange', {
    detail: { value: newValue, type: container.getAttribute('aria-label') },
    bubbles: true
  }));
}

内容的提问来源于stack exchange，提问作者Darryl Noakes