AutoVizuA11y
v2.0.3
AutoVizuA11y는 스크린 리더 사용자를 위해 접근 가능한 데이터 시각화를 생성하는 프로세스를 자동화하는 React 라이브러리입니다. 개발자의 광범위한 접근성 지식 없이도 키보드를 사용하여 차트 탐색을 개선하는 기능에 중점을 둡니다.
이 도구는 여러 스크린 리더 사용자와 상담한 후 확인된 세 가지 주요 구성 요소, 즉 차트 탐색 가능성, 통찰력 있는 차트 설명; 차트를 탐색하고 더 빠르게 통찰력을 얻을 수 있는 바로가기 등이 있습니다.
npm i @feedzai/autovizua11y
다음을 사용하여 저장소를 로컬 디렉터리에 복제합니다.
git clone https://github.com/feedzai/autovizua11y.git
cd autovizua11y
gpt-3.5-turbo 모델을 사용하여 생성된 인간과 유사한 요약으로 구성됩니다. 데이터 시각화에 초점이 맞춰지면 기본적으로 더 짧은 설명이 발표됩니다. 설명은 수동으로 작성할 수도 있습니다.| 재산 | 필수/선택 | 유형 | 설명 |
|---|---|---|---|
data | 필수의 | 객체 배열 | 차트에 존재하는 데이터입니다. 각 쌍의 값은 문자열에 순서대로 추가되고 해당 DOM 요소에 초점이 맞춰지면 읽혀집니다. 참고: 객체 수는 DOM에 표시된 총 데이터 포인트와 일치해야 합니다. |
selectorType | 필수의 | 물체 | 데이터 요소의 HTML 유형(예: "사각형", "원" 또는 "경로") 또는 해당 클래스 이름 - 하나만 선택할 수 있습니다. 이를 통해 데이터 요소를 탐색할 수 있고 aria-label을 가질 수 있습니다. AutoVizuA11y는 지정된 클래스 또는 유형을 가진 데이터 요소 수가 데이터 소품을 통해 전달된 요소 수와 일치한다고 가정합니다 (레이블 없이는 요소가 남지 않도록 보장). |
type | 필수의 | 끈 | 데이터 시각화 유형입니다. 데이터 시각화에 초점이 맞춰지면 제목 뒤, 설명 앞에 발표됩니다. |
title | 필수의 | 끈 | 시각화 제목은 짧고 간결해야 하며 데이터 시각화 내 콘텐츠의 목적을 보여줍니다. 데이터 시각화에 초점이 맞춰지면 유형 및 더 길거나 짧은 설명 전에 발표됩니다. |
insights | 필수의 | 끈 | 통계적 통찰력을 도출하는 데 값이 사용되는 데이터 개체의 키에 해당하는 string 필요합니다. 예를 들어 데이터의 amount 에서 통찰력을 파생해야 하는 경우 해당 내용이 이 속성에 전달되어야 합니다. 빈 문자열 "" 이 전달되면 사용자는 '이 단축키는 이 차트에서 작동하지 않습니다.'라는 경고를 받게 됩니다. 이는 최소값, 평균값, 최대값과 관련된 바로가기뿐만 아니라 이러한 통찰력 및 기타 데이터 포인트와의 비교와 관련된 바로가기에 적용됩니다. 참고: 통찰력에 사용되는 값은 Number 유형이어야 합니다. |
context | 필수의 | 끈 | 데이터 시각화가 존재하는 맥락입니다. 설명을 자동으로 생성할 때 프롬프트에 전달되어 상황에 맞는 출력이 생성됩니다. |
descriptor | 선택 과목 | 끈 | string 수신함으로써 이 설명자는 데이터 요소가 무엇인지 더 잘 맥락화하는 데 도움이 됩니다. 이는 각 데이터 요소의 끝에 추가됩니다. 설명자가 제공되지 않으면 대신 빈 텍스트("")가 설정됩니다. |
multiSeries | 선택 과목 | 끈 | 다중 계열 데이터로 작업할 때 각 계열을 정의하는 데이터 개체의 키에 해당하는 string 제공하면 사용자가 일반 탐색 외에도 다양한 계열/클러스터 간을 탐색할 수 있습니다. 빈 문자열 "" 이 전달되면 도구는 데이터를 단일 계열로 해석합니다. |
shortcutGuide | 선택 과목 | JSX.요소 | AutoVizuA11y에는 기본 NativeShortcutGuide 있지만 직접 만들 수도 있습니다. ShortcutGuide는 <dialog> 에 래핑되어 있으며 해당 참조는 바로 shortcutGuide 에 추가할 수 있는 dialogRef 속성을 통해 얻을 수 있습니다. dialogRef 는 RefObject<HTMLDialogElement> 이며, 예를 들어 이 대화 상자를 닫는 논리를 처리하는 버튼을 만드는 데 사용할 수 있습니다. |
autoDescriptions | 필수(옵션 A) | 물체 | OpenAI 모델을 사용한 자동 설명 생성과 관련된 다양한 옵션입니다. AutoVizuA11y는 래핑된 시각화당 두 개의 API 호출을 수행합니다. 각 설명 유형(더 길거나 더 짧음)에 대해 하나씩입니다. 이 소품의 옵션은 여기에서 확인할 수 있습니다. 이 소품은 "manualDescriptions"와 동시에 사용할 수 없습니다. |
manualDescriptions | 필수(옵션 B) | 물체 | 데이터에 대해 수동으로 작성된 두 가지 설명입니다. 이 소품을 제공하면 자동 설명이 생성되지 않으므로 관련 비용이 발생하지 않습니다. 이 소품의 옵션은 여기에서 확인할 수 있습니다. 이 prop은 "autoDescriptions"와 동시에 사용할 수 없습니다. |
autoDescriptions 소품 옵션| 열쇠 | 필수/선택 | 유형 | 설명 |
|---|---|---|---|
dynamicDescriptions | 선택 과목 | 불리언 | 이를 false 로 설정하면 구성 요소가 첫 번째 렌더링 후 해당 차트에 대한 두 가지 설명을 생성하는 것을 중지합니다(설명은 localstorage에 저장됨). 이는 정적 시각화에 유용합니다. |
apiKey | 필수의 | 끈 | LLM이 데이터 시각화에 대해 인간과 유사한 설명을 생성할 수 있게 해주는 OpenAI API 키입니다. 여기에서 얻을 수 있습니다. 개발자는 API 키를 숨기기 위해 필요한 예방 조치를 취하는 것이 좋습니다. |
model | 선택 과목 | 끈 | 두 설명을 모두 생성하는 역할을 담당하는 OpenAI LLM입니다. 여기에서 사용 가능한 모델을 확인할 수 있습니다. 모델이 제공되지 않으면 gpt-3.5-turbo default 으로 선택됩니다. |
temperature | 선택 과목 | 숫자 | 두 설명을 모두 생성하는 모델에 사용되는 0 에서 1 사이의 온도입니다. 온도가 0에 가까울수록 API 호출 간에 더 결정적이어야 하며, 1에 가까울수록 API 호출 간에 더 무작위적이어야 합니다. 여기에서 사용 가능한 모델을 확인할 수 있습니다. 모델이 제공되지 않으면 default 으로 0 선택됩니다. |
manualDescriptions 소품 옵션| 열쇠 | 필수/선택 | 유형 | 설명 |
|---|---|---|---|
longer | 필수의 | 끈 | 래핑된 데이터 시각화와 관련된 더 긴 설명입니다. |
shorter | 필수의 | 끈 | 래핑된 데이터 시각화와 관련된 짧은 설명입니다. |
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 >
< / >
) ;
} 다음 단축키는 모두 AutoVizuA11y에서 다루는 데이터 시각화(또는 인접한 데이터 요소)에 초점을 맞춘 경우에만 작동합니다.
데이터 시각화 간의 탐색 외에도 다른 모든 바로가기 결과(즉, 통계적 통찰력)는 각 개별 시각화에만 관련됩니다.
이 도구는 VoiceOver, JAWS, NVDA는 물론 가장 일반적으로 사용되는 브라우저에서 테스트되었습니다. 각 단축키의 키 조합은 테스트된 스크린 리더 및 브라우저에서 다른 단축키와 충돌을 피하기 위한 의도로 선택되었습니다. 즉, JAWS 및 NVDA 사용자는 "초점 모드"( 삽입 + 공백 )를 켜서 시각화 사이와 내부에서 화살표 키를 사용한 탐색을 수행할 수 있도록 하는 것이 좋습니다 .
여기에서 AutoVizuA11y를 사용하여 구축된 일련의 예제를 확인할 수 있습니다(일부 기능에는 OpenAI API 키가 필요함).
모든 테스트는 Cypress를 사용하여 작성되었습니다.
로컬에서 테스트를 실행하려면 다음 안내를 따르세요.
# root
npm install
npm run build
# /examples
npm install
npm run dev
# root
npx cypress open
사용자는 ? 를 사용하여 바로가기 가이드에 액세스할 수 있습니다. 키를 누른 상태에서 AutoVizuA11y 차트나 기본 데이터 요소에 키보드 포커스를 둡니다. 개발자는 이 구성요소를 자신의 구성요소로 재정의하거나 스타일을 변경할 수 있습니다.
| 활성화 키 | 설명 |
|---|---|
| ? | 바로가기 가이드 입력 |
| ? 또는 Esc | 바로가기 가이드 남기기 |
| ↓ | 차트에 들어가다 |
| ↑ | 차트에서 나가기 |
| → | 페이지 요소에서 앞으로 이동 |
| ← | 페이지 요소에서 뒤로 이동 |
| Alt(옵션) + M | 차트 내 일련의 데이터 간 이동 |
| Home 또는 Alt(옵션) + Q | 차트의 시작 부분으로 이동 |
| End 또는 Alt(옵션) + W | 차트 끝으로 이동 |
| Alt(옵션) + X | 한 번에 이동할 데이터 포인트 수 정의 |
| + | 점프할 데이터 포인트에 한 번에 하나의 숫자를 추가합니다. |
| - | 한 번에 점프할 데이터 포인트에 하나의 숫자를 뺍니다. |
| Alt(옵션) + J | 최소값 |
| Alt(옵션) + K | 평균값 |
| Alt(옵션) + L | 최대값 |
| Alt(옵션) + Shift + J | 현재 포인트를 시각화의 최소값과 비교 |
| Alt(옵션) + Shift + K | 현재 포인트를 시각화의 평균값과 비교 |
| Alt(옵션) + Shift + L | 현재 지점을 시각화의 최대값과 비교 |
| Alt(옵션) + Z | 포인트를 차트의 나머지 부분과 비교하는 방법 |
| Alt(옵션) + B | 차트에 대한 자세한 설명 설정 |
| Alt(옵션) + S | 차트에 대한 간략한 설명 설정(기본값) |
Shortcut Guide는 시각적인 AutoVizuA11y의 유일한 측면입니다. 기본 가이드의 스타일을 변경할 수 있습니다. 다음은 이 구성 요소를 구성하는 요소의 className입니다.
| 클래스 이름 | HTML |
|---|---|
| 바로가기 가이드 | 형태 |
| 바로가기 가이드__컨테이너 | div |
| 바로가기 가이드__헤더 | div |
| 바로가기 가이드__제목 | h2 |
| 바로가기 가이드__버튼 라벨 | 피 |
| 바로가기 가이드__버튼 | 단추 |
| 바로가기 가이드__break | 시간 |
| 바로가기 가이드__본문 | div |
| 바로가기 가이드__섹션 | div |
| 바로가기 가이드__목록--제목 | h3 |
| 바로가기 가이드__목록 | div |
| 바로가기 가이드__행 | DL |
| 바로 가기-가이드__셀--바로가기 | dt |
| 바로가기 가이드__셀--설명 | dd |
다음은 AutoVizuA11y 생성 과정을 설명하는 EuroVis'24 전체 문서의 BibTeX 항목입니다.
@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
}다른 라이선스 옵션도 이용 가능합니다. 자세한 내용은 [email protected]으로 문의하세요.
