Atributos obrigatórios do role ARIA
Consulte um role ARIA e receba o contrato exato dele: checkbox exige aria-checked, tem 8 atributos recomendados como aria-label e aria-invalid e precisa de um nome acessível. Baseado no WAI-ARIA 1.2, com roles desconhecidos recusados. Grátis no seu navegador.
- Grátis
- Funciona no seu navegador
- Sem cadastro
- Seus dados não saem do seu aparelho
Executar grátis
Exemplo resolvido
- Cargo
- checkbox
- Categoria
- widget
- Superclasse
- input
- Atributos obrigatórios
- aria-checked
- Quantidade obrigatória
- 1
Accessible Rich Internet Applications (ARIA) define dezenas de roles para que widgets personalizados exponham o mesmo significado dos controles HTML nativos. Cada role carrega um contrato fixo: alguns estados e propriedades são obrigatórios, outros são recomendados para suporte real de tecnologias assistivas, e muitos roles também exigem um nome acessível. Adivinhar esses atributos de memória é causa comum de falhas em auditorias — faltar aria-checked em um role checkbox, esquecer aria-controls em um combobox ou publicar um landmark region sem rótulo. Esta capacidade aceita um único nome de role ARIA, normaliza maiúsculas e prefixos comuns e devolve um pacote determinístico: atributos obrigatórios, atributos recomendados, categoria, superclasse, requisitos de nome e uma descrição curta fundamentada em WAI-ARIA 1.2.
O que significam atributos ARIA obrigatórios e recomendados
Na especificação WAI-ARIA cada role concreto lista Required States and Properties — atributos que o autor deve fornecer para o role ser válido — e Supported States and Properties que as tecnologias assistivas esperam quando o padrão precisa de estado mais rico. Atributos obrigatórios não são negociáveis: um role checkbox sem aria-checked, um slider sem aria-valuenow ou um combobox sem aria-controls e aria-expanded falham em verificações automáticas e confundem leitores de tela.
A resposta também indica se o role exige nome acessível e como esse nome pode ser calculado (atributos do autor, conteúdo do elemento ou proibido). Roles concretos descontinuados como directory permanecem consultáveis, mas são sinalizados para ferramentas de migração alertarem sem bloquear a consulta.
Casos de uso
Oráculos de lint de acessibilidade em CI
Com valores role extraídos do markup ou do Storybook, afirme que todo atributo obrigatório está presente antes do merge; falhe em roles abstratos ou desconhecidos.
Perguntas frequentes
Quais atributos ARIA são obrigatórios para um role?
Envie o nome do role (por exemplo checkbox, combobox, slider).
Isso valida a minha página HTML?
Não. Só consulta características da especificação para um nome de role. Use um auditor de acessibilidade (por exemplo web.accessibility) para varrer markup ao vivo.
Qual a diferença entre atributos obrigatórios e recomendados?
Os obrigatórios precisam estar presentes para o role ser válido: um checkbox sem aria-checked falha nas verificações automáticas e confunde os leitores de tela. Os recomendados são os que as tecnologias assistivas esperam quando o padrão precisa de mais estado, como desativado, somente leitura ou mensagens de erro.
O role checkbox precisa de nome acessível?
Sim. A consulta informa que o nome é obrigatório e que ele pode vir do próprio conteúdo do elemento ou do autor, por exemplo com aria-label ou aria-labelledby quando o texto visível não basta.
O que acontece com roles obsoletos ou abstratos?
Roles obsoletos, como directory, continuam podendo ser consultados, mas aparecem sinalizados para que uma ferramenta de migração avise sem bloquear. Roles abstratos e nomes desconhecidos são recusados, para ninguém criar atributos para um role que não existe.
Ferramentas relacionadas
Para desenvolvedores — acesso via API
Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.
Endpoint
Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.
Chame do seu código
curl -X POST https://api.kit.forhosting.com/web/aria-role-lookup \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"role":"checkbox"}'const res = await fetch("https://api.kit.forhosting.com/web/aria-role-lookup", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"role": "checkbox"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/web/aria-role-lookup",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"role": "checkbox"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/web/aria-role-lookup", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"role":"checkbox"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"role":"checkbox"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/web/aria-role-lookup", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Exemplo de requisição
{
"role": "checkbox"
}Exemplo de resposta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "web.aria_role_lookup",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.
Preço
Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.
Limites
timeout_sec | 30 |
max_crawl_pages | 25 |
Erros
| HTTP | Código | O que significa |
|---|---|---|
401 | unauthorized | Token ausente ou inválido. Confira o header Authorization. |
402 | insufficient_balance | Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo. |
404 | unknown_type | Esse tipo de tarefa não existe. Confira o campo type no catálogo. |
429 | rate_limited | Muitas requisições em pouco tempo. Espere um instante e tente de novo. |
Notas técnicas
Nomes não reconhecidos e roles abstratos falham com invalid_input para que o cliente nunca invente atributos de roles inexistentes. A mesma tabela pura alimenta a ferramenta gratuita do navegador e a API pré-paga a US$ 0,002 por item bem-sucedido.
O que significam atributos ARIA obrigatórios e recomendados
Os atributos recomendados nesta API são as propriedades suportadas que os autores mais precisam para teclado e AT corretos: flags de seleção e expansão, mínimo e máximo de valor em widgets de intervalo, orientação em toolbars e tablists, e ajudas de nome como aria-label e aria-labelledby quando o texto visível não basta.
Contrato de entrada, formato da resposta e erros
Notes opcionais aparecem quando um requisito é condicional — por exemplo um separator com foco precisa de aria-valuenow, aria-valuemin e aria-valuemax, embora um separator decorativo estático não. Exemplo: role checkbox devolve aria-checked obrigatório e um conjunto recomendado cobrindo readonly, required, disabled, rotulagem e mensagens de erro. Exemplo: role scrollbar devolve as quatro propriedades obrigatórias aria-controls, aria-valuenow, aria-valuemin e aria-valuemax. Envie um corpo JSON com um campo string obrigatório, role, que também pode chegar sob os aliases value, name, query ou aria_role. O motor remove espaços nas pontas, coloca o token em minúsculas, elimina prefixos opcionais como role= ou aria-role e remove espaços ou underscores internos para que column header e columnheader se resolvam iguais. Em sucesso o corpo ecoa o role normalizado, category, superclass, description, abstract false, required_attributes e recommended_attributes como arrays de strings ordenados, required_count e recommended_count, name_required, name_from, deprecated e spec definido como WAI-ARIA 1.2. Role ausente, string vazia, nomes desconhecidos e roles abstratos lançam invalid_input com mensagem que nomeia o problema; essas falhas não são cobradas. Combine a consulta com a documentação de lint ou design system de vocês; este endpoint não rastreia páginas nem valida markup ao vivo — só responde a pergunta da especificação para um nome de role por vez.
Onde a consulta de atributos de role ARIA vale a pena
Plataformas de treinamento e cursos WCAG usam o caminho gratuito do navegador para alunos explorarem checkbox versus switch, ou dialog versus alertdialog, sem memorizar as tabelas completas de características. Fixe nos testes os arrays ordenados devolvidos, documente rejeições de roles abstratos para autores que copiam nomes da taxonomia por engano, e você obtém um contrato estável para guias de estilo, ferramentas MCP e validadores na borda sem montar um motor de acessibilidade completo. Linters de acessibilidade e plugins de CI chamam a API como oráculo: dado o role encontrado em um nó, buscam atributos obrigatórios e falham o build se faltar algum. Como a implementação é parse de nível A com modelo de custo analítico, cada chamada bem-sucedida custa o preço base publicado US$ 0,002, roda offline no isolate do worker e nunca depende de baixar o site do W3C.
Casos de integração
Documentação de design system
Gere tabelas ARIA por componente a partir da string role para engenheiros verem atributos obrigatórios e recomendados ao lado da API React ou Web Component.
Treinamento e workshops WCAG
Permita que alunos consultem checkbox, combobox e region de forma interativa e comparem regras name_required sem memorizar as tabelas WAI-ARIA completas.
Perguntas técnicas
O que acontece se o nome do role for desconhecido?
A tarefa falha com invalid_input e uma mensagem de que o role não é reconhecido. Roles abstratos como widget ou landmark também são rejeitados porque autores não devem usá-los.
A consulta diferencia maiúsculas de minúsculas?
Não. Nomes de role são normalizados para minúsculas; prefixos opcionais como role= são removidos, e espaços ou underscores no token são eliminados.
Quanto custa a consulta de atributos de role ARIA?
A ferramenta do navegador é gratuita. Pedidos à API usam saldo pré-pago do KIT a US$ 0,002 por chamada bem-sucedida; entrada inválida não é cobrada.