Merge pull request #404 from flowerField/master

add api
5 years ago · 18f13af2d8
3 changed files with 348 additions and 0 deletions
--- a/docs/guide/api.md
+++ b/docs/guide/api.md
@ -728,6 +728,160 @@ Use note:

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

+
+### getRangeWithFlatten()
+ 
+- **Explanation**：
+
+	Returns an array representing the positions of all cells in the specified area, which is different from the getrange method, which organizes the data of the selection by cell (rather than a continuous area).
+
+- **Usage**:
+
+	- Select the specified area in the table, and then execute
+		
+		`luckysheet.getRange()`
+		
+		The returned result is:
+		```json
+		[
+			{"row":[0,0],"column":[0,2]},
+			{"row":[1,1],"column":[0,0]},
+			{"row":[3,3],"column":[0,0]}
+		]
+		```
+		Where，{"row":[0,0],"column":[0,2]} denote a whole continuous region.
+
+	- Select the area above in the table and execute
+		
+		`luckysheet.getRangeWithFlatten()`
+		
+		The returned result is:
+		```json
+		[
+			{"r":0,"c":0},
+			{"r":0,"c":1},
+			{"r":0,"c":2},
+			{"r":1,"c":0},
+			{"r":3,"c":0}
+		]
+		```
+
+------------
+
+
+### getRangeValuesWithFlatte()
+ 
+- **Explanation**：
+
+	Returns an array of objects representing the contents of all cells in a specified range
+
+- **Usage**:
+
+	- Select the specified area in the table, and then execute
+		
+		`luckysheet.getRange()`
+		
+		The returned result is:
+		```json
+		[
+			{"row":[0,0],"column":[0,2]},
+			{"row":[1,1],"column":[0,0]},
+			{"row":[3,3],"column":[0,0]}
+		]
+		```
+		Where，{"row":[0,0],"column":[0,2]} denote a whole continuous region.
+
+	- Select the area above in the table and execute
+		
+		`luckysheet.getRangeValuesWithFlatte()`
+		
+		The returned result is:
+		```json
+		[
+			{
+				"bg": null,
+				"bl": 0,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1,
+				"v": 1,
+				"ct": {
+					"fa": "General",
+					"t": "n"
+				},
+				"m": "1"
+			},
+			{
+				"bg": null,
+				"bl": 0,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1,
+				"v": 2,
+				"ct": {
+					"fa": "General",
+					"t": "n"
+				},
+				"m": "2"
+			},
+			{
+				"bg": null,
+				"bl": 0,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1,
+				"v": 3,
+				"ct": {
+					"fa": "General",
+					"t": "n"
+				},
+				"m": "3"
+			},
+			{
+				"v": "Background",
+				"ct": {
+					"fa": "General",
+					"t": "g"
+				},
+				"m": "Background",
+				"bg": null,
+				"bl": 1,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1
+			},
+			{
+				"v": "Border",
+				"ct": {
+					"fa": "General",
+					"t": "g"
+				},
+				"m": "Border",
+				"bg": null,
+				"bl": 1,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1
+			}
+		]
+		```
+------------
+
 ### getRangeAxis()
 
 - **Explanation**：
--- a/docs/zh/guide/api.md
+++ b/docs/zh/guide/api.md
@ -718,6 +718,159 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开

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

+### getRangeWithFlatten()
+ 
+- **说明**：
+
+	返回表示指定区域内所有单元格位置的数组，区别getRange方法，该方法以cell单元格(而非某块连续的区域)为单位来组织选区的数据。
+
+- **示例**:
+
+	- 在表格中选择指定的区域，然后执行
+		
+		`luckysheet.getRange()`
+		
+		则返回结果为：
+		```json
+		[
+			{"row":[0,0],"column":[0,2]},
+			{"row":[1,1],"column":[0,0]},
+			{"row":[3,3],"column":[0,0]}
+		]
+		```
+		其中，{"row":[0,0],"column":[0,2]} 表示的是一整块连续的区域。
+
+	- 在表格中选择上面的区域，然后执行
+		
+		`luckysheet.getRangeWithFlatten()`
+		
+		则返回结果为：
+		```json
+		[
+			{"r":0,"c":0},
+			{"r":0,"c":1},
+			{"r":0,"c":2},
+			{"r":1,"c":0},
+			{"r":3,"c":0}
+		]
+		```
+
+------------
+
+### getRangeValuesWithFlatte()
+ 
+- **说明**：
+
+	返回表示指定区域内所有单元格内容的对象数组
+
+- **示例**:
+
+	- 在表格中选择指定的区域，然后执行
+		
+		`luckysheet.getRange()`
+		
+		则返回结果为：
+		```json
+		[
+			{"row":[0,0],"column":[0,2]},
+			{"row":[1,1],"column":[0,0]},
+			{"row":[3,3],"column":[0,0]}
+		]
+		```
+		其中，{"row":[0,0],"column":[0,2]} 表示的是一整块连续的区域。
+
+	- 在表格中选择上面的区域，然后执行
+		
+		`luckysheet.getRangeValuesWithFlatte()`
+		
+		则返回结果为：
+		```json
+		[
+			{
+				"bg": null,
+				"bl": 0,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1,
+				"v": 1,
+				"ct": {
+					"fa": "General",
+					"t": "n"
+				},
+				"m": "1"
+			},
+			{
+				"bg": null,
+				"bl": 0,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1,
+				"v": 2,
+				"ct": {
+					"fa": "General",
+					"t": "n"
+				},
+				"m": "2"
+			},
+			{
+				"bg": null,
+				"bl": 0,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1,
+				"v": 3,
+				"ct": {
+					"fa": "General",
+					"t": "n"
+				},
+				"m": "3"
+			},
+			{
+				"v": "Background",
+				"ct": {
+					"fa": "General",
+					"t": "g"
+				},
+				"m": "Background",
+				"bg": null,
+				"bl": 1,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1
+			},
+			{
+				"v": "Border",
+				"ct": {
+					"fa": "General",
+					"t": "g"
+				},
+				"m": "Border",
+				"bg": null,
+				"bl": 1,
+				"it": 0,
+				"ff": 0,
+				"fs": 11,
+				"fc": "rgb(51, 51, 51)",
+				"ht": 1,
+				"vt": 1
+			}
+		]
+		```
+------------
+
+
 ### getRangeAxis()
 
 - **说明**：
--- a/src/global/api.js
+++ b/src/global/api.js
@ -1592,6 +1592,47 @@ export function getRange() {
    return result;
 }

+/**
+ * 返回表示指定区域内所有单元格位置的数组，区别getRange方法，该方法以cell单元格(而非某块连续的区域)为单位来组织选区的数据
+ * @param   {Array}   range 可选参数，默认为当前选中区域
+ * @returns {Array}   对象数组
+ */
+export function getRangeWithFlatten(range){
+    range = range ||  getRange();
+    
+    let result = [];
+    
+    range.forEach(ele=>{
+        // 这个data可能是个范围或者是单个cell
+        let rs = ele.row;
+        let cs = ele.column;
+        for(let r = rs[0]; r <= rs[1]; r++){
+            for(let c = cs[0]; c <= cs[1]; c++){
+                // r c 当前的r和当前的c
+                result.push({r,c});
+            }
+        }
+    })
+    return result;
+}
+
+/**
+ * 返回表示指定区域内所有单元格内容的对象数组
+ * @param   {Array}   range 可选参数，默认为当前选中区域扁平化后的对象，结构形如[{r:0,c:0},{r:0,c:1}...]
+ * @returns {Array}   对象数组
+ */
+export function getRangeValuesWithFlatte(range){
+    range = range || getRangeWithFlatten();
+    
+    let values = [];
+
+    // 获取到的这个数据不是最新的数据
+    range.forEach(item=> { 
+        values.push(Store.flowdata[item.r][item.c]);
+    });
+    return values;
+}
+

 /**
 * 返回对应当前选区的坐标字符串数组，可能存在多个选区。