Micromodal.js 轻量级可访问模态框库使用指南

什么是 Micromodal.js

Micromodal.js 是一个轻量级的 JavaScript 库，专门用于创建符合 WAI-ARIA 无障碍指南的模态对话框。它具有以下核心特点：

• 极小的体积：压缩后仅 1.9KB
• 零依赖：纯 JavaScript 实现
• 高度可配置：提供多种自定义选项
• 开箱即用的无障碍支持
• 简单易用的 API

核心功能特性

Micromodal.js 自动处理了模态框的多种交互场景：

1. 点击遮罩层关闭：点击模态框外部区域可关闭
2. ESC 键关闭：按下键盘 ESC 键可关闭模态框
3. 无障碍属性管理：自动管理 aria-hidden 等属性
4. 焦点管理：
   • 将焦点限制在模态框内（防止焦点逃逸）
   • 自动聚焦到第一个可聚焦元素
   • 关闭后恢复原始焦点位置
5. 键盘导航：支持 Tab 键在模态框内循环导航

安装方式

NPM/Yarn 安装

npm install micromodal --save
# 或
yarn add micromodal

CDN 引入

<script src="https://unpkg.com/micromodal/dist/micromodal.min.js"></script>

基础使用教程

1. HTML 结构

模态框的 HTML 需要遵循特定结构以确保无障碍性：

<div id="modal-1" aria-hidden="true">
  <div tabindex="-1" data-micromodal-close>
    <div role="dialog" aria-modal="true" aria-labelledby="modal-1-title">
      <header>
        <h2 id="modal-1-title">标题</h2>
        <button aria-label="关闭模态框" data-micromodal-close></button>
      </header>
      <div id="modal-1-content">
        内容区域
      </div>
    </div>
  </div>
</div>

关键元素说明：

1. 最外层容器：需要唯一 ID 和 aria-hidden="true" 初始状态
2. 遮罩层：添加 data-micromodal-close 实现点击关闭
3. 对话框本体：必须包含 role="dialog" 和 aria-labelledby 属性
4. 关闭按钮：应有明确的 aria-label 说明

2. 初始化

// ES6 模块导入
import MicroModal from 'micromodal';

// 或 CommonJS
const MicroModal = require('micromodal');

// 初始化
MicroModal.init();

3. 触发模态框

添加触发属性到按钮上：

<button data-micromodal-trigger="modal-1">打开模态框</button>

高级配置选项

Micromodal 提供丰富的配置选项：

MicroModal.init({
  onShow: modal => console.log(`${modal.id} 已显示`),  // 显示回调
  onClose: modal => console.log(`${modal.id} 已隐藏`), // 隐藏回调
  openTrigger: 'data-custom-open',    // 自定义打开属性
  closeTrigger: 'data-custom-close',  // 自定义关闭属性 
  openClass: 'is-open',               // 打开时添加的类名
  disableScroll: true,                // 是否禁用页面滚动
  disableFocus: false,               // 是否禁用自动聚焦
  awaitOpenAnimation: false,         // 等待打开动画
  awaitCloseAnimation: false,        // 等待关闭动画
  debugMode: true                   // 调试模式
});

编程式控制

除了数据属性，也可以通过 JavaScript 直接控制：

// 显示模态框
MicroModal.show('modal-id'); 

// 关闭模态框
MicroModal.close('modal-id');

// 使用元素对象
const modal = document.getElementById('modal-1');
MicroModal.show(modal);

// 带回调的显示
MicroModal.show('modal-id', {
  onShow: modal => console.log('显示回调'),
  onClose: modal => console.log('关闭回调')
});

样式定制建议

虽然 Micromodal 不强制样式，但建议遵循以下原则：

1. 为模态框添加适当的 z-index 确保在最上层
2. 遮罩层使用半透明背景
3. 添加打开/关闭动画提升用户体验
4. 确保模态框在移动设备上响应式显示

示例基础样式：

[aria-hidden="false"] {
  display: block;
}

[aria-hidden="true"] {
  display: none;
}

.modal-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(0,0,0,0.5);
}

.modal-container {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  background: white;
  padding: 20px;
  z-index: 1000;
}

最佳实践

1. 语义化标记：确保使用正确的 ARIA 属性
2. 焦点管理：不要让焦点意外移出模态框
3. 键盘导航：测试 Tab 和 Shift+Tab 导航
4. 移动端适配：考虑小屏幕下的显示效果
5. 性能优化：避免在模态框中放置过多内容

Micromodal.js 通过简洁的 API 和合理的默认值，让开发者能够轻松创建符合现代 Web 标准的模态对话框，同时保持极佳的性能表现。