api doc check

doc/api/axis.md

@@ -54,13 +54,13 @@ g2 `chart.axis()` 方法使用：https://antv.alipay.com/zh-cn/g2/3.x/api/chart.
 ### 3、position 	*'top'|'bottom'|'left'|'right'*
 当前坐标轴的摆放位置。
 
-### 4、title 	*Object*
-当前坐标轴标题的样式配置。
+### 4、title 	*Object | null*
+设置坐标轴标题的显示样式。如果该属性值为 null 则表示不展示坐标轴标题。
 
-- 样式配置
+通过 `title={true}` 渲染坐标轴标题。通过以下配置对标题进行个性化配置：参考[绘图属性](./graphic.md)
 
 ```javascript
-const axisConfig = {
+const title = {
   autoRotate: {Boolean}, // 是否需要自动旋转，默认为 true
   offset: {Number}, // 设置标题 title 距离坐标轴线的距离
   textStyle: {
@@ -73,9 +73,7 @@ const axisConfig = {
   position: 'start' || 'center' || 'end', // 标题的位置，**新增**
 }
 ```
-
-- title显示文本配置
-当需要配置坐标轴标题文本时，在该轴的 scale 中设置 alias 属性，如下所示，更多 scale 设置请查看 scale。
+提示：当需要配置坐标轴标题文本时，在该轴的 scale 中设置 alias 属性，如下所示，更多 scale 设置请查看 scale。
 
 ```jsx
 const scale = {
@@ -84,11 +82,13 @@ const scale = {
   }
 };
 
-<Chart scale={scale} />
+<Chart scale={scale} >
+  <Axis name="sold" title={title}/>
+</Chart>
 ```
 
-### 5、line 	*Object*
-当前坐标轴轴线的样式配置。
+### 5、line 	*Object | null*
+设置坐标轴线的样式，包括线的颜色、粗细等。如果该属性值为 null 则表示不展示坐标轴线。样式设置细节参考[绘图属性](./graphic.md)
 
 ```javascript
 //可配置样式
@@ -100,79 +100,98 @@ const scale = {
 }
 ```
 
-### 6、tickLine 	*Object*
-当前坐标轴刻度线的样式配置。
+### 6、tickLine 	*Object | null*
+设置坐标轴的刻度线。如果该属性值为 null 则表示不展示。
 
 ```javascript
 //可配置样式
-{
+const tickLine = {
   lineWidth: 1, // 刻度线宽
   stroke: '#ccc', // 刻度线的颜色
   length: 5, // 刻度线的长度, **原来的属性为 line**,可以通过将值设置为负数来改变其在轴上的方向
 }
 ```
 
-- 刻度线个数、范围、内容可以通过该轴的 scale 配置，如下所示，更多 scale 配置请查看 scale。
+提示：刻度线个数、范围、内容可以通过该轴的 scale 配置，如下所示，更多 scale 配置请查看 scale。
 
 ```jsx
 const scale = {
   sales:{
-    min:0,//定义数值范围的最小值
-	max:10000,//定义数值范围的最大值
-    ticks:[100, 1000, 2000, 3000],//用于指定坐标轴上刻度点的文本信息，当用户设置了 ticks 就会按照 ticks 的个数和文本来显示。
-	tickInterval:1000,//用于指定坐标轴各个标度点的间距，是原始数据之间的间距差值，tickCount 和 tickInterval 不可以同时声明。
-	tickCount:10,//定义坐标轴刻度线的条数，默认为 5
+    min: 0, // 定义数值范围的最小值
+    max: 10000, // 定义数值范围的最大值
+    ticks: [100, 1000, 2000, 3000], // 用于指定坐标轴上刻度点的文本信息，当用户设置了 ticks 就会按照 ticks 的个数和文本来显示。
+    tickInterval: 1000, // 用于指定坐标轴各个标度点的间距，是原始数据之间的间距差值，tickCount 和 tickInterval 不可以同时声明。
+    tickCount: 10, // 定义坐标轴刻度线的条数，默认为 5
   }
 };
 
-<Chart scale={scale} />
+<Chart scale={scale} >
+  <Axis name="sold" tickLine={tickLine}/>
+</Chart>
 ```
-
 <span id="label"></span>
 
-### 7、label 	*Object*
-当前坐标轴刻度文本的样式配置。
-可配置值有:
+### 7、label 	*Object | null*
+设置坐标轴文本的样式。如果该属性值为 null 则表示不展示坐标轴文本。
 
 ```javascript
-{
-  offset: {Number}, // 设置坐标轴文本 label 距离坐标轴线的距离
+const label = {
+  offset: {number}, // 数值，设置坐标轴文本 label 距离坐标轴线的距离
+  // 设置文本的显示样式，还可以是个回调函数，回调函数的参数为该坐标轴对应字段的数值
   textStyle: {
-  textAlign: 'center', // 文本对齐方向，可取值为： start middle end
-  fill: '#404040', // 文本的颜色
-  fontSize: '12', // 文本大小
-  fontWeight: 'bold', // 文本粗细
-  rotate: 30,
-  textBaseline: 'top' // 文本基准线，可取 top middle bottom，默认为middle
-  } || {Function}, // 支持回调
-  autoRotate: {Boolean} // 是否需要自动旋转，默认为 true
-  formatter: {Function}, // 回调函数，用于格式化坐标轴上显示的文本信息
-  htmlTemplate: {Function}, // 使用 html 自定义 label
+    textAlign: 'center', // 文本对齐方向，可取值为： start center end
+    fill: '#404040', // 文本的颜色
+    fontSize: '12', // 文本大小
+    fontWeight: 'bold', // 文本粗细
+    rotate: 30, 
+    textBaseline: 'top' // 文本基准线，可取 top middle bottom，默认为middle
+  } | (text) => {
+    // text: 坐标轴对应字段的数值
+  }, 
+  autoRotate: {boolean}, // 文本是否需要自动旋转，默认为 true
+  /**
+   * 用于格式化坐标轴上显示的文本信息的回调函数
+   * @param  {string} text  文本值
+   * @param  {object} item  该文本值对应的原始数据记录
+   * @param  {number} index 索引值
+   * @return {string}       返回格式化后的文本值
+   */
+  formatter(text, item, index) {},
+  /**
+   * 使用 html 渲染文本
+   * @param  {string} text  文本值
+   * @param  {object} item  该文本值对应的原始数据记录
+   * @param  {number} index 索引值
+   * @return {string}       返回 html 字符串
+   */
+  htmlTemplate(text, item, index) {}
 }
 ```
 
-- label显示文本等配置也可以通过该轴的 scale 配置，如下所示，更多 scale 配置请查看 scale。
+提示：label显示文本等配置也可以通过该轴的 scale 配置，如下所示，更多 scale 配置请查看 scale。
 
 ```jsx
 const scale = {
-  sales:{
-    min:0,//定义数值范围的最小值
-	max:10000,//定义数值范围的最大值
-    ticks:[100, 1000, 2000, 3000],//用于指定坐标轴上刻度点的文本信息，当用户设置了 ticks 就会按照 ticks 的个数和文本来显示。
-	tickInterval:1000,//用于指定坐标轴各个标度点的间距，是原始数据之间的间距差值，tickCount 和 tickInterval 不可以同时声明。
-	tickCount:10,//定义坐标轴刻度线的条数，默认为 5
+  sales: {
+    min:0, // 定义数值范围的最小值
+    max:10000, // 定义数值范围的最大值
+    ticks:[100, 1000, 2000, 3000], // 用于指定坐标轴上刻度点的文本信息（label），当用户设置了 ticks 就会按照 ticks 的个数和文本来显示。
+    tickInterval: 1000, // 用于指定坐标轴各个标度点的间距，是原始数据之间的间距差值，tickCount 和 tickInterval 不可以同时声明。
+    tickCount: 10, // 定义坐标轴刻度线的条数，默认为 5
   }
 };
 
-<Chart scale={scale} />
+<Chart scale={scale} >
+  <Axis name="sold" label={label}/>
+</Chart>
 ```
 
 ### 8、grid 	* Object | null*
-当前坐标轴网格线的样式配置。当 `grid={null}` 时，则不现实网格线。
-
+设置坐标轴网格线的样式，网格线与坐标轴线垂直。如果该属性值为 null 则表示不展示。
+更多参考[绘图属性](./graphic.md)
 ```javascript
 //可配置样式
-{
+const grid = {
   align: 'center', // 网格顶点从两个刻度中间开始
   type: 'line' || 'polygon', // 网格的类型
   lineStyle: {
@@ -186,15 +205,19 @@ const scale = {
 
 ### 9、subTickCount 	*Number*
 当前坐标轴次刻度线个数。
+```javascript
+<Axis subTickCount={2} />// 设置次刻度线的个数，数值类型
+```
 
 ### 10、subTickLine 	*Object*
 当前坐标轴次刻度线样式配置。
 ```javascript
 //可配置样式
-{
-  lineWidth: 1, // 子刻度线宽
-  stroke: '#ddd', // 子刻度线颜色
-  length: 3, // 自刻度线的长度
+const subTickLine = {
+  lineWidth: 1, // 次刻度线宽
+  stroke: '#ddd', // 次刻度线颜色
+  strokeOpacity: 0.5, // 次刻度线颜色的透明度
+  length: 3 // 次刻度线的长度，可以为负值（表示反方向渲染）
 }
 ```
 
@@ -208,7 +231,7 @@ const scale = {
   sales:{
     type:"linear",
     min:0,
-	max:1000,
+    max:1000,
   },
 }
 <Chart scale={scale}>

doc/api/bizcharts.md

@@ -93,3 +93,6 @@ const Util = {
 };
 ```
 
+## 9、[绘图属性](./graphic.md)
+
+

doc/api/chart.md

@@ -30,66 +30,68 @@
 
 ## 属性
 ### 1、forceFit		* Boolean *
-设置图表的宽度是否自适应，设置为 true，则图表 chart 会继承父元素的宽度，用户设置的 width 则不生效。
-默认值: false
+图表的宽度自适应开关，默认为 false，设置为 true 时表示自动取 dom（实例容器）的宽度。
 
 ### 2、width		* Number *
 指定图表的宽度，默认单位为 'px'，当 *forceFit: true* 是宽度不生效。
 
 ### 3、height		* Number(必填) *
-指定图表的高度，默认单位为 'px'。
+指定图表的高度，单位为 'px'。
+
+> 宽和高未指定时，默认为 500px
 
 <span id="data"></span>
 
 ### 4、data	* Array/DataSet *
-图表数据源，是一个包含 JSON 对象的数组或者 DataView 对象。
+设置图表的数据源，`data` 是一个包含 JSON 对象的数组或者 DataSet.View 对象。
 具体参见 [数据](../tutorial/data.md)
 
 <span id="scale"></span>
 
 ### 5、scale		* Object *
-> (fieldName: string, scaleConfig: object) | (scaleConfig: object)
-图表数据源相关的比例尺信息，*scaleConfig* 可配置属性如下。
+配置数据比例尺，该配置会影响数据在图表中的展示方式。
 ```jsx
-scale={{
-  fieldName:'sales',
-  //scaleConfig
-  {
-	type: 'identity' | 'linear' | 'cat' | 'time' | 'timeCat' | 'log' | 'pow', // 指定数据类型
-	alias: string, // 数据字段的别名
-	formatter: function, // 格式化文本内容
-	range: array, // 输出数据的范围，默认[0, 1]，格式为 [min, max]，min 和 max 均为 0 至 1 范围的数据。
-	tickCount: number, // 设置坐标轴上刻度点的个数
-	ticks: array, // 用于指定坐标轴上刻度点的文本信息，当用户设置了 ticks 就会按照 ticks 的个数和文本来显示
-	sync: boolean // 当 chart 存在不同数据源的 view 时，用于统一相同数据属性的值域范围
+const scale = {
+  'sales': {
+    type: 'identity' | 'linear' | 'cat' | 'time' | 'timeCat' | 'log' | 'pow', // 指定数据类型
+    alias: string, // 数据字段的别名
+    formatter: () => {}, // 格式化文本内容
+    range: array, // 输出数据的范围，默认[0, 1]，格式为 [min, max]，min 和 max 均为 0 至 1 范围的数据。
+    tickCount: number, // 设置坐标轴上刻度点的个数
+    ticks: array, // 用于指定坐标轴上刻度点的文本信息，当用户设置了 ticks 就会按照 ticks 的个数和文本来显示
+    sync: boolean // 当 chart 存在不同数据源的 view 时，用于统一相同数据属性的值域范围
   }
-}}
+};
+<Chart data={data} scale={scale} />
 ```
-
-!注意：除了以上属性外，不同的 type 还对应有各自的可配置属性，详见 [Scale 度量 API](./scale.md);
+> !注意：除了以上属性外，不同的 type 还对应有各自的可配置属性，详见 [Scale 度量 API](./scale.md);
 
 ### 6、placeholder		* string *
-图表source为空时显示的内容。
+图表source为空时显示的内容，未设置该属性时为G2 默认样式。`<Chart placeholder />` 则为Bizcharts 定义的无数据提示。
 默认值:  `<div style={{ position: 'relative', top: '48%', textAlign: 'center' }}>暂无数据</div>` ;会在图表区域的中间显示 "暂无数据" 。
 
 <span id="padding"></span>
 
-### 7、padding		* Object／Number／Array *
+### 7、padding		* Object | Number | Array *
 图表内边距。
 有如下三种配置格式。
 ```jsx
 //有时候坐标轴、图例等绘图区域外的组件显示不全时，可以通过调整图表各个方向的 padding 来调整最终效果
-padding={[ 20, 30, 20, 30]}
-padding={20}
-padding={{ top: 20, right: 30, bottom: 20, left: 30 }}
+<Chart padding={[ 20, 30, 20, 30]} />
+<Chart padding={20} />
+<Chart padding={{ top: 20, right: 30, bottom: 20, left: 30 }} />
+<Chart padding="auto" />
+<Chart padding={[20, 'auto', 30, 'auto']} />
+<Chart padding={['20%', '30%']} />
 ```
+- padding 为数字以及数组类型时使用方法同 CSS 盒模型。
+- padding 中存在 'auto'，时会自动计算边框，目前仅考虑 axis 和 legend 占用的边框。
 
 ### 8、animate		* Boolean *
-是否执行动画。
-默认值: true
+图表动画开关，默认为 true，即开启动画。
 
 ### 9、background		* Object *
-图表背景样式设置。
+设置图表整体的边框和背景样式，是一个对象，包含如下属性：
 ```javascript
 //可配置样式有
 {
@@ -104,7 +106,7 @@ padding={{ top: 20, right: 30, bottom: 20, left: 30 }}
 ```
 
 ### 10、plotBackground		* Object *
-图表背景样式设置。
+图表绘图区域的边框和背景样式，是一个对象，包含如下属性：
 ```javascript
 //可配置样式有
 {
@@ -131,12 +133,12 @@ Array:[[fieldString1, callback1], [fieldString2, callback2]]
 <Chart filter={[['x', (val) => {return val > 20;}]]}/>
 ```
 ### 13、className   *String*
-设置图标最外层div的类名。
+设置图表最外层div的类名。
 ``` jsx
 <Chart className="chart1" />
 ```
 ### 14、style   *Object*
-设置图标最外层div的样式。
+设置图表最外层div的样式。
 ``` jsx
 const style={fontSize: '12'}
 <Chart style={style} />
@@ -363,3 +365,4 @@ Mouseenter, Mousemove, Mouseleave, Click, Dblclick, Mousedown, Mouseup, Touchsta
 <Chart onPointMouseenter={function(ev){//some code}}/>
 ```
 
+> [在线DEMO](https://alibaba.github.io/BizCharts/demo-detail.html?code=/demo/line/series)