AutoVizuA11y
v2.0.3
AutoVizuA11y é uma biblioteca React que automatiza o processo de criação de visualizações de dados acessíveis para usuários de leitores de tela. Ele se concentra em recursos que melhoram a exploração de gráficos com teclado, sem exigir amplo conhecimento de acessibilidade dos desenvolvedores.
Esta ferramenta concentra-se em três componentes principais diferentes que foram identificados após consulta a vários usuários de leitores de tela: navegabilidade das cartas; descrições de gráficos perspicazes; e atalhos que permitem navegar pelos gráficos e obter insights mais rapidamente.
npm i @feedzai/autovizua11y
Clone o repositório em um diretório local usando:
git clone https://github.com/feedzai/autovizua11y.git
cd autovizua11y
gpt-3.5-turbo da OpenAI. A descrição mais curta é anunciada por padrão assim que a visualização de dados é focada. As descrições também podem ser escritas manualmente.| Propriedade | Obrigatório/Opcional | Tipo | Descrição |
|---|---|---|---|
data | Obrigatório | matriz de objetos | Os dados presentes no gráfico. Os valores de cada par são adicionados, em ordem, a uma string e lidos quando o elemento DOM correspondente é focado. Nota: o número de objetos precisa corresponder ao total de pontos de dados representados no DOM. |
selectorType | Obrigatório | objeto | O tipo HTML (por exemplo, "rect", "circle" ou "path") dos elementos de dados ou o nome da classe — apenas um pode ser escolhido. Isso permite que os elementos de dados sejam navegáveis e tenham um rótulo aria. AutoVizuA11y assume que o número de elementos de dados com a classe ou tipo especificado corresponde ao número de elementos passados pelo data prop (garantindo que nenhum elemento fique sem um rótulo). |
type | Obrigatório | corda | O tipo de visualização de dados. É anunciado assim que a visualização dos dados fica em foco, após o título e antes das descrições. |
title | Obrigatório | corda | O título da visualização, que deve ser curto e conciso, mostrando a finalidade do conteúdo da visualização dos dados. É anunciado assim que a visualização de dados é focada, antes do tipo e das descrições mais longas ou mais curtas. |
insights | Obrigatório | corda | Espera uma string que corresponde à chave no objeto de dados da qual os valores serão usados para derivar insights estatísticos. Por exemplo, se os insights devem ser derivados da amount nos dados, então é isso que deve ser passado nesta propriedade. Se uma string vazia "" for passada, o usuário receberá um alerta informando 'Este atalho não funciona neste gráfico'. Isso se aplica a atalhos relacionados a valores mínimos, médios e máximos, bem como aqueles que envolvem comparações com esses insights e outros pontos de dados. Observação: os valores usados para insights precisam ser do tipo Number . |
context | Obrigatório | corda | O contexto em que a visualização de dados está presente. É passado no prompt, ao gerar automaticamente as descrições, resultando em saídas contextualizadas. |
descriptor | Opcional | corda | Ao receber uma string , esse descritor ajuda a contextualizar melhor o que são os elementos de dados. Ele é adicionado no final de cada elemento de dados. Se nenhum descritor for fornecido, um texto em branco (“”) será definido. |
multiSeries | Opcional | corda | Ao trabalhar com dados multisséries, forneça uma string que corresponda à chave no objeto de dados que define cada série, permitindo aos usuários navegar entre diferentes séries/clusters, além da navegação normal. Se for passada uma string vazia "" a ferramenta interpreta os dados como série única. |
shortcutGuide | Opcional | JSX.Elemento | AutoVizuA11y tem seu NativeShortcutGuide padrão, mas você pode criar o seu próprio. O ShortcutGuide é encapsulado em um <dialog> , e sua referência pode ser obtida através da propriedade dialogRef , que você pode adicionar ao seu shortcutGuide . O dialogRef é um RefObject<HTMLDialogElement> , que você pode usar para criar, por exemplo, um botão que trata da lógica de fechar esse diálogo. |
autoDescriptions | Obrigatório (opção A) | objeto | Várias opções quanto à criação de descrições automáticas com modelos OpenAI. AutoVizuA11y faz duas chamadas de API por visualização encapsulada, uma para cada tipo de descrição (mais longa e mais curta). As opções para este adereço podem ser conferidas aqui. Esta propriedade não pode ser usada ao mesmo tempo que "manualDescriptions". |
manualDescriptions | Obrigatório (opção B) | objeto | Duas descrições dos dados escritas manualmente. Ao disponibilizar este adereço não são geradas descrições automáticas, não tendo assim quaisquer custos associados. As opções para este adereço podem ser conferidas aqui. Esta propriedade não pode ser usada ao mesmo tempo que "autoDescriptions". |
autoDescriptions| Chaves | Obrigatório/Opcional | Tipo | Descrição |
|---|---|---|---|
dynamicDescriptions | Opcional | booleano | Definir isso como false impede que o componente gere as duas descrições para aquele gráfico após a primeira renderização (as descrições são salvas no armazenamento local). Isso deve ser útil para visualizações estáticas. |
apiKey | Obrigatório | corda | A chave da API OpenAI, permitindo que um LLM gere descrições semelhantes às humanas da visualização de dados. Você pode obter o seu aqui. Recomenda-se que o desenvolvedor tome os cuidados necessários para ocultar a chave API. |
model | Opcional | corda | O OpenAI LLM responsável por gerar ambas as descrições. Você pode conferir os modelos disponíveis aqui. Se nenhum modelo for fornecido, gpt-3.5-turbo será escolhido por default . |
temperature | Opcional | número | Uma temperatura, de 0 a 1 , utilizada no modelo responsável por gerar ambas as descrições. Descrições com temperaturas próximas de 0 devem ser mais determinísticas entre chamadas de API, enquanto aquelas mais próximas de 1 devem ser mais aleatórias entre chamadas de API. Você pode conferir os modelos disponíveis aqui. Se nenhum modelo for fornecido, 0 será escolhido por default . |
manualDescriptions opções de suporte| Chaves | Obrigatório/Opcional | Tipo | Descrição |
|---|---|---|---|
longer | Obrigatório | corda | A descrição mais longa associada à visualização de dados agrupados. |
shorter | Obrigatório | corda | A descrição mais curta associada à visualização de dados agrupados. |
import { AutoVizuA11y } from "@feedzai/autovizua11y" ;
// ...
const barData = [
{ day : "Monday" , value : 8 } ,
{ day : "Tuesday" , value : 6.5 } ,
{ day : "Wednesday" , value : 7 } ,
{ day : "Thursday" , value : 9 } ,
{ day : "Friday" , value : 11 } ,
{ day : "Saturday" , value : 2 } ,
{ day : "Sunday" , value : 3 } ,
] ;
const multiLineData = [
{ series : "Croatia" , x : 2010 , y : 4.37 } ,
{ series : "Croatia" , x : 2015 , y : 4.25 } ,
{ series : "Croatia" , x : 2020 , y : 4.13 } ,
{ series : "Croatia" , x : 2022 , y : 4.03 } ,
{ series : "Latvia" , x : 2010 , y : 4.25 } ,
{ series : "Latvia" , x : 2015 , y : 4.25 } ,
{ series : "Latvia" , x : 2020 , y : 4.25 } ,
{ series : "Latvia" , x : 2022 , y : 4.25 } ,
{ series : "Lithuania" , x : 2010 , y : 4.25 } ,
{ series : "Lithuania" , x : 2015 , y : 4.25 } ,
{ series : "Lithuania" , x : 2020 , y : 4.25 } ,
{ series : "Lithuania" , x : 2022 , y : 4.25 } ,
] ;
const longerDesc = "..." ;
const shorterDesc = "..." ;
// ...
function App ( ) {
return (
< >
{ /* SingleSeries with automatic descriptions */ }
< AutoVizuA11y
data = { barData }
selectorType = { { element : "rect" } }
type = "bar chart"
title = "Number of hours spent looking at a screen per day of the week."
context = "Screen time dashboard"
insights = "value"
descriptor = "hours"
autoDescriptions = { {
dynamicDescriptions : false ,
apiKey : API_KEY ,
model : "gpt-3.5-turbo" ,
temperature : 0.1 ,
} }
>
< BarChart > < / BarChart >
< / AutoVizuA11y >
{ /* MultiSeries with manual descriptions */ }
< AutoVizuA11y
data = { multiLineData }
selectorType = { { element : "circle" } }
type = "Multi line chart"
title = "Latvia, Lithuania, and Croatia are among the countries where population is decreasing"
context = "Interface with World data"
insights = "y"
descriptor = "millions"
multiSeries = "series"
manualDescriptions = { {
longer : longerDesc ,
shorter : shorterDesc ,
} }
>
< LineChart > < / LineChart >
< / AutoVizuA11y >
< / >
) ;
} Todos os atalhos a seguir funcionam apenas quando focados em uma visualização de dados (ou elementos de dados adjacentes) cobertos pelo AutoVizuA11y.
Além da navegação entre visualizações de dados, todos os outros resultados de atalho (nomeadamente os insights estatísticos) referem-se apenas a cada visualização individual.
A ferramenta foi testada com VoiceOver, JAWS e NVDA, bem como com os navegadores mais utilizados. As combinações de teclas para cada atalho foram escolhidas com o intuito de evitar colisões com outras dos leitores de tela e navegadores testados. Dito isto, sugere-se aos usuários do JAWS e NVDA ativar o "modo Foco" ( Inserir + Espaço ) para que a navegação com as teclas de seta possa ser feita entre e dentro das visualizações .
Você pode verificar uma série de exemplos criados usando AutoVizuA11y aqui (alguns recursos requerem uma chave de API OpenAI).
Todos os testes foram escritos usando cipreste.
Para executar testes localmente:
# root
npm install
npm run build
# /examples
npm install
npm run dev
# root
npx cypress open
O Guia de Atalhos pode ser acessado pelo usuário, através do ? tecla, enquanto o teclado se concentra em um gráfico AutoVizuA11y ou em um elemento de dados subjacente. Como desenvolvedor, você pode substituir este componente pelo seu próprio ou alterar seu estilo.
| Chave(s) de ativação | Descrição |
|---|---|
| ? | Insira o guia de atalho |
| ? ou Esc | Deixar guia de atalho |
| ↓ | Entre em um gráfico |
| ↑ | Saia de um gráfico |
| → | Avançar em um elemento da página |
| ← | Retroceder em um elemento da página |
| Alt (opção) + M | Mova-se entre séries de dados dentro do gráfico |
| Home ou Alt (opção) + Q | Ir para o início de um gráfico |
| Fim ou Alt (opção) + W | Ir para o final de um gráfico |
| Alt (opção) + X | Defina o número de pontos de dados a serem saltados por vez |
| + | Adicione um número aos pontos de dados a serem saltados de cada vez |
| - | Subtraia um número aos pontos de dados a serem saltados de cada vez |
| Alt (opção) + J | Valor mínimo |
| Alt (opção) + K | Valor médio |
| Alt (opção) + L | Valor máximo |
| Alt (opção) + Shift + J | Compare o ponto atual com o valor mínimo da visualização |
| Alt (opção) + Shift + K | Compare o ponto atual com o valor médio da visualização |
| Alt (opção) + Shift + L | Compare o ponto atual com o valor máximo da visualização |
| Alt (opção) + Z | Como um ponto se compara ao resto do gráfico |
| Alt (opção) + B | Defina uma descrição mais longa do gráfico |
| Alt (opção) + S | Definir uma descrição mais curta do gráfico (padrão) |
O Guia de Atalhos é o único aspecto do AutoVizuA11y que também é visual. Você pode alterar o estilo da guia padrão. Abaixo estão os classNames dos elementos que compõem este componente:
| nomedaclasse | HTML |
|---|---|
| guia de atalho | forma |
| guia de atalho__container | divisão |
| guia de atalho__header | divisão |
| guia de atalho__título | h2 |
| guia de atalho__button-label | p |
| guia de atalho__botão | botão |
| guia de atalho__break | horas |
| guia de atalho__body | divisão |
| guia de atalho__seção | divisão |
| guia de atalho__lista--título | h3 |
| guia de atalho__lista | divisão |
| guia de atalho__row | dl |
| atalho-guia__célula--atalho | dt |
| guia de atalho__célula--explicação | dd |
Abaixo está a entrada do BibTeX para o artigo completo do EuroVis'24 que explica o processo de criação do AutoVizuA11y.
@article { 2024-AutoVizuA11y ,
title = { AutoVizuA11y: A Tool to Automate Screen Reader Accessibility in Charts } ,
ISSN = { 1467-8659 } ,
url = { http://dx.doi.org/10.1111/cgf.15099 } ,
DOI = { 10.1111/cgf.15099 } ,
journal = { Computer Graphics Forum } ,
publisher = { Wiley } ,
author = { Duarte, Diogo and Costa, Rita and Bizarro, Pedro and Duarte, Carlos } ,
year = { 2024 } ,
month = jun
}Outras opções de licenciamento podem estar disponíveis. Entre em contato com [email protected] para obter mais informações.
