feat(aria): 设置无障碍标签 (#3656)

* feat(aria): 设置无障碍标签

* docs: add aria document

Author: hustcc

docs/api/general/chart.zh.md

@@ -43,6 +43,20 @@ changeSize(width: number, height: number): Chart;
 changeVisible(visible: boolean): Chart;
 ```
 
+### chart.aria()
+
+开启或者关闭无障碍标签，`false` 表示关闭，否则需要填入无障碍标签配置内容，默认关闭。
+
+```sign
+aria(false ｜ AriaOptions): void
+```
+
+Example:
+
+```ts
+chart.aria({ label: '这张图表展示的是不同城市的交易额对比情况。' });
+```
+
 ## View API
 
 > View 上的 api 同样适用于 Chart 上

src/chart/chart.ts

@@ -1,9 +1,10 @@
-import { debounce, each, isString, get } from '@antv/util';
+import { debounce, each, isString } from '@antv/util';
 import { ChartCfg } from '../interface';
 import { GROUP_Z_INDEX, VIEW_LIFE_CIRCLE } from '../constant';
 import { getEngine } from '../engine';
 import { createDom, getChartSize, removeDom, modifyCSS } from '../util/dom';
 import View from './view';
+import { AriaOption } from '../interface';
 
 /**
  * Chart 类，是使用 G2 进行绘图的入口。
@@ -103,6 +104,19 @@ export default class Chart extends View {
     });
   }
 
+  /**
+   * 设置 WAI-ARIA 无障碍标签。如何根据图形语法自动生成 arial 内容？
+   * @param ariaOption
+   */
+  public aria(ariaOption: AriaOption) {
+    const ATTR = 'aria-label';
+    if (ariaOption === false) {
+      this.ele.removeAttribute(ATTR);
+    } else {
+      this.ele.setAttribute(ATTR, ariaOption.label);
+    }
+  }
+
   /**
    * 改变图表大小，同时重新渲染。
    * @param width 图表宽度
@@ -129,6 +143,15 @@ export default class Chart extends View {
     return this;
   }
 
+  /**
+   * 清空图表，同时清除掉 aria 配置
+   */
+  public clear() {
+    super.clear();
+
+    this.aria(false);
+  }
+
   /**
    * 销毁图表，同时解绑事件，销毁创建的 G.Canvas 实例。
    * @returns void

src/interface.ts

@@ -70,6 +70,13 @@ export interface RangePoint {
   readonly y?: number | number[];
 }
 
+/**
+ * WAI-ARIA 无障碍标签配置
+ */
+export type AriaOption  = false | {
+  readonly label: string;
+}
+
 /** 用户数据经过图形映射处理后的数据结构 */
 export interface MappingDatum {
   /** 原始数据 */

tests/unit/chart/chart-aria-spec.ts

@@ -0,0 +1,39 @@
+import { Chart } from '../../../src';
+import { CITY_SALE } from '../../util/data';
+import { createDiv } from '../../util/dom';
+
+describe('Chart aria', () => {
+  const div = createDiv();
+
+  const chart = new Chart({
+    container: div,
+    autoFit: true,
+  });
+
+  chart.data(CITY_SALE);
+
+  chart.interval().position('city*sale').color('category').adjust('stack');
+
+  test('aria', () => {
+
+    const label = '不同城市按照产品类别的堆积柱形图。';
+
+    chart.aria({
+      label,
+    });
+
+    expect(chart.ele.getAttribute('aria-label')).toBe(label);
+
+    chart.aria(false);
+    expect(chart.ele.getAttribute('aria-label')).toBe(null);
+
+    chart.aria({
+      label,
+    });
+
+    chart.destroy();
+
+    expect(div.getAttribute('aria-label')).toBe(null);
+  });
+
+});