You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by ov...@apache.org on 2020/12/07 09:27:15 UTC
[incubator-echarts-doc] branch next updated (74449d7 -> f004ec2)
This is an automated email from the ASF dual-hosted git repository.
ovilia pushed a change to branch next
in repository https://gitbox.apache.org/repos/asf/incubator-echarts-doc.git.
from 74449d7 fix code in example
add 216a9c6 doc: aria doc (WIP)
new 8db0591 doc: aria decals
new f004ec2 Merge branch 'next' of github.com:apache/incubator-echarts-doc into next
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
en/option/component/aria.md | 274 ++++++++++++++++++++++++++++++--------------
zh/option/component/aria.md | 168 +++++++++++++++++++++------
2 files changed, 322 insertions(+), 120 deletions(-)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org
[incubator-echarts-doc] 02/02: Merge branch 'next' of
github.com:apache/incubator-echarts-doc into next
Posted by ov...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ovilia pushed a commit to branch next
in repository https://gitbox.apache.org/repos/asf/incubator-echarts-doc.git
commit f004ec27fd5a69b9dbe003114509ae6d12486540
Merge: 8db0591 74449d7
Author: Ovilia <zw...@gmail.com>
AuthorDate: Mon Dec 7 17:26:34 2020 +0800
Merge branch 'next' of github.com:apache/incubator-echarts-doc into next
en/changelog.md | 41 +++---
en/option/partial/parallel.md | 12 --
en/option/partial/text-style.md | 2 +-
en/option/partial/zr-graphic.md | 296 +++++++++++++++++++++++++++++++++++++++-
en/tutorial/dynamic-data.md | 4 +-
zh/changelog.md | 198 +++++++++++++++++++++++++++
zh/option/partial/parallel.md | 16 ---
zh/option/partial/text-style.md | 2 +-
zh/option/partial/zr-graphic.md | 286 +++++++++++++++++++++++++++++++++++++-
zh/tutorial/dynamic-data.md | 4 +-
10 files changed, 803 insertions(+), 58 deletions(-)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org
[incubator-echarts-doc] 01/02: doc: aria decals
Posted by ov...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ovilia pushed a commit to branch next
in repository https://gitbox.apache.org/repos/asf/incubator-echarts-doc.git
commit 8db05911f8e5521d3ebf15f43fe980d742e6e147
Author: Ovilia <zw...@gmail.com>
AuthorDate: Mon Dec 7 17:26:28 2020 +0800
doc: aria decals
---
en/option/component/aria.md | 274 ++++++++++++++++++++++++++++++--------------
zh/option/component/aria.md | 37 +++++-
2 files changed, 222 insertions(+), 89 deletions(-)
diff --git a/en/option/component/aria.md b/en/option/component/aria.md
index 09e5aa1..b1f28a5 100644
--- a/en/option/component/aria.md
+++ b/en/option/component/aria.md
@@ -3,33 +3,43 @@
# aria(*)
-W3C defined the Accessible Rich Internet Applications Suite ([WAI-ARIA](https://www.w3.org/WAI/intro/aria)) to make Web content and Web applications more accessible to the disabled. From ECharts 4.0, we support ARIA by generating description for charts automatically.
+The W3C has developed the [WAI-ARIA](https://www.w3.org/WAI/intro/aria), the Accessible Rich Internet Applications Suite, which is dedicated to making web content and web applications accessible. Apache ECharts 4 complies with this specification by supporting the automatic generation of intelligent descriptions based on chart configuration items, allowing blind people to understand the chart content with the help of a reading device, making the chart accessible to a wider audience. In ad [...]
-By default, ARIA is disabled. To enable it, you should set [aria.show](~aria.show) to be `true`. After enabling, it will generate descriptions based on charts, series, data, and so on. Users may change the generated description.
+It is turned off by default and needs to be turned on by setting [aria.enabled](~aria.enabled) to `true`.
-**For example:**
+## enabled(boolean) = false
-For config:
+Whether or not aria is turned on. If not, the `label` or `decal` effect is not applied.
+
+## label(Object)
+
+If [aria.enabled](~aria.enabled) is set to `true`, `label` is enabled by default. When enabled, the description of the chart will be automatically and intelligently generated based on the chart, data, title, etc. Users can also modify the description through the configuration item.
+
+**Example:**
```js
option = {
aria: {
- show: true
+ // The following lines can be omitted because label.enabled defaults to true.
+ // label: {
+ // enabled: true
+ // },
+ enabled: true
},
title: {
- text: 'Source of user access to a site',
+ text: 'User access sources for a site',
x: 'center'
},
series: [
{
- Name: 'access source',
+ name: 'access source',
type: 'pie',
data: [
- { value: 335, name: 'direct access' },
- { value: 310, name: 'mail marketing' },
- { value: 234, name: 'union ad' },
- { value: 135, name: 'video ad' },
- { value: 1548, name: 'search engine' }
+ { value: 335, name: 'Direct Access' },
+ { value: 310, name: 'Email Marketing' },
+ { value: 234, name: 'Affiliate Ads' },
+ { value: 135, name: 'Video Ads' },
+ { value: 1548, name: 'Search Engine' }
]
}
]
@@ -38,146 +48,240 @@ option = {
~[700x300](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
-There should be an `aria-label` attribute on the chart DOM, which can help the disabled understand the content of charts with the help of certain devices. The value of the label is:
+On the generated chart DOM, there is an `aria-label` attribute that allows the blind to understand the chart with the help of a reading device. Its value is.
-```
-This is a chart of "Source of user access to a site." The chart type is a pie chart that indicates the source of the visit. The data is - direct access data is 335, mail marketing data is 310, union ad data is 234, video ad data is 135, search engine data is 1548.
-```
+> This is a chart of "Source of user access to a site." The chart type is a pie chart that indicates the source of the visit. The data is - direct access data is 335, mail marketing data is 310, union ad data is 234, video ad data is 135, search engine data is 1548.
+
+The basic process for generating the description is that if [aria.enabled](~aria.enabled) is set to `true` (not the default) and [aria.label.enabled](~aria.label.enabled) is set to `true` (the default), then the accessibility description is generated. Otherwise it is not generated. If [aria.label.description](~aria.description) is defined, it is used as the full description of the chart, otherwise the description is generated according to the template stitching. We provide a default algo [...]
+
+When using template stitching, the decision to use [aria.label.general.withTitle](~aria.general.withTitle) or [aria.label.general. withoutTitle](~aria.label.general. withoutTitle) is based on the existence of [title.text](~title.text) or [aria.label.general. withoutTitle](~aria.general. withoutTitle). withoutTitle](~aria.general.withoutTitle) as a global description. The `aria.label.general.withTitle` configuration item includes the template variable `'{title}'`, which will be replaced w [...]
+
+After piecing the title, the description of the series ([aria.series](~aria.series)), and the description of the data for each series ([aria.data](~aria.data)) are pieced in turn. Again, each template may include template variables to replace the actual values.
+
+The complete description generation process is.
+
+
+
+### enabled(boolean) = true
+
+Whether or not to enable label generation for accessibility. When enabled, the attribute `aria-label` will be generated.
+
+### description(string) = null
+
+By default, an algorithm is used to automatically generate a chart description, but if you want to fully customize it, you can set this value to a description. If it is set to ``This is a chart showing price movements''`, then the value of the `aria-label` attribute is the string.
+
+This configuration item is often used to display text that specifies a general description of the chart, when displaying individual data does not show the contents of the chart. For example, if the chart is a map with a large number of scattered points, the default algorithm can only show the locations of the data points and cannot convey the author's intent as a whole. In this case, you can specify `description` as what the author wants to say.
+
+### general(Object)
+
+For the overall description of the chart.
+
+#### withTitle(string) = 'This is a chart about "{title}".'
+
+If the chart exists [title.text](~title.text), then `withTitle` is used. This includes the template variable.
+
+- `{title}`: will be replaced with [title.text](~title.text) of the chart.
+
+#### withoutTitle(string) = 'This is a chart,'
+
+If the chart does not have [title.text](~title.text), then `withoutTitle` is used.
+
+### series(Object)
+
+series-related configuration items.
+
+#### maxCount(number) = 10
+
+The maximum number of series in the description.
-The default language is in Chinese, but you can configure it with templates. The following document shows how to do it.
+#### single(Object)
-## show(boolean) = false
+The description used when the chart contains only one series.
-Whether to enable ARIA. When enabled, there should be an `aria-label` label.
+##### prefix(string) = ''
-## description(string) = null
+Holistic descriptions for all series are shown before each series description. This includes template variables.
-By default, the description is generated by our algorithm based on charts. If user wants to set their own description, `description` should be set to the whole description.
+- `{seriesCount}`: will be replaced with the number of series, where it is always 1.
-This is useful when single data values cannot represent what the chart means. For example, if the chart is a map containing many scatter points. Default description can only show the data, but the users may find it hard to interpret. In this case, `description` should be set to describe the meaning of chart.
+##### withName(string) = 'The chart type is {seriesType}, which means {seriesName}.'
-## general(Object)
+This description is used if the series has the `name` attribute. This includes the template variable.
-General description of chart.
+- `{seriesName}`: will be replaced with `name` of the series.
+- `{seriesType}`: the name of the type that will be replaced with the series, e.g. ``Histogram''`, ``Line Chart''`, etc.''.
-### withTitle(string) = 'This is a chart about "{title}".'
+##### withoutName(string) = 'The chart type is {seriesType}.'
-If [title.text](~title.text) exists, then this is used. Template variable:
+This description is used if the series has no `name` attribute. This includes the template variable.
-- `{title}`: will be replaced by [title.text](~title.text).
+- `{seriesType}`: the name of the type that will be replaced with the series, e.g. ``Histogram''`, ``Line Chart''` and so on.
-### withoutTitle(string) = 'This is a chart'
+#### multiple(Object)
-If [title.text](~title.text) does not exist, then this is used.
+Description to use when the chart contains only multiple series.
-## series(Object)
+##### prefix(string) = 'It consists of {seriesCount} of chart series.'
-Series-related configures.
+A holistic description for all series is displayed before each series description. This includes the template variable.
-### maxCount(number) = 10
+- `{seriesCount}`: will be replaced with the number of series.
-Maximum series number.
+##### withName(string) = 'The chart type is {seriesType}, which means {seriesName}.'
-### single(Object)
+This description is used if the series has the `name` attribute. This includes the template variable.
-Description used when there is only one chart.
+- `{seriesName}`: will be replaced with `name` of the series.
+- `{seriesType}`: the name of the type that will be replaced with the series, e.g. ``Histogram''`, ``Line Chart''`, etc.''.
-#### prefix(string) = ''
+##### withoutName(string) = 'The chart type is {seriesType}.'
-General description for all series. This displays before all series descriptions. Template variable:
+This description is used if the series has no `name` attribute. This includes the template variable.
-- `{seriesCount}`: will be replaced by series count, which is 1.
+- `{seriesType}`: the name of the type that will be replaced with the name of the series, e.g. ``Histogram'`, ``Line Chart'` and so on.
-#### withName(string) = 'The chart type is {seriesType}, which means {seriesName}. '
+##### separator(Object)
-If chart contains `name` attribute, then this is used. Template variable:
+The separator between the series and the description of the series.
-- `{seriesName}`: will be replaced by the series `name`;
-- `{seriesType}`: will be replaced by the series type name.
+###### middle(string) = ';'
-#### withoutName(string) = 'The chart type is {seriesType}.'
+Except for the separator after the last series.
-If chart doesn't contain `name` attribute, then this is used. Template variable:
+###### end(string) = '.'
-- `{seriesType}`: will be replaced by series type name.
+Delimiter after the last series.
-### multiple(Object)
+### data(Object)
-Description used when there are more than one chart.
+Data-related configuration items.
-#### prefix(string) = 'It consists of {seriesCount} chart series. '
+#### maxCount(number) = 10
-General description for all series. This displays before all series descriptions. Template variable:
+The maximum number of data occurrences per series in the description.
-- `{seriesCount}`: will be replaced by series count.
+#### allData(string) = 'whose data is --'
-#### withName(string) = 'The chart type is {seriesType}, which means {seriesName}. '
+Description to be used when all data is displayed. This item **doesn't** make all the data displayed. It can be achieved by setting [aria.data.maxCount](~aria.data.maxCount) to `Number.MAX_VALUE`.
-If series contains `name` attribute, then this is used. Template variable:
+#### partialData(string) = 'where the first {displayCnt} term is --'
-- `{seriesName}`: will be replaced by series `name`;
-- `{seriesType}`: will be replaced by series type name.
+Descriptions used when only partial data is displayed. This includes template variables.
-#### withoutName(string) = 'The chart type is {seriesType}.'
+- `{displayCnt}`: the number of data that will be replaced with the number of displays.
-If series doesn't contain `name` attribute, then this is used. Template variable:
+#### withName(string) = 'The data for {name} is {value}'
-- `{seriesType}`: will be replaced by series type name.
+This description is used if the data has the `name` attribute. This includes the template variable.
+
+- `{name}`: `name` that will be replaced with the data.
+- `{value}`: the value that will be replaced with the data.
+
+#### withoutName(string) = '{value}'
+
+This description is used if the data does not have the `name` attribute. This includes the template variable.
+
+- `{value}`: the value that will be replaced with the data.
#### separator(Object)
-Separators between series and series.
+The separator between data and data description.
+
+##### middle(string) = ','
+
+The delimiter of the data except the last one.
+
+##### end(string) = ''
+
+The delimiter after the last data.
+
+Note that usually the last series is followed by the series `separator.end`, so `data.separator.end` is an empty string in most cases.
+
+
+
+## decal(Object)
+
+Decal patterns are added to series data as an additional hint other than colors to help differentiate the data. The following are some examples of decal options.
+
+~[700x300](${galleryViewPath}doc-example/aria-decal&edit=1&reset=1)
+
+### show(boolean) = false
+
+Whether or not to display the decal pattern is not shown by default. If you want to display the applique, you need to make sure [aria.enabled](~aria.enabled) and `aria.decal.show` are both `true`.
+
+```
+aria: {
+ enabled: true,
+ decal: {
+ show: true
+ }
+}
+```
+
+### decals(Object|Array)
+
+The style of the decal pattern. If it is an `Object` type, it means all data will have the same style, if it is an array, then each item in the array will have one style and the data will be looped through the array in order.
+
+#### symbol(string|string[]) = 'rect'
+
+The symbol type of the decal. If it is in the type of `string[]`, it means the symbols are used one by one.
+
+{{ use: partial-icon() }}
+
+#### symbolSize(number) = 1
+
+Range of values: `0` to `1`, representing the size of symbol relative to decal.
-##### middle(string) = '；'
+#### symbolKeepAspect(boolean) = true
-Separators other than the last one.
+Whether or not to keep the aspect ratio of the pattern.
-##### end(string) = '.'
+#### color(string) = 'rgba(0, 0, 0, 0.2)'
-The last series seperator.
+For the color of the decal pattern, it is recommended to use a translucent color, which can be superimposed on the color of the series itself.
-## data(Object)
+#### backgroundColor(string) = null
-Data-related configures.
+The background color of the decal will be over the color of the series itself, under the decal pattern.
-### maxCount(number) = 10
+#### dashArrayX(number | number[] | (number | number[])[]) = 5
-Maximum data number.
+The basic pattern of the decal pattern is an infinite loop in the form of `Pattern - Blank - Pattern - Blank - Pattern - Blank` both horizontally and vertically, respectively. By setting the length of each pattern and blank, complex pattern effects can be achieved.
-### allData(string) = 'Its data is --'
+`dashArrayX` controls the horizontal pattern pattern. When its value is of type `number` or `number[]`, it is similar to [SVG stroke-dasharray](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray).
-Description used when all data is displayed. Note that this option will **not** set to display all data. If all data should be displayed, [aria.data.maxCount](~aria.data.maxCount) should be set to be `Number.MAX_VALUE`.
+- If it is of type `number`, it means that the pattern and the blank space are of this value respectively. For example, `5` means the pattern with width 5 is displayed first, then 5 pixels empty, then the pattern with width 5 is displayed...
-### partialData(string) = ''Where the first {displayCnt} entry is -''
+- In the case of `number[]` type, it means that the pattern and empty space are loops of an array of values. For example: `[5, 10, 2, 6]` means the pattern is 5 pixels wide, then 10 pixels empty, then the pattern is 2 pixels wide, then 6 pixels empty, then the pattern is 5 pixels wide...
-Description used when only part of data is displayed. Template variable:
+- If of type `(number | number[])[]`, it means that each row is a loop with an array of values for the pattern and blank space. For example: `[10, [2, 5]]` means that the first line will be 10 pixels by 10 pixels and empty space, the second line will be 2 pixels by 2 pixels and empty space, and the third line will be 10 pixels by 10 pixels and empty space...
-- `{displayCnt}`: number of data displayed.
+This interface can be better understood with the following examples.
-### withName(string) = '{name}'s data is {value}'
+~[700x300](${galleryViewPath}doc-example/aria-decal&edit=1&reset=1)
-If data contains `name` attribute, then this is used. Template variable:
+#### dashArrayY(number | number[]) = 5
-- `{name}`: will be replaced by data `name`;
-- `{value}`: will be replaced by data value.
+The basic pattern of the decal pattern is an infinite loop in the form of `Pattern - Blank - Pattern - Blank - Pattern - Blank` both horizontally and vertically, respectively. By setting the length of each pattern and blank, complex pattern effects can be achieved.
-### withoutName(string) = '{value}'
+`dashArrayY` controls the horizontal pattern pattern. Similar to [SVG stroke-dasharray](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray).
-If data doesn't contain `name` attribute, then this is used. Template variable:
+- If it is a `number` type, it means the pattern and the blank are each of this value. For example, `5` means that the pattern with a height of 5 is displayed first, then 5 pixels empty, then the pattern with a height of 5 is displayed...
-- `{value}`: will be replaced by data value.
+- In the case of `number[]` type, it means that the pattern and empty space are loops of sequential array values. For example: `[5, 10, 2, 6]` means the pattern is 5 pixels high, then 10 pixels empty, then the pattern is 2 pixels high, then 6 pixels empty, then the pattern is 5 pixels high...
-### separator(Object)
+This interface can be better understood with the following examples.
-Separators between data and data.
+~[700x300](${galleryViewPath}doc-example/aria-decal&edit=1&reset=1)
-#### middle(string) = '，'
+#### rotation(number) = 0
-Separators other than the last one.
+The overall rotation angle (in radians) of the pattern, in the range from `-Math.
-#### end(string) = ''
+#### maxTileWidth(number) = 512
-The last data separator.
+The upper limit of the width of the generated pattern before it is duplicated. Usually this value is not necessary, but you can try to increase it if you notice discontinuous seams in the pattern when it repeats.
-Note that since series `separator.end` is used after the last data, `data.separator.end` is not needed in most cases.
+#### maxTileHeight(number) = 512
+The upper limit of the height of the generated pattern before it repeats. This value is usually not necessary to set, but you can try to increase it if you find that the pattern has discontinuous seams when it is repeated.
diff --git a/zh/option/component/aria.md b/zh/option/component/aria.md
index 280156a..71e6e1e 100644
--- a/zh/option/component/aria.md
+++ b/zh/option/component/aria.md
@@ -17,8 +17,6 @@ W3C 制定了无障碍富互联网应用规范集（[WAI-ARIA](https://www.w3.or
**例子：**
-对于配置项：
-
```js
option = {
aria: {
@@ -203,7 +201,9 @@ option = {
## decal(Object)
-为系列数据增加贴花纹理，作为颜色的辅助，帮助区分数据。
+为系列数据增加贴花纹理，作为颜色的辅助，帮助区分数据。下面是一些贴花图案的配置样例：
+
+~[700x300](${galleryViewPath}doc-example/aria-decal&edit=1&reset=1)
### show(boolean) = false
@@ -250,9 +250,38 @@ aria: {
`dashArrayX` 控制了横向的图案模式。当其值为 `number` 或 `number[]` 类型时，与 [SVG stroke-dasharray](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray) 类似。
-- 如果是 `number` 类型，表示图案和空白分别是这个值。如 `5` 表示先显示宽度为 5 的图案，然后空 5 像素，再然后显示宽度为 5 的团……
+- 如果是 `number` 类型，表示图案和空白分别是这个值。如 `5` 表示先显示宽度为 5 的图案，然后空 5 像素，再然后显示宽度为 5 的图案……
- 如果是 `number[]` 类型，则表示图案和空白依次为数组值的循环。如：`[5, 10, 2, 6]` 表示图案宽 5 像素，然后空 10 像素，然后图案宽 2 像素，然后空 6 像素，然后图案宽 5 像素……
- 如果是 `(number | number[])[]` 类型，表示每行的图案和空白依次为数组值的循环。如：`[10, [2, 5]]` 表示第一行以图案 10 像素空 10 像素循环，第二行以图案 2 像素空 5 像素循环，第三行以图案 10 像素空 10 像素循环……
+可以结合以下的例子理解本接口：
+
+~[700x300](${galleryViewPath}doc-example/aria-decal&edit=1&reset=1)
+
+#### dashArrayY(number | number[]) = 5
+
+贴花图案的基本模式是在横向和纵向上分别以`图案 - 空白 - 图案 - 空白 - 图案 - 空白`的形式无限循环。通过设置每个图案和空白的长度，可以实现复杂的图案效果。
+
+`dashArrayY` 控制了横向的图案模式。与 [SVG stroke-dasharray](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray) 类似。
+
+- 如果是 `number` 类型，表示图案和空白分别是这个值。如 `5` 表示先显示高度为 5 的图案，然后空 5 像素，再然后显示高度为 5 的图案……
+
+- 如果是 `number[]` 类型，则表示图案和空白依次为数组值的循环。如：`[5, 10, 2, 6]` 表示图案高 5 像素，然后空 10 像素，然后图案高 2 像素，然后空 6 像素，然后图案高 5 像素……
+
+可以结合以下的例子理解本接口：
+
+~[700x300](${galleryViewPath}doc-example/aria-decal&edit=1&reset=1)
+
+#### rotation(number) = 0
+
+图案的整体旋转角度（弧度制），取值范围从 `-Math.PI` 到 `Math.PI`。
+
+#### maxTileWidth(number) = 512
+
+生成的图案在未重复之前的宽度上限。通常不需要设置该值，当你发现图案在重复的时候出现不连续的接缝时，可以尝试提高该值。
+
+#### maxTileHeight(number) = 512
+
+生成的图案在未重复之前的高度上限。通常不需要设置该值，当你发现图案在重复的时候出现不连续的接缝时，可以尝试提高该值。
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org