Skip to content

Commit

Permalink
docs: markdown format
Browse files Browse the repository at this point in the history
  • Loading branch information
@simaQ
simaQ committed Nov 15, 2019
1 parent d415a5a commit 2fd9220
Show file tree
Hide file tree
Showing 25 changed files with 389 additions and 423 deletions.
4 changes: 3 additions & 1 deletion CONTRIBUTING.md
View file
Expand Up @@ -129,9 +129,11 @@ In the release of every stable version, there will be a PM who has the following

- Confirm that performance test is passed and all issues in current Milestone are either closed or can be delayed to later versions.
- Open a new [Release Proposal MR], and write `History` as [node CHANGELOG]. Don't forget to correct content in documentation which is related to the releasing version. Commits can be generated automatically.
```

```bash
$ npm run commits
```

- Nominate PM for next stable version.

[semver] {: http:// semver.org/lang/zh-CN/
Expand Down
10 changes: 6 additions & 4 deletions CONTRIBUTING.zh-CN.md
View file
Expand Up @@ -7,7 +7,7 @@

- 请确定 issue 的类型。
- 请避免提交重复的 issue，在提交之前搜索现有的 issue。
- 在标签(分类参考**标签分类**), 标题 或者内容中体现明确的意图。
- 在标签（分类参考**标签分类**), 标题 或者内容中体现明确的意图。

随后 AntV 负责人会确认 issue 意图，更新合适的标签，关联 milestone，指派开发者。

Expand Down Expand Up @@ -85,7 +85,7 @@ $ git push origin branch-name

（5）footer

- **当有非兼容修改(Breaking Change)时必须在这里描述清楚**
- **当有非兼容修改 (Breaking Change) 时必须在这里描述清楚**
- 关联相关 issue，如 `Closes #1, Closes #2, #3`

示例
Expand Down Expand Up @@ -119,7 +119,7 @@ scale 基于 [semver] 语义化版本号进行发布。

### 发布策略

每个大版本都有一个发布经理管理（PM），他/她要做的事情
每个大版本都有一个发布经理管理（PM），他 / 她要做的事情

#### 准备工作：

Expand All @@ -129,16 +129,18 @@ scale 基于 [semver] 语义化版本号进行发布。

- 确认当前 Milestone 所有的 issue 都已关闭或可延期，完成性能测试。
- 发起一个新的 [Release Proposal MR]，按照 [node CHANGELOG] 进行 `History` 的编写，修正文档中与版本相关的内容，commits 可以自动生成。

```bash
$ npm run commits
```

- 指定下一个大版本的 PM。

#### 发布时：

- 将老的稳定版本（master）备份到以当前大版本为名字的分支上（例如 `1.x`），并设置 tag 为 {v}.x`（ v 为当前版本，例如`1.x`）。
- 发布新的稳定版本到 [npm]，并通知上层框架进行更新。
- `npm publish` 之前，请先阅读[『我是如何发布一个 npm 包的』]。
- `npm publish` 之前，请先阅读 [『我是如何发布一个 npm 包的』]。

[semver]: http://semver.org/lang/zh-CN/
[release proposal mr]: https://github.com/nodejs/node/pull/4181
Expand Down
103 changes: 50 additions & 53 deletions docs/manual/advanced/responsive.zh.md
View file
Expand Up @@ -5,31 +5,31 @@ order: 0

## 概述

响应式图表( responsive plot) 的目的是为了保证图表在任何数据和显示尺寸下的基本可读性问题。
响应式图表 (responsive plot) 的目的是为了保证图表在任何数据和显示尺寸下的基本可读性问题。

在现实的图表应用场景中，一个棘手的难题是图表的展示空间往往并不足够显示图表的数据量。我们的业务数据可能呈现多种形态，不一定是理想数据；同时图表的使用场景也经常是在一个上下文语境中，比如在文本中插入的图表、中台系统、dashboard 等，这决定了图表未必能获得理想的展示空间。

图表数据量和展示空间的矛盾会造成图表布局错乱、组件遮挡图形、组件各部分相互重叠等问题。下图是两个典型案例：

src as img as p="https://gw.alipayobjects.com/mdn/rms_d314dd/afts/img/A*y-k1Q4V7jXsAAAAAAAAAAABkARQnAQ" width="600">(/p> as )

这种非常典型的信息密度(information density)过载现象正是 G2Plot 响应式模块所要解决的问题 — 当信息密度过高时，对图表辅助信息进行抽稀，保证图表主要信息的展示，以使图表的信息密度达到合理平衡。
这种非常典型的信息密度 (information density) 过载现象正是 G2Plot 响应式模块所要解决的问题 — 当信息密度过高时，对图表辅助信息进行抽稀，保证图表主要信息的展示，以使图表的信息密度达到合理平衡。

这种非常典型的信息密度(information density)过载现象正是 G2Plot 响应式模块所要解决的问题 — 当信息密度过高时，对图表辅助信息进行抽稀，保证图表主要信息的展示，以使图表的信息密度达到合理平衡。
这种非常典型的信息密度 (information density) 过载现象正是 G2Plot 响应式模块所要解决的问题 — 当信息密度过高时，对图表辅助信息进行抽稀，保证图表主要信息的展示，以使图表的信息密度达到合理平衡。

g2plot 响应式方案由三块组成： constraints（约束条件）、 rules（响应规则) 和 responsiveTheme（响应式主题）。基本思路是：首先定义图表合理信息密度的衡量标准(constraints)，然后去判断图表各组成部分是否满足该标准，如果不满足标准，则对图表应用响应规则(rules）。这个过程是 iterative 的，如果不满足约束条件，响应规则会被依次执行下去。
g2plot 响应式方案由三块组成：constraints（约束条件）、rules（响应规则） 和 responsiveTheme（响应式主题）。基本思路是：首先定义图表合理信息密度的衡量标准 (constraints)，然后去判断图表各组成部分是否满足该标准，如果不满足标准，则对图表应用响应规则 (rules）。这个过程是 iterative 的，如果不满足约束条件，响应规则会被依次执行下去。

一个约束条件(constraint)对应一组响应规则(rules)，多个约束组构成一个完整的响应式方案 — resonsiveTheme。
一个约束条件 (constraint) 对应一组响应规则 (rules)，多个约束组构成一个完整的响应式方案 — resonsiveTheme。

src as img as p="https://gw.alipayobjects.com/mdn/rms_d314dd/afts/img/A*L6qZRrqCOLwAAAAAAAAAAABkARQnAQ" width="600">(/p> as )

## Constraint （约束条件）

可以将 constraint（约束条件) 理解为一个判断方法，定义某图表组成部分的信息密度衡量标准，并判断该部分是否符合该标准。
可以将 constraint（约束条件） 理解为一个判断方法，定义某图表组成部分的信息密度衡量标准，并判断该部分是否符合该标准。

下面的例子中声明了一个 axis（坐标轴）的约束条件，该条件判断坐标轴 label 之间的间距是否大于 4 像素。

```
```js
axis: {
constraint:{
name: 'elementDist',
Expand Down Expand Up @@ -70,14 +70,13 @@ g2plot 内置了一套常用的 constraint library，目前响应式模块还在

g2plot 允许用户注册自己的约束条件，允许覆盖现有约束库中的条件。

```
function myConstraint(parameters,cfg?){
}
```js
function myConstraint(parameters, cfg?) {}

plot.registerConstraint(name,{
type:'padding',
plot.registerConstraint(name, {
type: 'padding',
usage: 'compare',
method: myConstraint
method: myConstraint,
});
```
Expand All @@ -89,30 +88,30 @@ plot.registerConstraint(name,{
g2plot 内置了一套常用的 rule library，目前响应式模块还在试验和打磨阶段，该库将会持续更新：
| rule name | option | intro |
| ------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| textWrapper | lineNumber: Number | 文本折行，可设置每行字数或折几行 |
| textRotation | degree: Number | 文本旋转，可设置旋转角度 |
| textAbbrevaite | abbreviateBy: string | 文本省略，可设置省略头部、尾部或中间 |
| textHide | | 文本消失 |
| digitAbbraviate | unit: 'k'  |  'm'  |  'b'  |  't'  |  'auto'<br />decimal: number<br />formatter: Function | 数字省略，可设置格式化单位、保留小数点数，或自定义一个 formatter<br />如不设置格式化单位，则会自动应用 k - m - b- t 规则 |
| dateTimeStringAbbraviate | keep: any[] | 时间文本周期显示，可设置保头保尾或保留任意一 index |
| textAbbraviate | abbreviateBy?: 'start'  |  'middle'  |  'end' | 文本省略，可设置省略头部、省略中间、省略尾部 |
| robustAbbraviate | unit: 'k'  |  'm'  |  'b'  |  't'  |  'auto'<br />decimal: number<br />formatter: Function<br />keep: any[] | 判断字符类型，应用 text / digit / dateTime abbreviate 方法 |
| nodesSampling | keep: array | 抽样显示，可设置保头保尾或任意一个 index |
| nodesSamplingByAbbraviate | | 配合 dateTimeAbbraviate 方法使用，抽样掉经过省略的文本，保留完整的文本。 |
| nodeSamplingByChange | | 根据数据间的变化进行抽样，保留变化较大的点 |
| rule name | option | intro |
| ------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| textWrapper | lineNumber: Number | 文本折行，可设置每行字数或折几行 |
| textRotation | degree: Number | 文本旋转，可设置旋转角度 |
| textAbbrevaite | abbreviateBy: string | 文本省略，可设置省略头部、尾部或中间 |
| textHide | | 文本消失 |
| digitAbbraviate | unit: 'k'  |  'm'  |  'b'  |  't'  |  'auto'<br />decimal: number<br />formatter: Function | 数字省略，可设置格式化单位、保留小数点数，或自定义一个 formatter<br />如不设置格式化单位，则会自动应用 k - m - b- t 规则 |
| dateTimeStringAbbraviate | keep: any[] | 时间文本周期显示，可设置保头保尾或保留任意一 index |
| textAbbraviate | abbreviateBy?: 'start'  |  'middle'  |  'end' | 文本省略，可设置省略头部、省略中间、省略尾部 |
| robustAbbraviate | unit: 'k'  |  'm'  |  'b'  |  't'  |  'auto'<br />decimal: number<br />formatter: Function<br />keep: any[] | 判断字符类型，应用 text / digit / dateTime abbreviate 方法 |
| nodesSampling | keep: array | 抽样显示，可设置保头保尾或任意一个 index |
| nodesSamplingByAbbraviate | | 配合 dateTimeAbbraviate 方法使用，抽样掉经过省略的文本，保留完整的文本。 |
| nodeSamplingByChange | | 根据数据间的变化进行抽样，保留变化较大的点 |
| nodeSamplingByState | state: {(/>    name: string,<br / as br)>    exp: string | function<br />} | 根据状态量进行抽样，保留符合状态量的 node |
| nodeJitter | | 元素在水平和垂直方向抖开 |
| nodeJitterUpward | | 元素向上抖开并拉线 |
| clearOverlapping | | 在一组元素中去除 overlap 的元素，当多个元素发生重叠时，只保留位于最高点的元素。此方法用于多折线数据点 label 的 overlapping。 |
| nodeJitter | | 元素在水平和垂直方向抖开 |
| nodeJitterUpward | | 元素向上抖开并拉线 |
| clearOverlapping | | 在一组元素中去除 overlap 的元素，当多个元素发生重叠时，只保留位于最高点的元素。此方法用于多折线数据点 label 的 overlapping。 |
### 注册自定义响应规则
g2plot 允许用户注册自己的响应规则，允许覆盖现有规则库中的规则。
```
function myRule(){}
```js
function myRule() {}
plot.registerResponsiveRule(name, myRule);
```
Expand All @@ -126,36 +125,34 @@ plot.registerResponsiveRule(name, myRule);
一个完整的 responsiveTheme 的结构按图表构成进行组织，定义了图表内各组件的约束条件和该条件的响应规则。
以柱状图为例，柱状图参与响应式的图表元素为图形(column)、坐标轴(axis)、图形标签(label)，它的 responsiveTheme 结构如下：
以柱状图为例，柱状图参与响应式的图表元素为图形 (column)、坐标轴 (axis)、图形标签 (label)，它的 responsiveTheme 结构如下：
```
```js
const responsiveTheme = {
axis:{
x:{
category:{
axis: {
x: {
category: {
constraints: [],
rules: []
}
rules: [],
},
},

y: {
linear:{
linear: {
constraints: [],
rules: []
}
}
rules: [],
},
},
},

label:{
constraints:[],
rules:[]
label: {
constraints: [],
rules: [],
},

column:{
constraints: []
}
column: {
constraints: [],
},
};
```
Expand All @@ -165,7 +162,7 @@ const responsiveTheme = {
调用一个 constraint 方法：
```
```js
// 调用elementDist约束条件，并声明元素最小间距为8
{
name: 'elementDist',
Expand All @@ -177,7 +174,7 @@ const responsiveTheme = {
调用一个 rule 方法：
```
```js
// 调用textAbbravaite响应规则，并声明省略文字的尾部
{
name: 'textAbbrevaite',
Expand All @@ -189,7 +186,7 @@ const responsiveTheme = {
组装：
```
```js
const lineTheme = {
label: {
constraints: [{
Expand Down

0 comments on commit 2fd9220

Please sign in to comment.