docs(readme,api): readme,api

readme add twitter, api
5 years ago · 70b8494403
2 changed files with 378 additions and 37 deletions
--- a/README.md
+++ b/README.md
@ -3,6 +3,9 @@
 ![logo](/docs/.vuepress/public/img/logo_text.png)

 [![Join the chat at https://gitter.im/mengshukeji/Luckysheet](https://badges.gitter.im/mengshukeji/Luckysheet.svg)](https://gitter.im/mengshukeji/Luckysheet?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+<a href="https://twitter.com/intent/follow?screen_name=luckysheet">
+        <img src="https://img.shields.io/twitter/follow/luckysheet?style=social&logo=twitter"
+            alt="follow on Twitter"></a>

 </div>

--- a/docs/zh/guide/api.md
+++ b/docs/zh/guide/api.md
@ -9,7 +9,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 ## 单元格操作

-### getCellValue(row, column [,setting])
+### getCellValue(row, column [,setting])<div id='getCellValue'></div>

 - **参数**：

@ -504,10 +504,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 			[
 				{
 					"v": "vaule1",
-					"ct": {
-						"fa": "General",
-						"t": "g"
-					},
+					"ct": { "fa": "General", "t": "g" },
 					"m": "vaule1",
 					"bg": "rgba(255,255,255)",
 					"bl": 0,
@ -520,10 +517,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 				},
 				{
 					"v": "value3",
-					"ct": {
-						"fa": "General",
-						"t": "g"
-					},
+					"ct": { "fa": "General", "t": "g" },
 					"m": "value3",
 					"bg": "rgba(255,255,255)",
 					"bl": 0,
@ -538,10 +532,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 			[
 				{
 					"v": "vaule2",
-					"ct": {
-						"fa": "General",
-						"t": "g"
-					},
+					"ct": { "fa": "General", "t": "g" },
 					"m": "vaule2",
 					"bg": "rgba(255,255,255)",
 					"bl": 0,
@ -554,10 +545,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 				},
 				{
 					"v": "value4",
-					"ct": {
-						"fa": "General",
-						"t": "g"
-					},
+					"ct": { "fa": "General", "t": "g" },
 					"m": "value4",
 					"bg": "rgba(255,255,255)",
 					"bl": 0,
@ -640,6 +628,31 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 	复制指定工作表指定单元格区域的数据，返回`json`格式的数据

+- **示例**:
+
+	- 当前选区为"A1:B2"，首行为标题取得json
+		
+		`luckysheet.getRangeJson(true)`
+		
+		则返回结果为：
+		```json
+		[
+			{ "A": "value1", "B": "value3" },
+			{ "A": "value2", "B": "value4" }
+		]
+		```
+
+	- 当前选区为"A1:B2"，首行不为标题取得json
+		
+		`luckysheet.getRangeJson(false)`
+		
+		则返回结果为：
+		```json
+		[
+			{ "value1": "value2", "value3": "value4" }
+		]
+		```
+
 ------------

 ### getRangeArray(dimensional [,setting])
@ -652,7 +665,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 		
 		+ `"oneDimensional"`: 一维数组
 		+ `"twoDimensional"`: 二维数组
-		+ `"custom"`: 自定义维数组
+		+ `"custom"`: 自定义行列数的二维数组
 	- {PlainObject} [setting]: 可选参数
 		+ {Number} [row]: `dimensional`为`custom`的时候设置，多维数组的行数
 		+ {Number} [column]: `dimensional`为`custom`的时候设置，多维数组的列数
@ -661,10 +674,80 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 - **说明**：
 	
-	复制指定工作表指定单元格区域的数据，返回一维、二维或者自定义维数组格式的数据。
+	复制指定工作表指定单元格区域的数据，返回一维、二维或者自定义行列数的二维数组的数据。

 	特别注意，只有在`dimensional`设置为`custom`的时候，才需要设置`setting`中的`row`和`column`

+- **示例**:
+
+	- 当前选区为"A1:B2"，一维数组
+		
+		`luckysheet.getRangeArray('oneDimensional')`
+		
+		则返回结果为：
+		```json
+		["value1","value3","value2","value4"]
+		```
+
+	- 当前选区为"A1:B2"，二维数组
+		
+		`luckysheet.getRangeArray('twoDimensional')`
+		
+		则返回结果为：
+		```json
+		[
+			[ "value1", "value3" ],
+			[ "value2", "value4" ]
+		]
+		```
+
+	- 当前选区为"A1:C5"，由 'value1'到'value15'的值组成，得到3
+	行2列的二维数组数据
+		
+		`luckysheet.getRangeArray('custom', { row: 3, column: 2 })`
+		
+		则返回结果为：
+		```json
+		[
+			[
+				{
+					"m": "value1",
+					"ct": { "fa": "General", "t": "g" },
+					"v": "value1"
+				},
+				{
+					"ct": { "fa": "General", "t": "g" },
+					"v": "value6",
+					"m": "value6"
+				}
+			],
+			[
+				{
+					"ct": { "fa": "General", "t": "g" },
+					"v": "value11",
+					"m": "value11"
+				},
+				{
+					"m": "value2",
+					"ct": { "fa": "General", "t": "g" },
+					"v": "value2"
+				}
+			],
+			[
+				{
+					"ct": { "fa": "General", "t": "g" },
+					"v": "value7",
+					"m": "value7"
+				},
+				{
+					"ct": { "fa": "General", "t": "g" },
+					"v": "value12",
+					"m": "value12"
+				}
+			]
+		]
+		```
+
 ------------

 ### getRangeDiagonal(type [,setting])
@ -676,6 +759,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 		`type`可能的值有：
 		
 		+ `"normal"`: 对角线
+		+ `"anti"`: 反对角线
 		+ `"offset"`: 对角线偏移
 	- {PlainObject} [setting]: 可选参数
 		- {Number} [column]: `type`为`offset`的时候设置，对角偏移的列数
@ -688,6 +772,61 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 	特别注意，只有在`type`设置为`offset`的时候，才需要设置`setting`中的`column`。

+- **示例**:
+
+	- 当前选区为"A1:B2"，对角线
+		
+		`luckysheet.getRangeDiagonal('normal')`
+		
+		则返回结果为：
+		```json
+		[
+			{
+				"m": "value1",
+				"ct": { "fa": "General", "t": "g" },
+				"v": "value1"
+			},
+			{
+				"m": "value4",
+				"ct": { "fa": "General", "t": "g" },
+				"v": "value4"
+			}
+		]
+		```
+
+	- 当前选区为"A1:B2"，反对角线
+		
+		`luckysheet.getRangeDiagonal('anti')`
+		
+		则返回结果为：
+		```json
+		[
+			{
+				"m": "value3",
+				"ct": { "fa": "General", "t": "g" },
+				"v": "value3"
+			},
+			{
+				"m": "value2",
+				"ct": { "fa": "General", "t": "g" },
+				"v": "value2"
+			}
+		]
+		```
+	- 当前选区为"A1:B2"，对角线偏移1列
+		
+		`luckysheet.getRangeDiagonal('offset', { column: 1 })`
+		
+		则返回结果为：
+		```json
+		[
+			{
+				"m": "value3",
+				"ct": { "fa": "General", "t": "g" },
+				"v": "value3"
+			}
+		]
+		```
 ------------

 ### getRangeBoolean([setting])
@ -702,6 +841,20 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	复制指定工作表指定单元格区域的数据，返回布尔值的数据

+- **示例**:
+
+	- 当前选区为"A1:B2"
+		
+		`luckysheet.getRangeBoolean()`
+		
+		则返回结果为：
+		```json
+		[
+			[ false, false ],
+			[ false, false ]
+		]
+		```
+
 ------------

 ### setRangeShow(range [,setting])<div id='setRangeShow'></div>
@ -757,6 +910,52 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	将一个单元格数组数据赋值到指定的区域，数据格式同`getRangeValue`方法取到的数据。

+- **示例**:
+
+     + 赋值到当前选区
+      
+		```js
+		const data = [
+				[
+					{
+						"m": "value1",
+						"ct": {
+							"fa": "General",
+							"t": "g"
+						},
+						"v": "value1"
+					},
+					{
+						"m": "value3",
+						"ct": {
+							"fa": "General",
+							"t": "g"
+						},
+						"v": "value3"
+					}
+				],
+				[
+					{
+						"m": "value2",
+						"ct": {
+							"fa": "General",
+							"t": "g"
+						},
+						"v": "value2"
+					},
+					{
+						"m": "value4",
+						"ct": {
+							"fa": "General",
+							"t": "g"
+						},
+						"v": "value4"
+					}
+				]
+			]
+		luckysheet.setRangeValue(data)
+		```
+
 ------------

 ### setRangeFormat(attr, value [,setting])
@ -791,9 +990,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 - **示例**:

   - 设置当前工作表`"A1:B2"`范围的单元格文本加粗
-   `luckysheet.setRangeFormat("bl", 1, {range:"A1:B2"})`
+		
+		`luckysheet.setRangeFormat("bl", 1, {range:"A1:B2"})`
   - 设置第二个工作表的`"B2"`和`"C4:D5"`范围的单元格背景为红色
-   `luckysheet.setRangeFormat("bg", "#ff0000", {range:["B2","C4:D5"], order:1})`
+		
+		`luckysheet.setRangeFormat("bg", "#ff0000", {range:["B2","C4:D5"], order:1})`

 ------------

@ -825,6 +1026,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 ### setRangeMerge(type [,setting])

 - **参数**：
+	
 	- {String} [type]: 合并单元格类型
 	
 		`type`可能的值有：
@ -832,6 +1034,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 		+ `"all"`: 全部合并，区域内所有单元格合并成一个大的单元格
 		+ `"horizontal"`: 水平合并，区域内在同一行的单元格合并成一个单元格
 		+ `"vertical"`: 垂直合并，区域内在同一列的单元格合并成一个单元格
+	
 	- {PlainObject} [setting]: 可选参数
    	+ {Array | Object | String} [range]: 选区范围,支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，允许多个选区组成的数组；默认为当前选区
    	+ {Number} [order]: 工作表索引；默认值为当前工作表索引
@ -841,6 +1044,36 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	为指定索引的工作表，选定的范围设定合并单元格

+- **示例**:
+
+	- 当前选区 'A1:B2' 设置为合并单元格，类型为全部合并
+		
+		`luckysheet.setRangeMerge("all")`
+		得到 'A1:B1' 的数据为：
+		```json
+		[
+			[
+				{
+					"m": "value1",
+					"ct": { "fa": "General", "t": "g" },
+					"v": "value1",
+					"mc": { "r": 0, "c": 0, "rs": 2, "cs": 2 }
+				},
+				{
+					"mc": { "r": 0, "c": 0 }
+				}
+			],
+			[
+				{
+					"mc": { "r": 0, "c": 0 }
+				},
+				{
+					"mc": { "r": 0, "c": 0 }
+				}
+			]
+		]
+		```
+
 ------------

 ### cancelRangeMerge( [setting])
@ -856,6 +1089,12 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	为指定索引的工作表，选定的范围取消合并单元格

+- **示例**:
+
+	- 当前选区 'A1:B2' 已为合并单元格，现在要取消合并
+		
+		`luckysheet.cancelRangeMerge()`
+		
 ------------

 ### setRangeSort(type [,setting])
@ -1004,10 +1243,10 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
      `luckysheet.setRangeConditionalFormatDefault("lastPercent",{ type: 'value', content: [15] })`
 	
 	- 突出显示高于平均值的单元格
-      luckysheet.setRangeConditionalFormatDefault("AboveAverage",{ type: 'value', content: ['AboveAverage'] })`
+      `luckysheet.setRangeConditionalFormatDefault("AboveAverage",{ type: 'value', content: ['AboveAverage'] })`
 	
 	- 突出显示低于平均值的单元格
-	  luckysheet.setRangeConditionalFormatDefault("SubAverage",{ type: 'value', content: ['SubAverage'] })`
+	  `luckysheet.setRangeConditionalFormatDefault("SubAverage",{ type: 'value', content: ['SubAverage'] })`

 ------------

@ -1122,6 +1361,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	为指定索引的工作表，选定的范围开启条件格式，返回开启条件格式后的数据。

+- **示例**:
+
+    - 当前选区范围开启条件格式，显示渐变色
+      `luckysheet.setRangeConditionalFormat("dataBar", { format: ["#63c384", "#ffffff"] })`
+
 ------------

 ### deleteRangeConditionalFormat(itemIndex [,setting])
@ -1142,7 +1386,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 - **示例**:

    - 删除第三个条件格式规则
-      `luckysheet.editRangeConditionalFormat(2)`
+      `luckysheet.deleteRangeConditionalFormat(2)`
    
 ------------

@ -1159,6 +1403,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	清除指定工作表指定单元格区域的内容，返回清除掉的数据，不同于删除选区的功能，不需要设定单元格移动情况

+- **示例**:
+
+    - 清空当前选区内容
+      `luckysheet.clearRange()`
+    
 ------------

 ### deleteRange(move [,setting])
@ -1180,6 +1429,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	删除指定工作表指定单元格区域，返回删除掉的数据，同时，指定是右侧单元格左移还是下方单元格上移

+- **示例**:
+
+    - 删除当前选区并且在删除后，右侧单元格左移
+      `luckysheet.deleteRange('left')`
+    
 ------------

 ### insertRange(move [,setting])
@ -1208,6 +1462,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	在指定工作表指定单元格区域，赋值单元格数据，或者新建一块空白区域，返回data数据，同时，指定活动单元格右移或者下移

+- **示例**:
+
+    - 当前选区位置插入空白单元格，并且插入后当前选区单元格右移
+      `luckysheet.insertRange('right')`
+    
 ------------

 ### matrixOperation(type [,setting])
@ -1237,6 +1496,20 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	指定工作表指定单元格区域的数据进行矩阵操作，返回操作成功后的结果数据

+- **示例**:
+
+    - 当前选区上下翻转
+    		
+		`luckysheet.matrixOperation('flipUpDown')`
+
+		原来的选区复制为二维数组：
+		
+		`[["value1","value3"],["value2","value4"]]`
+		
+		上下翻转后选区复制为二维数组：
+		
+		`[["value2","value4"],["value1","value3"]]`
+    
 ------------

 ### matrixCalculation(type, number [,setting])
@ -1253,9 +1526,6 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 		+ `"power"`: 次方
 		+ `"root"`: 次方根
 		+ `"log"`: log
-		+ `"removeDuplicateByRow"`: 按行删除重复值
-		+ `"removeDuplicateByColumn"`: 按列删除重复值
-		+ `"newMatrix"`: 生产新矩阵
 	- {Number} [number]: 计算数值，如: 2
 	- {PlainObject} [setting]: 可选参数
    	+ {Array | Object | String} [range]: 选区范围,支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，只能为单个选区；默认为当前选区
@ -1266,6 +1536,20 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	
 	指定工作表指定单元格区域的数据进行矩阵计算，返回计算成功后的结果数据

+- **示例**:
+
+    - 当前选区所有单元格值加2
+    		
+		`luckysheet.matrixCalculation('plus', 2)`
+
+		原来的选区复制为二维数组：
+		
+		`[[1,2],[3,4]]`
+		
+		加2后选区复制为二维数组：
+		
+		`[[3,4],[5,6]]`
+    
 ------------

 ## 工作表操作
@ -1509,7 +1793,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 - **说明**：
 	
-	初始化一个luckysheet，可包含多个工作表，参考 [配置列表](/zh/guide/config.html)
+	初始化一个Luckysheet，可包含多个工作表，参考 [配置列表](/zh/guide/config.html)

 ------------

@ -1526,6 +1810,19 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 ------------

+### destroy([setting])
+
+- **参数**：
+	
+	- {PlainObject} [setting]: 可选参数
+		+ {Function} [success]: 表格释放成功后的回调函数
+
+- **说明**：
+	
+	删除并释放表格
+
+------------
+
 ### getScreenshot([setting])

 - **参数**：
@ -1682,12 +1979,43 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	celldata => data ，celldata一维数组数据转化成表格所需二维数组

 ------------
+
 ## 旧版API

 ::: warning
 为保持兼容性，仍然支持旧版API，但是已不推荐使用。
 :::

+### getcellvalue([r] [,c] [,data] [,type])
+- **参数**：
+	- {Number} [r]:单元格所在行数；可选值；从0开始的整数，0表示第一行
+	- {Number} [c]:单元格所在列数；可选值；从0开始的整数，0表示第一列
+	- {Array} [data]:表数据，二维数组；可选值；默认值为当前表格数据
+	- {String} [type]:单元格属性值；可选值；默认值为'v',表示获取单元格的实际值
+- **说明**：
+
+	此方法为获取单元格的值。
+
+	- luckysheet.getcellvalue()：返回当前工作表的所有数据；
+	- luckysheet.getcellvalue(0)：返回当前工作表第1行数据；
+	- luckysheet.getcellvalue(null,0)：返回当前工作表第1列数据；
+	- luckysheet.getcellvalue(0,0)：返回当前工作表第1行第1列单元格的数据的v值；
+	- luckysheet.getcellvalue(1,1,null,'m'): 返回指定data数据的第2行第2列单元格的原始值。
+	
+	特殊情况：单元格格式为yyyy-MM-dd，type为'v'时会强制取'm'显示值
+
+	> 推荐使用新API： <a href='#getCellValue'>getCellValue</a>
+
+
+
+### getluckysheetfile()
+- **说明**：
+
+	返回所有表格数据结构的一维数组`luckysheetfile`
+
+	> 推荐使用新API： [getLuckysheetfile](#getLuckysheetfile())
+------------
+
 ### getconfig()
 - **说明**：

@ -1727,6 +2055,23 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 ------------

+## setcellvalue(r, c, d, v)
+- **参数**：
+	- {Number} [r]：单元格所在行数；从0开始的整数，0表示第一行。
+	- {Number} [c]：单元格所在列数；从0开始的整数，0表示第一列。
+	- {Array} [d]：表数据；可选值；二维数组。
+	- {Object | String | Number} [v]：要设置的值；可为对象，对象是是要符合单元格对象格式。
+- **说明**：
+
+	设置某个单元格的值。可配合`luckysheet.jfrefreshgrid()`刷新查看单元格值改变。
+
+	```js
+	luckysheet.setcellvalue(0, 0, luckysheet.flowdata(), 'abc');
+	luckysheet.jfrefreshgrid();
+	```
+
+------------
+
 ## jfrefreshgrid()
 - **说明**：

@ -1734,7 +2079,6 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

 	> 推荐使用新API： [refresh](#refresh([setting]))
 	
-
 ------------

 ## setluckysheet_select_save(v)
@ -1788,9 +2132,3 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 	二维数组数据转化成 `{r, c, v}` 格式 一维数组

 	> 推荐使用新API：<a href='#transToCellData'>transToCellData</a>
-
------------
-## destroy()
- **说明**：
-	
-	删除并释放表格