Embla Carousel A11y 插件
一个无障碍插件 埃布拉·卡鲁塞尔 遵循WAI-ARIA对旋转木马的写作实践.
特征
- 在旋转木马元素中添加适当的 ARIA 角色和属性
- 创建可访问的直播区域以宣布幻灯片更改
- 尊重用户提供的ARIA属性
- 显示有用的开发警告, 改善无障碍环境
安装
# npm
npm install embla-carousel @bluecadet/embla-carousel-a11y
# yarn
yarn add embla-carousel @bluecadet/embla-carousel-a11y
# pnpm
pnpm add embla-carousel @bluecadet/embla-carousel-a11y
基本用途
import A11y from "@bluecadet/embla-carousel-a11y";
import EmblaCarousel from "embla-carousel";
// Initialize Embla with the A11y plugin
const emblaNode = document.querySelector(".embla");
const embla = EmblaCarousel(emblaNode, { loop: true }, [A11y()]);
// The plugin is accessible through embla.plugins().a11y
const a11yPlugin = embla.plugins().a11y;
API 参考
选项
A11y 插件接受以下选项:
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
carouselLabel | string | undefined | undefined | 旋转木马的自定义标签. 如果不提供,则使用现有的 aria-label 或设置默认值. |
slideSelector | string | undefined | undefined | 自定义幻灯片元素的选择器 。 如果不提供,则使用 Embla 默认的幻灯片节点. |
announceSlideChanges | boolean | true | 是否向屏幕阅读器宣布幻灯片更改 . |
slideAnnouncementTemplate | string | "Slide {{currentSlide}} of {{totalSlides}}" | 幻灯片更改通知模板 。 使用 {{currentSlide}} 财务报告和审定财务报表 {{totalSlides}} 作为变量. |
showDeveloperWarnings | boolean | true | 是否在非生产环境中显示开发者控制台警告 . |
插件方法
A11y 插件暴露了以下方法:
| 方法 | 说明 |
|---|---|
update() | 基于当前自旋状态更新 ARIA 属性. 当所选幻灯片更改时自动调用 . |
无障碍特性
此插件执行以下无障碍特性:
ARIA 适当的作用和属性
- 添加数
role="region"到木马容器 - 添加数
aria-roledescription="carousel"把它当作木马 - 添加正则
aria-label(或尊重已存在的标签) - 添加数
role="group"财务报告和审定财务报表aria-roledescription="slide"转到幻灯片 - 应用
aria-hidden="true"改为非可见幻灯片 - 设定
aria-setsize财务报告和审定财务报表aria-posinset用于适当的幻灯片位置信息
发布现场区域
- 为屏幕阅读器通知创建可视化隐藏直播区域
- 导航时宣布当前幻灯片位置
- 使用自定义的公告模板
尊重用户属性
- 检测用户在初始化前提供的现有ARIA属性
- 保护这些属性而不是凌驾于它们之上
- 只更新动态属性, 如
aria-hidden视需要
发展警告
在开发模式中,插件为无障碍性改进提供了有益的控制台警告:
- 当没有为旋转木马提供无障碍名称( 标签) 时警告
- 建议在幻灯片中添加描述性标签
- 可在生产中或选择中被禁用
无障碍木马的最佳做法
为了最大限度的无障碍,我们建议:
- 提供有意义的标签: 使用
carouselLabel选项或添加aria-label带有描述内容的旋转木马和幻灯片.
<div class="embla" aria-label="Featured products">
<div class="embla__container">
<div class="embla__slide" aria-label="Red summer dress, $49.99">...</div>
<div class="embla__slide" aria-label="Blue winter coat, $89.99">...</div>
</div>
</div>
- 添加可访问的导航控制: 包含带有适当标签的上个/下个按钮.
<button class="embla__prev" aria-label="Previous slide">Prev</button>
<div class="embla">...</div>
<button class="embla__next" aria-label="Next slide">Next</button>
- 互动中暂停自动播放:如果使用自動播放,当用户与旋转木马互动时暂停.
const options = {
loop: true,
autoplay: true,
};
const embla = EmblaCarousel(emblaNode, options, [A11y()]);
// Pause autoplay on focus within the carousel
emblaNode.addEventListener("focusin", () => {
embla.plugins().autoplay.stop();
});
// Resume when focus leaves
emblaNode.addEventListener("focusout", (event) => {
if (!emblaNode.contains(event.relatedTarget)) {
embla.plugins().autoplay.play();
}
});
为什么无障碍问题
使你的旋转木马可以进入,确保:
- 有屏幕阅读器的用户可以理解并浏览您的内容
- 只有键盘用户可以访问所有自动机特性
- 您的网站符合 WCAG 等无障碍标准
- 你接触到更广泛的受众,包括残疾人
捐款
欢迎捐款! 请随意提交拉力请求.