Skip to content

Commit

Permalink
docs: 添加pattern精选案例 (#2818)
Browse files Browse the repository at this point in the history
* test: 添加双轴图的单测和文档,并修改贴图的默认值

* docs: 添加pattern精选案例

* docs: 修改pattern的文档

Co-authored-by: 酥云 <lisuwen.lsw@antgroup.com>
  • Loading branch information
Angelii and 酥云 authored Aug 24, 2021
1 parent de2efd5 commit b87a9ba
Show file tree
Hide file tree
Showing 28 changed files with 1,046 additions and 168 deletions.
152 changes: 152 additions & 0 deletions __tests__/unit/plots/dual-axes/pattern-spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
import { DualAxes } from '../../../../src';
import { PV_DATA, UV_DATA } from '../../../data/pv-uv';
import { createDiv } from '../../../utils/dom';
import { MultipleData } from '../../../data/common';

describe('dual-axes: pattern', () => {
it('column pattern: obj', () => {
const dualAxes = new DualAxes(createDiv(), {
width: 400,
height: 500,
data: [PV_DATA, UV_DATA],
xField: 'date',
yField: ['pv', 'uv'],
geometryOptions: [
{
geometry: 'column',
pattern: {
type: 'dot',
},
},
{
geometry: 'line',
},
],
});

dualAxes.render();

const [leftView] = dualAxes.chart.views;
expect(leftView.geometries[0].elements[0].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[1].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[2].shape.attr('fill') instanceof CanvasPattern).toEqual(true);

dualAxes.destroy();
});

it('column pattern: callback', () => {
const dualAxes = new DualAxes(createDiv(), {
width: 400,
height: 500,
data: [PV_DATA, UV_DATA],
xField: 'date',
yField: ['pv', 'uv'],
geometryOptions: [
{
geometry: 'column',
pattern: ({ pv }) => {
if (pv > 630000) {
return { type: 'line' };
}
},
},
{
geometry: 'line',
},
],
});

dualAxes.render();

const [leftView] = dualAxes.chart.views;
expect(leftView.geometries[0].elements[3].shape.attr('fill') instanceof CanvasPattern).toEqual(false);
expect(leftView.geometries[0].elements[4].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[5].shape.attr('fill') instanceof CanvasPattern).toEqual(false);

dualAxes.destroy();
});

it('stack column pattern: obj', () => {
const dualAxes = new DualAxes(createDiv('stack column and stack line'), {
height: 500,
data: [MultipleData, MultipleData],
xField: 'month',
yField: ['value', 'value'],
geometryOptions: [
{
geometry: 'column',
isGroup: true,
isStack: true,
seriesField: 'type',
groupField: 'name',
pattern: {
type: 'line',
},
},
{
geometry: 'line',
seriesField: 'type',
smooth: true,
isGroup: true,
isStack: true,
groupField: 'name',
},
],
tooltip: false,
});

dualAxes.render();

const [leftView] = dualAxes.chart.views;
expect(leftView.geometries[0].elements[0].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[1].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[2].shape.attr('fill') instanceof CanvasPattern).toEqual(true);

dualAxes.destroy();
});

it('stack column pattern: callback', () => {
const dualAxes = new DualAxes(createDiv('stack column and stack line'), {
height: 500,
data: [MultipleData, MultipleData],
xField: 'month',
yField: ['value', 'value'],
geometryOptions: [
{
geometry: 'column',
isGroup: true,
isStack: true,
seriesField: 'type',
groupField: 'name',
pattern: ({ type }) => {
if (type === '语文') {
return {
type: 'line',
};
}
},
},
{
geometry: 'line',
seriesField: 'type',
smooth: true,
isGroup: true,
isStack: true,
groupField: 'name',
},
],
tooltip: false,
});

dualAxes.render();

const [leftView] = dualAxes.chart.views;
expect(leftView.geometries[0].elements[0].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[1].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[2].shape.attr('fill') instanceof CanvasPattern).toEqual(true);
expect(leftView.geometries[0].elements[3].shape.attr('fill') instanceof CanvasPattern).toEqual(false);
expect(leftView.geometries[0].elements[4].shape.attr('fill') instanceof CanvasPattern).toEqual(false);

dualAxes.destroy();
});
});
36 changes: 35 additions & 1 deletion docs/api/pattern.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,38 @@ title: Pattern
order: 12
---

`markdown:docs/api/pattern.zh.md`
### Introduction
We can set patterns for geometries.
- We provide the default, high contrast patterns: dot, line, and square. For charts with poor color differentiation, pattern can be used as an "intuitive, visual classification attribute" to distinguish each item, making it color-blind friendly.
- add grouping for color: Pattern can help to expand the classification of colors when there are not enough harmonious colors, or when the color has a small proportion, the distinction is not obvious.
- Subdivision and grouping with color: We can use pattern as a "group", and the color as sub classification in this group.
- Grouping as degree: The size of a circle or square, the thickness of a line can indicate "degree".
- Highlight key points and enrich expression: Pattern not only has a "good-looking" skin, but also can highlight a certain items for storytelling.

### Use pattern in G2Plot

G2Plot with built-in `'dot' | 'line' | 'square'` several patterns, the pattern inherits the current element's fill color by default.

<playground path="plugin/pattern/demo/pie-pattern.ts" rid="pie-pattern"></playground>

Usage for scenes:

- [Demo1](/zh/examples/plugin/pattern#legend-marker-with-pattern): Set pattern for legend marker
- [Demo2](/zh/examples/plugin/pattern#bar-pattern): Set pattern with callback for each geometry


<!-- 补充 案例说明 和 案例 -->

### API

`markdown:docs/common/pattern.en.md`

### Attention

Please note the use of pattern, which currently has some limitations.

1. Pattern is not supported in the `svg` rendering mode.
2. Pattern inherits the fill color of element by default, but does not support gradient color for pattern fill color, i.e. when we needs gradient color for element, pattern background color cannot be inherited and needs to be specified manually. See: [Demo](/zh/examples/tiny/tiny-area#pattern)
3. Tooltip, the legend marker is still in plain color. For the legend marker, consider using a callback to set it, see:[Demo](/zh/examples/plugin/pattern#pie-pattern-callback)


8 changes: 6 additions & 2 deletions docs/api/pattern.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,12 @@ order: 12
---

### 介绍

使用 Pattern 可以很有用地对相似的项目进行分组,例如,假设您想要构建一个显示各种食物的饼图,您可以使用颜色比例尺为每种食物指定一种唯一的颜色,然后您可以对蔬菜/水果/肉类/进行分组,为每组使用类似的 pattern(同时保持颜色)。
pattern 是附着在图形上的贴图样式。
- 我们内置了默认的、区分度较高的三种贴图:点、线、方形。在颜色区分度不高的图表中,pattern 能够作为「直观的、视觉上的分类属性」来区分每个项目,对色盲人士友好。
- 扩充颜色分组:pattern 还可以作为颜色的「补充项」。遇到和谐的颜色「不够用」、颜色占比小「区分不明显」等情况,pattern 可以帮助颜色扩充分类。
- 结合颜色分组:我们可以用 pattern 作为「组」,然后用颜色在该组下进行细粒度的分类。
- 程度分组:圆形和方形的大小、线的粗细可以用来表示「程度」。
- 突出重点、丰富表现力:pattern 不仅有「好看」的皮囊,还可以作为讲故事的「点睛之笔」,高亮某个项目。

### 在 G2Plot 中使用 pattern

Expand Down
1 change: 1 addition & 0 deletions docs/api/plots/dual-axes.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ The graph corresponding to the column is configured as follows:
| columnStyle | _StyleAttr \| Function_ | Column style configuration[Column columnStyle](/en/docs/api/plots/column#columnstyle) | |
| label | _ContinueLegendLabelCfg_ | Column label [Column label](/en/docs/api/plots/column#label) |
| color | _string \| string[] \| Function_ | Specifies the color of the point [Column color](/en/docs/api/plots/column#color) |
| pattern | _object \| Function_ | Specifies the pattern of the column [Column pattern](/en/docs/api/plots/column#pattern) |
| groupField | _string_ | Split field, used to stack group histograms. Split field takes precedence over SeriesField. IsGroup: true will group by GroupField. | - |

### Plot Components
Expand Down
1 change: 1 addition & 0 deletions docs/api/plots/dual-axes.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ const data = [[{ time: '1991',value: 20 }], [{ time: '1992', count: 20 }]];
| columnStyle | _StyleAttr \| Function_ | 柱子样式配置,具体用法同[柱形图 columnStyle](/zh/docs/api/plots/column#columnstyle) | |
| label | _ContinueLegendLabelCfg_ | 柱形图 label,具体用法同[柱形图 label](/zh/docs/api/plots/column#label) |
| color | _string \| string[] \| Function_ | 指定点的颜色。具体用法同[柱形图 color](/zh/docs/api/plots/column#color) |
| pattern | _object \| Function_ | 柱子的贴图配置,具体用法同[柱形图 columnStyle](/zh/docs/api/plots/column#pattern) |
| groupField | _string_ | 拆分字段,用于堆叠+分组柱图,拆分优先级高于 seriesField,isGroup: true 时会根据 groupField 进行分组。 | - |

### 图表组件
Expand Down
10 changes: 5 additions & 5 deletions docs/common/pattern.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ Set the pattern style of the geometries.
- PatternOption: consists of `type` and `cfg`, `type` includes: `dot`, `line`, `square`, `cfg` is optional.
- Features: pattern will override the `style` of geometry (such as pieStyle, columnStyle, etc.).
- Usage: You can set a uniform pattern style for all geometries of the chart by using configuration (`PatternOption`) or `CanvasPattern` object, and a `callback` is provided to set the pattern for each geometry.
In addition, we provide `getCanvasPattern` function, pass in the PatternOption to create the pattern to modify the Legend, Tooltip Marker styles[Demo](/zh/examples/plugin/pattern#legend-marker-with-pattern)
In addition, we provide `getCanvasPattern` function, pass in the PatternOption to create the pattern to modify the Legend styles[Demo](/zh/examples/plugin/pattern#legend-marker-with-pattern)

The type of pattern is defined as follows:
```plain
Expand Down Expand Up @@ -71,20 +71,20 @@ Additional configuration for dotPattern

| Attribute | Type | Description |
| ------------- | --------------- | ---------------- |
| size | _number_ | The size of the dot, default: `4` |
| size | _number_ | The size of the dot, default: `6` |
| padding | _number_ | The distance between dots, default: `2` |
| isStagger | _boolean_ | Staggered dots. default: `true` |

Additional configuration for linePattern

| Attribute | Type | Description |
| ------------- | --------------- | ---------------- |
| spacing | _number_ | The distance between the two lines, default: `4` |
| spacing | _number_ | The distance between the two lines, default: `5` |

Additional configuration for squarePattern

| Attribute | Type | Description |
| ------------- | --------------- | ---------------- |
| size | _number_ | The size of the square, default: `5` |
| padding | _number_ | The distance between squares, default:`0` |
| size | _number_ | The size of the square, default: `6` |
| padding | _number_ | The distance between squares, default:`1` |
| isStagger | _boolean_ | Staggered squares. default:`true` |
10 changes: 5 additions & 5 deletions docs/common/pattern.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

- 配置项:由`type``cfg`组成,`type`目前包括三种类型:`dot``line``square``cfg`为可选项。
- 特点:`pattern`会覆盖当前图形设置的`style`样式(如 pieStyle、columnStyle 等)。
- 使用方式:可通过 配置项(PatternOption) 或传入 CanvasPattern 对象 的方式给图表的所有图形设置统一的贴图样式,还提供了 callback 的方式给对应的图形设置样式。此外,提供了 getCanvasPattern 方法传入 PatternOption 配置来创建 pattern,以修改 Legend、Tooltip Marker 样式[Demo](/zh/examples/plugin/pattern#legend-marker-with-pattern)
- 使用方式:可通过 配置项(PatternOption) 或传入 CanvasPattern 对象 的方式给图表的所有图形设置统一的贴图样式,还提供了 callback 的方式给对应的图形设置样式。此外,提供了 getCanvasPattern 方法传入 PatternOption 配置来创建 pattern,以修改 Legend 样式[Demo](/zh/examples/plugin/pattern#legend-marker-with-pattern)

pattern 的类型定义如下:

Expand Down Expand Up @@ -73,20 +73,20 @@ dotPattern 额外的 cfg 配置项

| 属性名 | 类型 | 介绍 |
| ------------- | --------------- | ---------------- |
| size | _number_ | 圆点的大小,默认为`4` |
| size | _number_ | 圆点的大小,默认为`6` |
| padding | _number_ | 圆点之间的间隔,默认为`2` |
| isStagger | _boolean_ | 圆点之间是否交错,默认为`true` |

linePattern 额外的 cfg 配置项

| 属性名 | 类型 | 介绍 |
| ------------- | --------------- | ---------------- |
| spacing | _number_ | 两条线之间的距离,默认为`4` |
| spacing | _number_ | 两条线之间的距离,默认为`5` |

squarePattern 额外的 cfg 配置项

| 属性名 | 类型 | 介绍 |
| ------------- | --------------- | ---------------- |
| size | _number_ | 矩形的大小,默认为`5` |
| padding | _number_ | 矩形之间的间隔,默认为`0` |
| size | _number_ | 矩形的大小,默认为`6` |
| padding | _number_ | 矩形之间的间隔,默认为`1` |
| isStagger | _boolean_ | 矩形之间是否交错,默认为`true` |
9 changes: 9 additions & 0 deletions examples/dual-axes/column-line/demo/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,15 @@
"en": "Slider with column line"
},
"screenshot": "https://gw.alipayobjects.com/zos/antfincdn/fxukGXuXfg/89ea37e5-e00d-4424-b75e-1aba3ff8b633.png"
},
{
"filename": "pattern.ts",
"title": {
"zh": "带贴图图案的柱线混合图表",
"en": "column line with pattern"
},
"new": true,
"screenshot": "https://gw.alipayobjects.com/zos/antfincdn/iMCSWEAapb/d19f59e0-788a-4945-8fbb-85b921a6e654.png"
}
]
}
81 changes: 81 additions & 0 deletions examples/plugin/pattern/demo/area-pattern.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
import { Area } from '@antv/g2plot';

const data = [
{ country: 'Asia', year: '1750', value: 502 },
{ country: 'Asia', year: '1800', value: 635 },
{ country: 'Asia', year: '1850', value: 809 },
{ country: 'Asia', year: '1900', value: 5268 },
{ country: 'Asia', year: '1950', value: 4400 },
{ country: 'Asia', year: '1999', value: 3634 },
{ country: 'Asia', year: '2050', value: 947 },
{ country: 'Africa', year: '1750', value: 106 },
{ country: 'Africa', year: '1800', value: 107 },
{ country: 'Africa', year: '1850', value: 111 },
{ country: 'Africa', year: '1900', value: 1766 },
{ country: 'Africa', year: '1950', value: 221 },
{ country: 'Africa', year: '1999', value: 767 },
{ country: 'Africa', year: '2050', value: 133 },
{ country: 'Europe', year: '1750', value: 163 },
{ country: 'Europe', year: '1800', value: 203 },
{ country: 'Europe', year: '1850', value: 276 },
{ country: 'Europe', year: '1900', value: 628 },
{ country: 'Europe', year: '1950', value: 547 },
{ country: 'Europe', year: '1999', value: 729 },
{ country: 'Europe', year: '2050', value: 408 },
{ country: 'Oceania', year: '1750', value: 200 },
{ country: 'Oceania', year: '1800', value: 200 },
{ country: 'Oceania', year: '1850', value: 200 },
{ country: 'Oceania', year: '1900', value: 460 },
{ country: 'Oceania', year: '1950', value: 230 },
{ country: 'Oceania', year: '1999', value: 300 },
{ country: 'Oceania', year: '2050', value: 300 },
];

const pattern = ({ country }) => {
if (country === 'Asia') {
return {
type: 'line',
cfg: {
lineWidth: 10,
strokeOpacity: 0.6,
},
};
} else if (country === 'Europe') {
return {
type: 'dot',
cfg: {
size: 10,
padding: 5,
fill: '#fff',
fillOpacity: 0.8,
},
};
}
};

const area = new Area('container', {
data,
xField: 'year',
yField: 'value',
seriesField: 'country',
color: ['#82d1de', '#cb302d', '#e3ca8c'],
areaStyle: {
fillOpacity: 0.7,
},
meta: {
year: {
nice: true,
range: [0, 1],
},
},
smooth: true,
yAxis: {
label: {
formatter: (value) => {
return value * 100;
},
},
},
pattern,
});
area.render();
Loading

0 comments on commit b87a9ba

Please sign in to comment.