feat: 迁移api文档

antvis · Nov 8, 2019 · 2975511 · 2975511
1 parent 78b6d4f
commit 2975511
Show file tree

Hide file tree

Showing 36 changed files with 5,736 additions and 18 deletions.
diff --git a/docs/api/animate.zh.md b/docs/api/animate.zh.md
@@ -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();
+```
+
diff --git a/docs/api/canvas.zh.md b/docs/api/canvas.zh.md
@@ -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` | 设置文本旋转的角度，单位为弧度 |
+
+