亚- 作用

亚- 作用 是一个轻量级的公用工具库,它为动态获取有效的ARIA角色提供了可靠的方式. 它通过防止硬码角色值并促成验证以更好地遵守UI的可访问性来简化可访问性开发.

* 特性

• · 获取所有有效ARIA角色的完整、最新清单
• 确定某一角色是否为公认的ARIA角色
• * 类型安全访问ARIA角色名称
• 轻、快、无依赖
• * 设计用于无障碍工具、测试和前端框架

* 安装

npm install @a11y-tools/aria-roles

使用量

基本用途

import { getAllAriaRoles, isValidAriaRole, ariaRoles } from "@a11y-tools/aria-roles";

// Get all valid ARIA roles
console.log(getAllAriaRoles()); // Returns an array of valid ARIA roles

// Validate a role
console.log(isValidAriaRole("button")); // true
console.log(isValidAriaRole("fake-role")); // false

// Type-safe access to role names
element.setAttribute('role', ariaRoles.button);
element.setAttribute('role', ariaRoles.tabpanel);

类型脚本使用

import { AriaRole, ariaRoles, isValidAriaRole } from "@a11y-tools/aria-roles";

// Type-safe role definition
const myRole: AriaRole = ariaRoles.button;

// Type narrowing with isValidAriaRole
function setRole(element: HTMLElement, role: string) {
  if (isValidAriaRole(role)) {
    // TypeScript knows 'role' is of type AriaRole here
    element.setAttribute('role', role);
  } else {
    console.warn(`Invalid ARIA role: ${role}`);
  }
}

反应示例

import React from 'react';
import { ariaRoles } from '@a11y-tools/aria-roles';

function AccessibleButton({ children, onClick }) {
  return (
    <div 
      role={ariaRoles.button} 
      onClick={onClick}
      tabIndex={0}
      onKeyDown={(e) => {
        if (e.key === 'Enter' || e.key === ' ') {
          onClick();
        }
      }}
    >
      {children}
    </div>
  );
}

Vue 示例

<template>
  <div 
    :role="ariaRoles.button"
    @click="onClick"
    tabindex="0"
    @keydown="handleKeyDown"
  >
    <slot></slot>
  </div>
</template>

<script>
import { ariaRoles } from '@a11y-tools/aria-roles';

export default {
  setup() {
    const handleKeyDown = (e) => {
      if (e.key === 'Enter' || e.key === ' ') {
        onClick();
      }
    };
    
    return {
      ariaRoles,
      handleKeyDown
    };
  },
  methods: {
    onClick() {
      // Handle click
    }
  }
}
</script>

测试示例

import { render, screen } from '@testing-library/react';
import { ariaRoles, isValidAriaRole } from '@a11y-tools/aria-roles';

// React Testing Library - use ariaRoles for type-safe queries
test('Component uses correct ARIA roles', () => {
  render(<MyComponent />);
  
  // Query elements by their roles using ariaRoles
  const button = screen.getByRole(ariaRoles.button);
  const navigation = screen.getByRole(ariaRoles.navigation);
  
  // Verify elements have proper attributes
  expect(button).toHaveAttribute('aria-pressed', 'false');
  expect(navigation).toBeInTheDocument();
});

// Validate all roles in a component
test('All roles are valid', () => {
  const { container } = render(<MyComponent />);
  
  // Check that all role attributes are valid
  container.querySelectorAll('[role]').forEach(element => {
    const role = element.getAttribute('role');
    expect(isValidAriaRole(role)).toBe(true);
  });
});

API 参考

getAllAriaRoles()

返回所有有效的 ARIA 字符串的数组 .

function getAllAriaRoles(): AriaRole[]

isValidAriaRole(role)

验证字符串是否为有效的 ARIA 角色 。 在TypeScript中,此函数起到类型守护的作用.

function isValidAriaRole(role: string): role is AriaRole

ariaRoles

一个提供类型安全访问所有ARIA角色名的对象. 每个属性以一个ARIA角色命名并返回角色名作为字符串.

const ariaRoles: Record<AriaRole, AriaRole>

AriaRole (只有脚本)

一个代表所有有效ARIA角色的TypeScript类型.

type AriaRole = 'alert' | 'alertdialog' | 'application' | /* ... */;

捐款

欢迎捐款! 请随意提交拉力请求.

许可证

这个项目根据麻省理工学院的许可证获得许可.