docs(multi-view): 多图层图表支持 multi-plots 的 api 文档

antvis · Feb 4, 2021 · b2765bb · b2765bb
1 parent 1036ae8
commit b2765bb
Show file tree

Hide file tree

Showing 3 changed files with 261 additions and 121 deletions.
diff --git a/docs/api/multi-view.en.md b/docs/api/multi-view.en.md
@@ -9,20 +9,30 @@ order: 8
 
 ### View
 
+#### syncViewPadding ✨
+
+<description>**optional** _boolean_</description>
+
+是否同步子 view 的 padding 配置。传入 boolean 值，含义是：是否需要将子 View 的 padding 同步，如果设置同步，那么可以保证子 View 在 auto padding 的情况下，所有子 View 的图形能够完全重合，避免显示上的错位。
+
 #### views
 
-<description>**required** _IView[]_</description>
+<description>**optional** _IView[]_</description>
 
 Configuration of `views` is an array. Every view has its own data, geometries and geometry configuration.
-see more: [View Configuration](#viewconfiguration)
+see more: [IView](#iview)
 
-#### syncViewPadding ✨
+#### plots
 
-<description>**optional** _boolean_</description>
+<description>**可选** _IPlot[]_</description>
 
-是否同步子 view 的 padding 配置。传入 boolean 值，含义是：是否需要将子 View 的 padding 同步，如果设置同步，那么可以保证子 View 在 auto padding 的情况下，所有子 View 的图形能够完全重合，避免显示上的错位。
+每一个图层的配置，每一个 plot 也是一个图层，都包含自己的：数据、图形、图形配置.
 
-### View Configuration
+在 2.4.0 版本之后，我们提供了 `plots` 的配置项，你可以使用 plots 来代替 views 或者联合使用.
+
+<playground path="plugin/multi-view/demo/series-columns.ts" rid="multi-views-plots"></playground>
+
+### IView
 
 #### IView.region
 
@@ -221,3 +231,81 @@ The purpose of adjusting data is to make the graphics not obscure each other and
 <description>**optional** _object_</description>
 
 Style of different state.
+
+### IPlot
+
+#### IPlot.type
+
+<description>**required** _string_</description>
+
+plot 类型，通过传入指定 type 的 plot，可以在图层上渲染 G2Plot 内置的图表。
+
+目前开放的图表类型有以下类型：
+
+- **基础图表**：`'line' | 'pie' | 'column' | 'bar' | 'area' | 'gauge'`
+- **迷你图表**：`'tiny-line' | 'tiny-column' | 'tiny-area' | 'progress' | 'ring-progress'`
+
+#### IPlot.region
+
+<description>**optional** _object_</description>
+
+plot 所在图层(view)的布局范围，默认是占满全部。
+
+```ts
+// 示例：设置 plot 所在图层(view)的布局位置在上半部分
+region: {
+  start: { x: 0, y: 0 },
+  end: { x: 1, y: 0.5 },
+}
+```
+
+#### IPlot.options
+
+<description>**required** _object[]_</description>
+
+plot 的具体配置项。每个 plot 都有自己的图层容器设置（不包括：width, height）以及数据、字段、样式等配置。
+
+具体配置项见指定 plot 的 API 文档. 如：type='column'时，options 对应 ColumnOptions，见文档: [Column API](/en/docs/api/plots/column)
+
+<div class="sign">
+
+```ts
+type IPlot = {
+   type: 'line';
+   options: Omit<LineOptions, 'width' | 'height'>;
+} | {
+  type: 'pie',
+  options: Omit<PieOptions, 'width' | 'height'>;
+} | {
+  // ... 等等
+}
+```
+
+</div>
+
+**示例**：添加一个图层，引入 column plot 和 bar plot
+
+```ts
+plots: [
+  {
+    type: 'column',
+    region: { start: { x: 0, y: 0 }, end: { x: 0.48, y: 1 }},
+    options: {
+      data: [{ city: '广州', sales: 1024 }, { city: '杭州', sales: 724 }, { city: '深圳', sales: 1256 }],
+      xField: 'city',
+      yField: 'sales',
+      seriesField: 'city',
+    }
+  },
+  {
+    type: 'bar',
+    region: { start: { x: 0.52, y: 0 }, end: { x: 1, y: 1 }},
+    options: {
+      data: [{ city: '广州', sales: 1024 }, { city: '杭州', sales: 724 }, { city: '深圳', sales: 1256 }],
+      yField: 'city',
+      xField: 'sales',
+      seriesField: 'city',
+    }
+  }
+]
+```
diff --git a/docs/api/multi-view.zh.md b/docs/api/multi-view.zh.md
@@ -2,37 +2,39 @@
 title: 多图层图表
 order: 8
 ---
+
 ### 图表容器
 
 `markdown:docs/common/chart-options.zh.md`
 
-### 图层
+### 图层配置
 
 #### syncViewPadding ✨
 
-<description>**optional** _boolean_</description>
+<description>**可选** _boolean_</description>
 
 是否同步子 view 的 padding 配置。传入 boolean 值，含义是：是否需要将子 View 的 padding 同步，如果设置同步，那么可以保证子 View 在 auto padding 的情况下，所有子 View 的图形能够完全重合，避免显示上的错位。
 
 #### views
 
-<description>**optional** _IView[]_</description>
+<description>**可选** _IView[]_</description>
 
-每一个图层的配置，每个图层都包含自己的：数据、图形、图形配置。具体见 [图层配置](#图层配置)
+每一个图层的配置，每个图层都包含自己的：数据、图形、图形配置。具体见 [IView](#iview)
+#### plots
 
-在 2.4.0 版本之后，我们提供了 `plots` 的配置项，你可以使用 `plots` 来代替 `views`。每一个 plot 是一个图层，详细见: [#plots]
+<description>**可选** _IPlot[]_</description>
 
-#### plots ✨
+每一个图层的配置，每一个 plot 也是一个图层，都包含自己的：数据、图形、图形配置。
 
-<description>**optional** _IView[]_</description>
+在 2.4.0 版本之后，我们提供了 `plots` 的配置项，你可以使用 plots 来代替 views 或者联合使用。
 
-每一个图层的配置，每个图层都包含自己的：数据、图形、图形配置。具体见 [图层配置](#图层配置)
+<playground path="plugin/multi-view/demo/series-columns.ts" rid="multi-views-plots"></playground>
 
-### 图层配置
+### IView
 
 #### IView.region
 
-<description>**optional** _object_</description>
+<description>**可选** _object_</description>
 
 view 的布局范围，默认是占满全部。
 
@@ -58,11 +60,11 @@ region: {
 
 坐标系的配置，每一个 view 具有自己的坐标系。同一个 view 下的 geometries 共用一个坐标系。
 
-| 参数名  | 类型            | 可选值 ｜                                                |
-| ------- | --------------- | -------------------------------------------------------- |
-| type    | _string_        | `'polar' | 'theta' | 'rect' | 'cartesian' | 'helix'` |
-| cfg     | _CoordinateCfg_ |   CoordinateCfg 坐标系配置项，目前常用于极坐标    |
-| actions | _array object_  | 坐标系的变换配置，具体可以见 G2 坐标系[文档](https://g2.antv.vision/zh/docs/api/general/coordinate)
+| 参数名  | 类型            | 可选值 ｜                                                                                           |
+| ------- | --------------- | --------------------------------------------------------------------------------------------------- | ------- | ------ | ----------- | -------- |
+| type    | _string_        | `'polar'                                                                                            | 'theta' | 'rect' | 'cartesian' | 'helix'` |
+| cfg     | _CoordinateCfg_ | CoordinateCfg 坐标系配置项，目前常用于极坐标                                                        |
+| actions | _array object_  | 坐标系的变换配置，具体可以见 G2 坐标系[文档](https://g2.antv.vision/zh/docs/api/general/coordinate) |
 
 <div class="sign">
 
@@ -83,13 +85,13 @@ type CoordinateCfg = {
 
 #### IView.geometries
 
-<description>**optional** _array object_</description>
+<description>**可选** _array object_</description>
 
 view 上的图形 geometry 及映射配置，具体见[图形配置](#图形配置)
 
 #### IView.axes
 
-<description>**optional** _object | false_</description>
+<description>**可选** _object | false_</description>
 
 view 上的图形坐标轴配置，key 值对应 `xField` 和 `yField`， value 具体配置见：[Axis API](/zh/docs/api/components/axis)
 
@@ -105,13 +107,13 @@ view 上的图形坐标轴配置，key 值对应 `xField` 和 `yField`， value
 
 #### IView.annotations
 
-<description>**optional** _object[]_ </description>
+<description>**可选** _object[]_ </description>
 
 view 上的几何图形的图形标注配置。具体见：[Annotations API](/zh/docs/api/components/annotations)
 
 #### IView.interactions
 
-<description>**optional** _object[]_ </description>
+<description>**可选** _object[]_ </description>
 
 view 上的交互配置。具体见：[Interactions API](/zh/docs/api/options/interactions)
 
@@ -144,7 +146,7 @@ type MappingOptions = {
   readonly style?: StyleAttr;
   /** tooltip 映射 */
   readonly tooltip?: TooltipAttr;
-}
+};
 
 /** 颜色映射 */
 type ColorAttr = string | string[] | ((datum: Datum) => string);
@@ -162,49 +164,49 @@ type TooltipAttr = (datum: Datum) => { name: string; value: string | number };
 
 #### IGeometry.xField
 
-<description>**optional** _string_</description>
+<description>**可选** _string_</description>
 
 对应 x 轴字段。数据映射到几何图形 geometry 上时，最重要的通道是 `position` 通道。笛卡尔坐标系上的几何图形，通常是一维或二维的，对应位置视觉通道需要 `x`, `y` 两个（或一个）字段的值。
 
 #### IGeometry.yField
 
-<description>**optional** _string_</description>
+<description>**可选** _string_</description>
 
 对应 y 轴字段。数据映射到几何图形 geometry 上时，最重要的通道是 `position` 通道。笛卡尔坐标系上的几何图形，通常是一维或二维的，对应位置视觉通道需要 `x`, `y` 两个（或一个）字段的值。
 
 #### IGeometry.colorField
 
-<description>**optional** _string_</description>
+<description>**可选** _string_</description>
 
 对应颜色(color)映射字段。通过颜色视觉通道对数据进行分组。
 
 #### IGeometry.shapeField
 
-<description>**optional** _string_</description>
+<description>**可选** _string_</description>
 
 对应形状(shape)映射字段。通过不同的形状对数据进行分组。
 
 #### IGeometry.sizeField
 
-<description>**optional** _string_</description>
+<description>**可选** _string_</description>
 
 对应大小(size)映射字段。通过 size 字段，可以将数据按照 `sizeField` 对应的数据进行不同的大小映射。
 
 #### IGeometry.styleField
 
-<description>**optional** _string_</description>
+<description>**可选** _string_</description>
 
 style 映射字段。
 
 #### IGeometry.tooltipFields
 
-<description>**optional** _string[] | false_</description>
+<description>**可选** _string[] | false_</description>
 
 tooltip 映射字段。
 
 #### IGeometry.label
 
-<description>**optional** _object_</description>
+<description>**可选** _object_</description>
 
 label 映射通道，具体见 [Label API](/zh/docs/api/components/label)
 
@@ -213,17 +215,94 @@ label 映射通道，具体见 [Label API](/zh/docs/api/components/label)
 数据调整配置项。
 调整数据的目的是为了使得图形不互相遮挡，对数据的认识更加清晰，但是必须保证对数据的正确理解，更多信息可以查看 [数据调整 | G2](https://g2.antv.vision/zh/docs/manual/concepts/adjust)
 
-
 | 参数名       | 类型       | 描述            |
 | ------------ | ----------- | -------- |
 | type         | 'stack' \| 'dodge' \| 'jitter' \| 'symmetric' | 数据调整类型    |
 | marginRatio  | number                                        | 只对 'dodge' 生效，取 0 到 1 范围的值（相对于每个柱子宽度），用于控制一个分组中柱子之间的间距 |
 | dodgeBy      | string                                        | 只对 'dodge' 生效，声明以哪个数据字段为分组依据                                               |
 | reverseOrder | boolean                                       | 只对 'stack' 生效，用于控制是否对数据进行反序操作                                             |
 
-
 #### IGeometry.state
 
-<description>**optional** _object_</description>
+<description>**可选** _object_</description>
 
 不同状态的样式
+
+### IPlot
+
+#### IPlot.type
+
+<description>**必选** _string_</description>
+
+plot 类型，通过传入指定 type 的 plot，可以在图层上渲染 G2Plot 内置的图表。
+
+目前开放的图表类型有以下类型：
+
+- **基础图表**：`'line' | 'pie' | 'column' | 'bar' | 'area' | 'gauge'`
+- **迷你图表**：`'tiny-line' | 'tiny-column' | 'tiny-area' | 'progress' | 'ring-progress'`
+
+#### IPlot.region
+
+<description>**可选** _object_</description>
+
+plot 所在图层(view)的布局范围，默认是占满全部。
+
+```ts
+// 示例：设置 plot 所在图层(view)的布局位置在上半部分
+region: {
+  start: { x: 0, y: 0 },
+  end: { x: 1, y: 0.5 },
+}
+```
+
+#### IPlot.options
+
+<description>**必选** _object[]_</description>
+
+plot 的具体配置项。每个 plot 都有自己的图层容器设置（不包括：width, height）以及数据、字段、样式等配置。
+
+具体配置项见指定 plot 的 API 文档。如：type='column'时，options 对应 ColumnOptions，见文档: [Column API](/zh/docs/api/plots/column)
+
+<div class="sign">
+
+```ts
+
+type IPlot = {
+   type: 'line';
+   options: Omit<LineOptions, 'width' | 'height'>;
+} | {
+  type: 'pie',
+  options: Omit<PieOptions, 'width' | 'height'>;
+} | {
+  // ... 等等
+}
+```
+
+</div>
+
+**示例**：添加一个图层，引入 column plot 和 bar plot
+
+```ts
+plots: [
+  {
+    type: 'column',
+    region: { start: { x: 0, y: 0 }, end: { x: 0.48, y: 1 }},
+    options: {
+      data: [{ city: '广州', sales: 1024 }, { city: '杭州', sales: 724 }, { city: '深圳', sales: 1256 }],
+      xField: 'city',
+      yField: 'sales',
+      seriesField: 'city',
+    }
+  },
+  {
+    type: 'bar',
+    region: { start: { x: 0.52, y: 0 }, end: { x: 1, y: 1 }},
+    options: {
+      data: [{ city: '广州', sales: 1024 }, { city: '杭州', sales: 724 }, { city: '深圳', sales: 1256 }],
+      yField: 'city',
+      xField: 'sales',
+      seriesField: 'city',
+    }
+  }
+]
+```