This is an automated email from the ASF dual-hosted git repository.
wangzx pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/echarts-handbook.git
The following commit(s) were added to refs/heads/master by this push:
new ac8a34b Clarify ARIA Customization Documentation
new a6642a7 Merge pull request #78 from zachary-svoboda-accesso/patch-1
ac8a34b is described below
commit ac8a34b0ee4b0a4c73e91ad702c594a0c8f27aa1
Author: Zachary Svoboda
<88666941+zachary-svoboda-acce...@users.noreply.github.com>
AuthorDate: Wed Dec 14 13:26:50 2022 -0500
Clarify ARIA Customization Documentation
- Correct grammatical and spelling errors
- Reorganize sections for clarity
---
contents/en/best-practices/aria.md | 29 ++++++++++++++---------------
1 file changed, 14 insertions(+), 15 deletions(-)
diff --git a/contents/en/best-practices/aria.md
b/contents/en/best-practices/aria.md
index 7a5a38c..da14f6b 100644
--- a/contents/en/best-practices/aria.md
+++ b/contents/en/best-practices/aria.md
@@ -2,15 +2,15 @@
[WAI-ARIA](https://www.w3.org/WAI/intro/aria), the Accessible Rich Internet
Applications Suite developed by W3C, defines a way to make Web content and Web
applications more accessible to people with disabilities.
-ECharts 4.0 complied with the specification, support generating description
based on the chart configuration intelligently, to allows people with visual
disabilities to understand the content of the chart with the help of reading
devices, to make the chart accessible to more people. Apache ECharts 5 supports
decal patterns that allow chart data to be distinguished by applique patterns
in addition to color, providing a better accessibility experience.
+ECharts 4.0 complied with the specification, supports generating a description
based on the chart configuration intelligently to allow people with visual
disabilities to understand the content of the chart with the help of reading
devices. Apache ECharts 5 supports decal patterns that allow chart data to be
distinguished by decal patterns in addition to color providing a better
experience to those with color-blindness.
-The Accessibility function was turn off by default, turn it on by define the
value of [aria.show](${optionPath}aria.show) as `true`.
+This accessibility function is turned off by default. It can be turned on by
setting the value of [aria.show](${optionPath}aria.show) to `true`.
## Chart Labels
-After setting [aria.show](${optionPath}aria.show) to be `true`, ECharts will
automatically generate a description of the chart according to the title,
chart, data, etc. Users can also change the description through the
configuration item.
+After setting [aria.show](${optionPath}aria.show) to `true`, ECharts will
automatically generate a description of the chart according to the title,
chart, data, etc. Users can also set description manually through the
configuration object.
-About the configuration item:
+Example configuration object:
```js
option = {
@@ -39,31 +39,30 @@ option = {
<md-example src="doc-example/aria-pie"></md-example>
-There will be an `aria-label` attribute on the Chart DOM. With the help of the
reading device, blind people can understand by hearing the following message:
+Enabling aria with add an `aria-label` attribute on the Chart HTML. Screen
readers use this attribute to describe the contect; this chart would have the
following description:
```
This is a chart about "Referrer of a User" with type Pie chart named Referrer.
The data is as follows: the data of Direct Visit is 335,the data of Mail
Marketing is 310,the data of Union Ad is 234,the data of Video Ad is 135,the
data of Search Engine is 1548.
```
-The default language will be used based on the language pack (default
Chinese), or you can customize the template using the configuration item.
+The configurated language will be used to build the description.
-### Overall Description Modification
+### Customizing Title
-For some charts, the default item description cannot show the info of the
whole chart. In the following scatter chart, the description generated by
default can include all the items, however, hearing info of hundreds of items
has no helps to understand the information the chart represented.
+The aria-label begins with the a general description. There are two templates,
[aria.general.withTitle](${optionPath}aria.general.withTitle) to be used when
[title.text](${optionPath}title.text) exists and
[aria.general.withoutTitle](${optionPath}aria.general.withoutTitle) for when
`title.text` is not defined.
-Under this circumstance, user can define the overall description by
[aria.description](${optionPath}aria.description) configuration item.
+In the `withTitle` template, the string `{title}` is replace with
[title.text](${optionPath}title.text). The template `This is a chart named
{title}` with a title of `Referrer of a User` would yield `This is a chart
named Referrer of a User`.
-### Customize Template Description
-Except for the overall description modify, we also provide the template of
generating the description. You can easily modify the description in fine-grain
level.
+### Customizing Description
-The basic process to generate a description: If
[aria.show](${optionPath}aria.show) is `true`, then generate the ARIA
description (otherwise, no.). If
[aria.description](${optionPath}aria.description) was defined, use it as the
overall description (otherwise, use the default to generate the description.).
We provide the basic algorithm, it needs to be changed only if the description
generated is not suitable. You can even use `aria.description` to cover the
default if needed.
+The description of the series and data are added after the title. For some
charts, the default item description cannot show all the information on the
chart. In the following scatter chart the description generated by default
includes all the items but it is not accessible due to the quantity of items
making the list too long to understand.
-While using the template to generate, firstly make sure whether the title
[title.text](${optionPath}title.text) exist to decide to use
[aria.general.withTitle](${optionPath}aria.general.withTitle) or
[aria.general.withoutTitle](${optionPath}aria.general.withoutTitle) as the
overall description. Configuration item `aria.general.withTitle` and
`'{title}'` will be replaced by the chart title. In another word, if
`aria.general.withTitle` was defined as `This is a chart about "{title}"`, and
[...]
+Under this circumstance, the description should be set with the
[aria.description](${optionPath}aria.description) property.
-After generating the title, ECharts will splice the description of the series
and data after the title part. Every part of the template can include template
variables, to be replaced by the actual value in the chart.
+### In-Depth Customization
-The complete process of generating description, please check: [ARIA
Document](${optionPath}aria.label).
+Every part of the aria-label can include template variables to be replaced by
the actual value in the chart. More information on the process of generating a
description is available in the API documentation:
[aria.label](${optionPath}aria.label).
## Decal Patterns
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@echarts.apache.org
For additional commands, e-mail: commits-h...@echarts.apache.org
