docs: update chart, data, get-started. add demo playground (#2885)

* docs: update chart, data, get-started. add demo playground * docs: update get started Co-authored-by: 羽熙 <yuxi.lx@antfin.com>
antvis · Oct 8, 2020 · 4da229b · 4da229b
1 parent 8d530b1
commit 4da229b
Show file tree

Hide file tree

Showing 8 changed files with 79 additions and 208 deletions.
diff --git a/docs/api/general/chart.zh.md b/docs/api/general/chart.zh.md
@@ -5,82 +5,12 @@ redirect_from:
   - /zh/docs/api
 ---
 
-创建 Chart 图表对象分四步。
+`markdown:docs/common/style.md`
 
-第一步：创建 Chart 对象。语法如下：
+创建 Chart 图表对象。
 
-```ts
-// highlight-start
-new Chart(params: ChartCfg) => chart
-// highlight-end
-
-new G2.Chart({
-  container: {string} | {HTMLDivElement},
-  width?: {number},
-  height?: {number},
-  padding?: {object} | {number} | {array},
-  background?: {object},
-  plotBackground?: {object},
-  forceFit?: {boolean},
-  animate?: {boolean},
-  pixelRatio?: {number},
-  data?: {array} | {DataSet.View},
-  theme?: {string} | {object},
-  renderer?: {string},
-});
-```
-
-创建一个 chart 实例，返回一个 Chart 对象，建议在单个容器上只初始化一个 Chart 实例。
-
-以柱状图为例：
-
-```ts
-// Step 1: 创建 Chart 对象
-const chart = new G2.Chart({
-  container: 'container', // 指定图表容器 ID
-  width: 600, // 指定图表宽度
-  height: 300, // 指定图表高度
-});
-```
-
-如果已经加载`Chart`,可以直接使用`Chart`声明：
-
-```ts
-import { Chart } from '@antv/g2';
-// Step 1: 创建 Chart 对象
-const chart = new Chart({
-  container: 'container', // 指定图表容器 ID
-  width: 600, // 指定图表宽度
-  height: 300, // 指定图表高度
-});
-```
-
-第二步 载入数据源
-
-```ts
-const data = [
-  { genre: 'Sports', sold: 275 },
-  { genre: 'Strategy', sold: 115 },
-  { genre: 'Action', sold: 120 },
-  { genre: 'Shooter', sold: 350 },
-  { genre: 'Other', sold: 150 },
-];
-// Step 2: 载入数据源
-chart.data(data);
-```
-
-第三步 创建图形语法，绘制柱状图
-
-```ts
-// Step 3：创建图形语法，绘制柱状图
-chart.interval().position('genre*sold').color('genre');
-```
-
-第四步 渲染图表
-
-```ts
-// Step 4: 渲染图表
-chart.render();
+```sign
+new Chart(params: ChartCfg) => View;
 ```
 
 ### ChartCfg.container
@@ -175,7 +105,7 @@ _default:_ `['tooltip', 'legend-filter', 'legend-active', 'continuous-filter', '
 
 <description> _ThemObject | string_ **optional**</description>
 
-<!-- TODO 写更详细的 theme 配置项 -->
+<!-- FIXME 写更详细的 theme 配置项 -->
 
 配置主题，目前 g2 默认有 `dark` 主题模式，如需要自定义配置，可以先通过 `registerTheme` 注册主题，再设置主题 key。
 

diff --git a/docs/api/general/data.zh.md b/docs/api/general/data.zh.md
@@ -3,66 +3,29 @@ title: 数据 - Data
 order: 1
 ---
 
-## 绑定数据
+### 绑定数据
 
-绑定数据调用方法为`chart.data`,之前的调用方法为 `source`，将在 V4.1 移除。_data_ 为 json 数组。
+绑定数据调用方法为`chart.data`，之前的调用方法为 `source`，将在 V4.1 移除。**参数格式只支持 json 数组**。
 
-```ts
-// highlight-start
-(field: Record<string, any>[]) => View;
-// highlight-end
-
-chart.data([
-  { city: '杭州', sale: 100 },
-  { city: '上海', sale: 110 },
-]);
-```
-
-chart 对象支持两种绑定数据的方式：
-
-第一种 data 属性传入
-
-```ts
-const chart = new G2.Chart({
-  container: 'container',
-  width: 600,
-  height: 300,
-  data: [
-    { city: '杭州', sale: 100 },
-    { city: '上海', sale: 110 },
-  ],
-});
+```sign
+chart.data(field: Record<string, any>[]) => View;
 ```
 
-第二种 调用 chart.data(data) 方法
-
 ```ts
-const data = [
+chart.data([
   { city: '杭州', sale: 100 },
   { city: '上海', sale: 110 },
-];
-const chart = new G2.Chart({
-  container: 'container',
-  width: 600,
-  height: 300,
-});
-chart.data(data);
+]);
 ```
 
-更多用法参考 [Demo](../../../examples/gallery/line#line1) 。
-
-## 如何更新数据
+### 更新数据
 
 G2 更新数据的方式有两种：
 
 1. 图表数据更新（**前后数据结构不发生变化**），更新后马上刷新图表。
 
-```typescript
-// highlight-start
-(field: Record<string, any>[]) => View;
-// highlight-end
-
-chart.changeData(data);
+```sign
+chart.changeData(data) => View
 ```
 
 2. 仅需要更新数据，但不需要马上更新图表，可以调用 `chart.data(data)`，然后在需要更新图表时调用 `chart.render()`
@@ -83,5 +46,3 @@ chart.data(newData); // 加载新数据
 chart.interval().position('x*y').color('z'); // 重新定义图形语法
 chart.render();
 ```
-
-更多信息查看 [数据](../../manual/tutorial/data) 。
diff --git a/docs/common/style.md b/docs/common/style.md
@@ -1,40 +1,11 @@
 <style>
-  .custom-api-docs h3 {
+  h3 {
     color: #873bf4;
     border-bottom: 1px solid #f0f0f0;
     margin: 1.2em 0 0.4em;
   }
 
-  .custom-api-docs p {
+  p {
     margin: 0.6em 0;
   }
-
-  .custom-api-docs p, 
-  .custom-api-docs li {
-    color: rgba(0, 0, 0, 0.68);
-  }
-
-  .custom-api-docs table, .custom-api-docs ul li {
-    color: rgba(0, 0, 0, 0.68);
-  }
-
-  .custom-api-docs table th, 
-  .custom-api-docs table td {
-    padding: 6px 12px;
-  }
-
-  .custom-api-docs table img {
-    max-height: 100px;
-  }
-
-  .custom-api-docs table td:first-child {
-    width: 20%;
-    font-weight: 500;
-    background: #fcfcfc;
-    color: rgba(0,0,0,.85);
-  }
-
-  .custom-api-docs pre[class*="language-"] {
-    background-color: rgba(0, 0, 0, 0.03);
-  }
 </style>
diff --git a/docs/manual/getting-started.zh.md b/docs/manual/getting-started.zh.md
@@ -53,68 +53,28 @@ const chart = new Chart({
 在绘图前我们需要为 G2 准备一个 DOM 容器：
 
 ```html
-<div id="c1"></div>
+<div id="container"></div>
 ```
 
 ### 2. 编写图表绘制代码
 
 创建 `div` 容器后，我们就可以进行简单的图表绘制：
 
-1. 创建 Chart 图表对象，指定图表所在的容器 ID、图表的宽高、边距等信息；
-1. 载入图表数据源；
-1. 使用图形语法进行图表的绘制；
-1. 渲染图表。
+1. `new Chart()` 创建 Chart 图表对象，指定图表所在的容器 id、图表的宽高、边距等信息；
+2. `chart.data()` 载入图表数据源；
+3. 使用图形语法进行图表的绘制；
+4. `chart.render()` 渲染图表。
 
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <title>柱状图</title>
-    <!-- 引入 G2 文件 -->
-    <script src="{{ url.g2 }}"></script>
-  </head>
-  <body>
-    <!-- 创建图表容器 -->
-    <div id="c1"></div>
-    <script>
-      const data = [
-        { genre: 'Sports', sold: 275 },
-        { genre: 'Strategy', sold: 115 },
-        { genre: 'Action', sold: 120 },
-        { genre: 'Shooter', sold: 350 },
-        { genre: 'Other', sold: 150 },
-      ];
-
-      // Step 1: 创建 Chart 对象
-      const chart = new G2.Chart({
-        container: 'c1', // 指定图表容器 ID
-        width: 600, // 指定图表宽度
-        height: 300, // 指定图表高度
-      });
-
-      // Step 2: 载入数据源
-      chart.data(data);
-
-      // Step 3：创建图形语法，绘制柱状图
-      chart.interval().position('genre*sold');
-
-      // Step 4: 渲染图表
-      chart.render();
-    </script>
-  </body>
-</html>
-```
-
-这样，你的第一个柱状图就绘制完成了!
+<!-- 先放这里，等 gatsby 版本升级后即可看到效果 -->
 
-<img src="https://gw.alipayobjects.com/mdn/rms_2274c3/afts/img/A*8qbLQb7A0loAAAAAAAAAAABkARQnAQ" style="width: 600px;">
+<playground path='column/basic/demo/basic.ts'></playground>
 
-你也可以进入 [G2 图表示例](../../examples/gallery)页面查看更多例子。
+你也可以进入 [G2 图表示例](zh/examples/gallery)页面查看更多例子。
 
 ## 在 React / Vue / Angular 中使用 G2
 
-基于 AntV 技术栈还有许多优秀的项目，在 React 环境下使用 G2，我们推荐使用 BizCharts 和 Viser-react！这两个产品都是基于 G2 的 React 版本封装，使用体验更符合 React 技术栈的习惯，他们都与 AntV 有着紧密的协同，他们很快也将同步开源和发布基于 G2 4.0 的版本。
+基于 AntV 技术栈还有许多优秀的项目，在 React 环境下使用 G2，我们推荐使用 Ant Design Charts，BizCharts 和 Viser。这三个产品都是基于 G2 的 React 版本封装，使用体验更符合 React 技术栈的习惯，他们都与 AntV 有着紧密的协同，他们很快也将同步开源和发布基于 G2 4.0 的版本。Viser 除了 React 外，还提供了 Vue 和 Angular 不同的分发版本。
 
+- Ant Design Charts 地址：[https://charts.ant.design](https://charts.ant.design)
 - BizCharts 地址：[https://bizcharts.net](https://bizcharts.net)
 - Viser 地址：[https://viserjs.github.io/](https://viserjs.github.io/)
diff --git a/examples/column/basic/demo/basic.ts b/examples/column/basic/demo/basic.ts
@@ -10,22 +10,28 @@ const data = [
   { year: '1960 年', sales: 38 },
   { year: '1962 年', sales: 38 },
 ];
+
+// step1: 创建 Chart 图表对象，指定图表所在的容器 ID、指定图表的宽高、边距等信息
 const chart = new Chart({
   container: 'container',
   autoFit: true,
   height: 500,
 });
 
+// step2: 载入图表数据源
 chart.data(data);
 chart.scale('sales', {
   nice: true,
 });
 
 chart.tooltip({
-  showMarkers: false
+  showMarkers: false,
 });
+
 chart.interaction('active-region');
 
+// step3: 使用图形语法进行图表的绘制
 chart.interval().position('year*sales');
 
+// step4: 渲染图表
 chart.render();
diff --git a/package.json b/package.json
@@ -54,7 +54,7 @@
   },
   "devDependencies": {
     "@antv/data-set": "^0.11.2",
-    "@antv/gatsby-theme-antv": "^1.0.0-beta.5",
+    "@antv/gatsby-theme-antv": "^1.0.0-beta.8",
     "@commitlint/cli": "^8.2.0",
     "@commitlint/config-angular": "^8.2.0",
     "@types/jest": "^25.2.1",

diff --git a/site/pages/docs.less b/site/pages/docs.less
@@ -0,0 +1,42 @@
+pre[class*="language-"] {
+  background-color: rgba(0, 0, 0, 0.03);
+}
+
+code[class*="language-"] {
+  background: none;
+}
+
+code.language-sign,
+pre.language-sign {
+  background: #e6f7ff;
+}
+
+pre.language-sign {
+  border: 1px solid #91d5ff;
+}
+
+p,
+li {
+  color: rgba(0, 0, 0, 0.68);
+}
+
+table,
+ul li {
+  color: rgba(0, 0, 0, 0.68);
+}
+
+table th,
+table td {
+  padding: 6px 12px;
+}
+
+table img {
+  max-height: 100px;
+}
+
+table td:first-child {
+  width: 20%;
+  font-weight: 500;
+  background: #fcfcfc;
+  color: rgba(0, 0, 0, .85);
+}
diff --git a/site/pages/index.less b/site/pages/index.less
@@ -1,3 +1,5 @@
+@import './docs.less';
+
 html {
   scroll-behavior: auto;
 }
@@ -23,5 +25,4 @@ html {
       margin-top: 60px !important;
     }
   }
-}
-
+}