Skip to content

Commit

Permalink
feat: 迁移api文档
Browse files Browse the repository at this point in the history
  • Loading branch information
@zengyue
zengyue committed Nov 8, 2019
1 parent 78b6d4f commit 2975511
Show file tree
Hide file tree
Showing 36 changed files with 5,736 additions and 18 deletions.
183 changes: 183 additions & 0 deletions docs/api/animate.zh.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
---
title: 自定义 Animate
order: 7
---

## 动画注册机制

使用动画注册机制以达到动画函数的复用。使用方式如下：

```javascript
// 加载动画注册类
const Animate = require('@antv/f2/lib/animation/animate');
/**
* @param {String} animationName 动画名称，用户自定义即可
* @param {Function} animationFun 动画执行函数
**/
Animate.registerAnimation('animationName', animationFun); // 注册名为 animationName 的动画函数


// 使用上述注册的函数
chart.line().animate({
appear: {
animation: 'animationName' // 对应上述注册的动画函数名
}
})
```

## 自定义动画详解

F2 提供了完善的动画自定义机制，用户可对任意支持动画的图形元素定制不同状态下的动画行为，这里所说的状态即为 appear enter leave update 这四种动画类型。

在 F2 中执行的都是 [Shape(图形)](https://www.yuque.com/antv/f2/api-g-shape) 元素的动画，通过逐帧改变 shape 对象的图形属性来达到动画的效果，以下面圆的移动动画为例：![](https://gw.alipayobjects.com/zos/rmsportal/VsphIrCJSqpILogoZTiS.gif#width=)

这个动画的实现非常简单，由于动画的最终效果是将圆移至 B 点（画布坐标为 `{ x: 230, y: 50 }`），那么我们只需要通过调用 `shape.animate()` 方法指定 shape 的最终状态（图形属性）即可：

```javascript
// circle 初始画布位置为 x: 100, y: 100
circle.animate().to({
attrs: {
x: 230, // 最终的 x 坐标
y: 50 // 最终的 y 坐标
}, // 指定最终的图形属性
easing: 'linear', // 指定动画的缓动效果
duration: 1500 // 指定动画的执行时间
})
```

各类型 shape 的图形属性说明见 [graphic 图形 api](https://www.yuque.com/antv/f2/api-g-shape)。

F2 会为用户自定义的动画函数传递三个参数，按照顺序，分别为 `shape`、`animateCfg`、`coord`

```javascript
chart.line().animate({
appear: {
animation: (shape, animateCfg, coord) => {}
}
})
```

- `shape`，shape 对象，当前执行动画的主体


通过操作该 shape 对象的图形属性，即可进行动画的个性化定制。

shape 对象具体提供了以下属性来帮助用户进行操作：

| **属性名** | **获取方式** | **类型** | **解释** |
| --- | --- | --- | --- |
| `attrs` | shape.get('attrs') | Object | 获取 shape 全部的图形属性 |
| `className` | shape.get('className') | String | 获取当前 shape 的图形元素类型 |
| `origin` | shape.get('origin') | Object | 获取当前 shape 的绘制数据以及对应的原始数据记录 |
| `index` | shape.get('index') | Number | 获取当前 shape 的索引值，即顺序 |


另外图形属性的获取还可以通过调用 `shape.attr(name)` 方法来获取，更多 shape 对象的方法请阅读 [Shape API](https://www.yuque.com/antv/f2/api-g-shape#gdgvuz)。

另外对于处理 `update` 更新状态下的 shape 对象，我们还会提供一个 `cacheShape` 属性，该属性为一个 Object 对象，存储的是当前 shape 在上一个状态（数据变更前）的内容，以便于用户进行变更动画的定制，该属性包含的内容如下：

```javascript
{
animateCfg: {}, // 动画效果配置
attrs: {}, // 上一个状态的图形属性
className: "", // 图形元素名称
}
```

- `animateCfg`，Object 类型，动画的配置


该对象包含的内容如下：

```javascript
{
easing: , // 缓动函数配合
duration: , // 动画执行时间
delay: // 动画延迟时间
}
```

- `coord`，Coord 坐标系对象，表示当前 chart 的坐标系，该对象包含的属性详见 [Coordinate API](https://www.yuque.com/antv/f2/api-coordinate)


## 示例

下面的示例对柱状图的初始化出场动画（appear）进行了自定义：

![](https://gw.alipayobjects.com/zos/skylark/477ede4d-3496-42c9-97a6-f63195765dbd/2018/gif/2e743bec-fefb-46f1-96f3-cc0e965d4234.gif#width=)

```javascript
const { Chart, Animate, Util, G } = F2;
// 注册函数名为 delayScaleInY 的自定义动画，实现柱子 y 轴方向的放大效果
Animate.registerAnimation('delayScaleInY', function(shape, animateCfg) {
const box = shape.getBBox(); // 获取图形的包围盒
const origin = shape.get('origin'); // 获取当前 shape 的绘制数据
const points = origin.points; // 获取柱子的各个顶点
const centerX = (box.minX + box.maxX) / 2;
let centerY;
if (points[0].y - points[1].y <= 0) { // 当顶点在零点之下
centerY = box.maxY;
} else {
centerY = box.minY;
}

shape.transform([
[ 't', centerX, centerY ],
[ 's', 1, 0.1 ],
[ 't', -centerX, -centerY ]
]); // 进行矩阵变换，将 shape 的原始状态改变，y 方向缩小至 0.1 倍
const index = shape.get('index');
let delay = animateCfg.delay; // 获取动画配置
if (Util.isFunction(delay)) {
delay = animateCfg.delay(index); // 根据 shape 的索引设置不同的延迟时间
}
const easing = animateCfg.easing; // 获取动画配置

const matrix = shape.getMatrix(); // 获取当前矩阵
const endMatrix = G.Matrix.transform(matrix, [
[ 't', centerX, centerY ],
[ 's', 1, 10 ],
[ 't', -centerX, -centerY ]
]); // shape 最终状态下的矩阵

shape.animate().to({
attrs: {
matrix: endMatrix
},
delay,
easing,
duration: animateCfg.duration
}); // 执行动画
});

const data = [];
for (let i = 0; i < 50; i++) {
data.push({
x: i,
y: (Math.sin(i / 5) * (i / 5 - 10) + i / 6) * 5
});
}
const chart = new Chart({
id: 'mountNode',
width: 375,
height: 200,
pixelRatio: window.devicePixelRatio
});
chart.axis('x', false);
chart.legend(false);
chart.source(data);
chart.interval()
.position('x*y')
.color('y', '#4a657a-#308e92-#b1cfa5-#f5d69f-#f5898b-#ef5055')
.animate({ // 进行自定义的动画配置
appear: {
animation: 'delayScaleInY', // 使用上面注册过的动画 delayScaleInY，当然也可以使用回调函数
easing: 'elasticOut', // 定义缓动函数
delay(index) {
return index * 10;
} // 根据索引值为各个 shape 设置不同的动画延迟执行时间
}
});
chart.render();
```

86 changes: 86 additions & 0 deletions docs/api/canvas.zh.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
---
title: 绘图属性
order: 11
---

由于 F2 使用的是 canvas，绘制的所有图形都支持 canvas 的属性，本章列出常用的属性，详细信息参考[ canvas 属性](http://www.w3school.com.cn/tags/html_ref_canvas.asp)。

## 通用属性
| 属性名 | 描述 |
| --- | --- |
| `fill` | Canvas 2D API 使用内部方式描述颜色和样式的属性。默认值是 #000 （黑色）， 参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/fillStyle) |
| `fillStyle` | 同 `fill` |
| `fillOpacity` | 用于设置图形填充颜色的透明度。 |
| `stroke` | Canvas 2D API 描述画笔（绘制图形）颜色或者样式的属性。默认值是 #000 (black)，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/strokeStyle) |
| `strokeStyle` | 同 `stroke` |
| `strokeOpacity` | 用于设置边颜色的透明度。 |
| `shadowColor` | Canvas 2D API 描述阴影颜色的属性，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/shadowColor) |
| `shadowBlur` | Canvas 2D API 描述模糊效果程度的属性； 它既不对应像素值也不受当前转换矩阵的影响。 默认值是 0，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/shadowBlur) |
| `shadowOffsetX` | Canvas 2D API 描述阴影水平偏移距离的属性，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX) |
| `shadowOffsetY` | Canvas 2D API 描述阴影垂直偏移距离的属性，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY) |
| `globalOpacity` | Canvas 2D API 用来描述在canvas上绘图之前，设置图形和图片透明度的属性。 数值的范围从 0.0 （完全透明）到1.0 （完全不透明），参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/globalAlpha) |
| `opacity` | 同 `globalOpacity` |
| `globalCompositionOperation` | 该属性设置要在绘制新形状时应用的合成操作的类型，其中type是用于标识要使用的合成或混合模式操作的字符串，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation) |


## 渐变色

为了方便用户使用，F2 中默认提供对线性渐变、放射状/环形渐变两种渐变色的支持，定义方式如下：

- **线性渐变**

- ![](https://gw.alipayobjects.com/zos/rmsportal/ElBYXdsTZKFflacOBNtp.png#width=600)


> 说明：`l` 表示使用线性渐变，绿色的字体为可变量，由用户自己填写，由一个空格进行间隔。

```javascript
// example
// 使用渐变色描边，渐变角度为 0，渐变的起始点颜色 #ffffff，中点的渐变色为 #7ec2f3，结束的渐变色为 #1890ff
stroke: 'l(0) 0:#ffffff 0.5:#7ec2f3 1:#1890ff'
```

- **放射状/环形渐变**

- ![](https://gw.alipayobjects.com/zos/rmsportal/fBFocveoeRaeaCCPTaFo.png#width=600)


> 说明：`r` 表示使用放射状渐变，绿色的字体为可变量，由用户自己填写，开始圆的 x y r 值均为相对值，0 至 1 范围，'r(x,y,r)' 内不可留有空格，颜色之间由一个空格进行间隔。

```javascript
// example
// 使用渐变色填充，渐变起始圆的圆心坐标为被填充物体的包围盒中心点，半径为(包围盒对角线长度 / 2) 的 0.1 倍，渐变的起始点颜色 #ffffff，中点的渐变色为 #7ec2f3，结束的渐变色为 #1890ff
fill: 'r(0.5,0.5,0.1) 0:#ffffff 1:#1890ff'
```

**注意**

> 为了提升性能，未使用正则表达式解析渐变色字符串，请严格按照要求填写，除去色值区域，其余不要留有空格。

## 线条样式
| 属性名 | 描述 |
| --- | --- |
| `lineCap` | Canvas 2D API 指定如何绘制每一条线段末端的属性。有3个可能的值，分别是：`butt`, `round` and `square`。默认值是 butt，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/lineCap). |
| `lineJoin` | Canvas 2D API 用来设置2个长度不为0的相连部分（线段，圆弧，曲线）如何连接在一起的属性（长度为0的变形部分，其指定的末端和控制点在同一位置，会被忽略），参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/lineJoin). |
| `lineWidth` | Canvas 2D API 设置线段厚度的属性（即线段的宽度）。当获取属性值时，它可以返回当前的值（默认值是1.0 ）。 当给属性赋值时， 0、 负数、 Infinity 和 NaN 都会被忽略；除此之外，都会被赋予一个新值，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/lineWidth). |
| `miterLimit` | Canvas 2D API 设置斜接面限制比例的属性。 当获取属性值时， 会返回当前的值（默认值是10.0 ）。当给属性赋值时， 0、负数、 Infinity 和 NaN 都会被忽略；除此之外都会被赋予一个新值。，参见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/miterLimit). |
| `lineDash` | 设置线的虚线样式，可以指定一个数组。一组描述交替绘制线段和间距（坐标空间单位）长度的数字。 如果数组元素的数量是奇数， 数组的元素会被复制并重复。例如， [5, 15, 25] 会变成 [5, 15, 25, 5, 15, 25]。这个属性取决于浏览器是否支持 `setLineDash()` 函数，详情参考 [setLineDash](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/setLineDash)。 |


## 文本属性
| 属性名 | 描述 |
| --- | --- |
| `textAlign` | 设置文本内容的当前对齐方式, 支持的属性：center |
| `textBaseline` | 设置在绘制文本时使用的当前文本基线, 支持的属性:top |
| `fontStyle` | 规定字体样式。可能的值：'normal', 'italic', 'oblique' |
| `fontSize` | 规定字号，以像素计 |
| `fontFamily` | 规定字体系列 |
| `fontWeight` | 规定字体的粗细。可能的值：'normal', 'bold', 'bolder', 'lighter', '100', '200, '300', '400','500', '600', '700', '800', '900' |
| `fontVariant` | 规定字体变体。可能的值：'normal', 'small-caps' |
| `lineHeight` | 规定行高，以像素计 |
| `rotate` | 设置文本旋转的角度，单位为弧度 |


Loading

0 comments on commit 2975511

Please sign in to comment.